SACS: Semantic Addressable CodeSpace

---

⚡ Executive Summary

SACS (Semantic Addressable CodeSpace) is an ultra-high-efficiency, deterministic architecture compilation and causal code slicing engine designed for Autonomous AI Software Engineers and Coding Agents.

Traditional LLM coding agents suffer from quadratic context inflation: dumping thousands of lines of raw source code, bloated directory trees, and massive test traces into the prompt window. This causes hallucinations, lost-in-the-middle degradation, high latency, and exorbitant API bills ($1–$5+ per simple issue).

SACS solves this by treating codebases not as raw text files, but as Compiled Semantic Graphs & Causal AST Address Spaces. Instead of sending whole files or brute-force keyword matches, SACS compiles architectural contracts, computes mathematical causal route proofs, extracts sub-symbol slices, and virtualizes runtime artifacts—slashing context token consumption by 90% to 96% while simultaneously improving patch resolution accuracy.

---

📊 The Paradigm Shift: SACS vs. Traditional Agents

Metric / Dimension	Traditional Agent (SWE-Agent / Aider / Raw)	SACS Architecture
Context Assembly Strategy	Brute-force full file dump or greedy BM25 grep	AST-Level Exact Causal Slicing & Route Proofs
Average Context Tokens / Step	45,000 – 128,000 tokens	2,500 – 6,000 tokens (95% reduction)
Multi-turn Context Explosion	Quadratic growth ($O(N^2)$ prompt cache misses)	Constant-Bounded Task Budget ($O(1)$ bounded)
Test & Execution Traces	Full 5,000–50,000 lines dumped into prompt	SHA-256 Virtualized Artifact Hash & Signals
Architectural Boundaries	Zero awareness; prone to boundary violations	Constitutional Mutation Gate (project.genome.yaml)
Hallucination & Drift Risk	High (confuses irrelevant files & deep layers)	Deterministic (Symbol frontier derived from AST DAG)
Cost per Resolved Patch	~$1.50 – $4.80	~$0.04 – $0.18 (Up to 25x cheaper)

---

🏛️ Core Architectural Pillars

flowchart TD
    subgraph SACS_Compilation ["1. Genome & AST Compilation"]
        G[project.genome.yaml] -->|Compiles| DAG[Architectural Semantic DAG]
        Repo[Source Codebase] -->|AST Parser| PIdx[Python / TS Symbol Index]
    end

    subgraph Task_Routing ["2. Causal Route Proof & Slicing"]
        Task[User Task / Bug Issue] --> Router[Intent & Causal Router]
        DAG --> Router
        PIdx --> Router
        Router -->|Causal Route Proof| Slices[Exact AST Symbol Slices]
    end

    subgraph Token_Optimization ["3. Context Virtualization"]
        Slices --> CtxEngine[Bounded Context Assembler]
        Artifacts[Test Output / Logs] -->|SHA-256 Virtualize| ArtEngine[Artifact Summary Signals]
        CtxEngine --> PromptBundle[Minimal Prompt Bundle < 6k Tokens]
        ArtEngine --> PromptBundle
    end

    subgraph Mutation_Governance ["4. Constitutional Execution"]
        PromptBundle --> LLM[LLM Agent / ADK]
        LLM -->|Proposed Patch| Gate[Constitutional Mutation Gate]
        Gate -->|Invariant Check| Verify[Test Runner & Verification]
        Verify -->|Pass| Finalize[Committed Solution]
    end

Loading

1. 🧬 Declarative Architecture Genome (project.genome.yaml)

Defines explicit domain boundaries, capability contracts, data constraints, invariant rules, and token budgets. SACS compiles this declarative genome into an immutable semantic graph DAG, enforcing clean architecture at compile-time.

2. ⚡ Exact AST Causal Slicing & Proofs (sacs.python_index)

Traverses abstract syntax trees (AST) to compute callers, callees, type definitions, and semantic routes. Rather than sending 1,000 lines of an implementation file, SACS slices out only the relevant class signature, active method, and directly coupled symbol definitions.

3. 🛡️ Constitutional Mutation Gates & Task Ledger (sacs.mutation, sacs.obligations)

Every code modification is subject to constitutional governance:

• Cyclic Dependency Denial: Blocks cross-domain imports that break architectural boundaries.
• Contract Invariance: Ensures public interfaces and contract invariants are preserved.
• Task Obligations: Automatically tracks unfulfilled requirements (e.g., unit test coverage, backward compatibility).

4. 📦 SHA-256 Artifact Hash Virtualization (sacs.artifacts)

Dumping thousands of lines of compiler errors or test outputs destroys LLM reasoning. SACS intercepts subprocess execution, writes full logs to a local artifact store, and feeds the LLM a compact structured virtualization signal containing error digests and specific failing assert locations.

---

🚀 Benchmark & Token Savings Metrics

Live benchmarks running real-world SWE-bench and modular enterprise repositories:

========================================================================================
TASK BENCHMARK: IDEMPOTENCY RETRY POLICY (100k LoC Monolith)
========================================================================================
Approach              Fresh Tokens     Total Cost    Tool Calls    Resolved?   Time (s)
----------------------------------------------------------------------------------------
Vanilla Agentless          100,739        $0.82           5           YES        84.2s
SWE-Agent Baseline         128,400        $1.15           8           YES        96.1s
SACS Engine                  4,905        $0.04           1           YES        18.5s
----------------------------------------------------------------------------------------
SACS ADVANTAGE:      -95.1% Tokens      -95.1% Cost      -80% Turns              4.5x Faster
========================================================================================

---

🛠️ Installation & Quickstart

Prerequisites

• Python 3.11+
• Git

Install SACS

# Clone the repository
git clone https://github.com/Minwsun/IOtokensaver.git
cd IOtokensaver

# Install with development & ADK dependencies
pip install -e .[adk]

🏃 End-to-End Workflow via CLI

# 1. Validate the architecture genome
python -m sacs validate project.genome.yaml

# 2. Compile genome into semantic graph (.sacs/)
python -m sacs compile project.genome.yaml --repo demo_repo

# 3. Create an isolated task ledger
python -m sacs task "Fix duplicate payment when retrying. Keep retry and don't change the public API." --id CHG-081

# 4. Build exact causal sliced context
python -m sacs context .sacs/tasks/CHG-081.json --repo demo_repo

# 5. Check if target file passes constitutional mutation gates
python -m sacs gate .sacs/tasks/CHG-081.json src/payment/retry/payment-retry.policy.ts

# 6. Apply patch deterministically
python -m sacs apply-patch .sacs/tasks/CHG-081.json src/payment/retry/payment-retry.policy.ts replacement.ts

# 7. Verify task obligations and test execution
python -m sacs verify .sacs/tasks/CHG-081.json

# 8. Mark task completed & archive ledger
python -m sacs finish .sacs/tasks/CHG-081.json

---

🧩 Project Structure

IOTokenSaver/
├── project.genome.yaml      # Declarative architecture genome & constraints
├── pyproject.toml           # Strict packaging, ruff, and mypy configuration
├── app/                     # Multi-provider model client (Gemini, LiteLLM, OpenAI, Custom)
│   └── model.py             # Configured model dispatcher with token caps
├── sacs/                    # SACS Core Engine
│   ├── compiler.py          # Genome compiler & semantic DAG generator
│   ├── python_index.py      # AST parser, causal route proofs & symbol slicer
│   ├── context.py           # Bounded context bundle builder
│   ├── mutation.py          # Constitutional mutation gate validator
│   ├── obligations.py       # Task ledger obligations engine
│   ├── prompt.py            # Structured prompt bundle composer
│   ├── artifacts.py         # Virtualized SHA-256 artifact storage
│   ├── errors.py            # Typed exception hierarchy
│   ├── types.py             # Strict TypedDict schemas for static type safety
│   ├── workflow.py          # End-to-end task execution state machine
│   └── cli.py               # Comprehensive CLI subcommands
├── benchmarks/              # SWE-bench & Industry benchmark suites
│   ├── run_live.py          # Live LLM benchmark runner
│   ├── run_offline.py       # Offline architecture & token budget simulator
│   └── industry.py          # Multi-baseline validation matrix
├── dashboard/               # Visual benchmark analytics dashboard
│   └── index.html           # Interactive HTML5/JS dashboard
└── tests/                   # 100% Passing Unit & Integration Test Suite

---

🧪 Running the Test Suite

SACS enforces strict test coverage and static type safety:

# Run 116+ comprehensive unit tests
pytest tests/

# Run type checking with mypy
mypy sacs/

# Run linter and code formatting with ruff
ruff check sacs/

---

🤝 Contributing

Contributions to SACS are welcome! Please ensure that:

1. All changes strictly adhere to SOLID and Clean Architecture principles.
2. New features include corresponding unit tests in tests/.
3. All code passes ruff check and pytest.

---

📄 License

Distributed under the Apache 2.0 License. See LICENSE for more information.