agent-coderag 1.1.0

Lightweight semantic code search and distillation utility for AI coding agents. It solves the API knowledge gap via real-time local signature extraction and intent analysis without PyTorch. Optimized for token efficiency, it compresses codebase context into compact semantic summaries stored in a local DuckDB vector similarity index.

Agent-CodeRAG: Semantic Intelligence for AI Coding Agents

Fast. Local. Agent-First. Token-Efficient.

---

📖 Table of Contents

• 🧠 The Problem: The API Knowledge Gap
• 🚀 The Solution: Real-Time Contextual Truth
• 🛠 How it Works
• 📡 API Discovery
• 🏃 Quick Start
• 🤖 For AI Agents
• 🔧 Development
• 📄 License

---

🧠 The Problem: The API Knowledge Gap

AI coding agents often hallucinate when calling library APIs because their training data is static. This leads to a "Fail-Fix-Fail" cycle:

1. Broken Code: Agents use deprecated parameters or non-existent methods from outdated versions.
2. Token Waste: You provide the error, the agent tries to fix it using more outdated data, consuming thousands of tokens in a loop.
3. Environment Mismatch: The agent knows the API for version 1.0, but your environment has 2.0.

Real-world Example (The Pydantic Gap)

• Agent's Knowledge: Knows Pydantic v1 (model.dict()).
• Your Environment: Uses Pydantic v2 (model.model_dump()).
• The Result: The agent writes dict(), the code fails, and it wastes 5000+ tokens trying to "fix" a problem it doesn't understand.

🚀 The Solution: Real-Time Contextual Truth

Agent-CodeRAG acts as a lightweight semantic bridge between your local environment and the LLM.

• API Discovery: Extracts actual signatures from your installed libraries.
• Semantic Retrieval: Provides the LLM with the exact Intent of your code units, indexed locally via ONNX.
• Token Efficiency: Instead of sending whole files, Agent-CodeRAG distills code into compact semantic summaries, saving up to 80% of context window tokens.

---

🛠 How it Works

graph TD
    A[Local Python Code] --> B[AST Parser]
    B --> C{Delta-Sync}
    C -- Changed/New --> D[LLM Distiller]
    C -- Unchanged --> E[Local Cache]
    D --> F[Semantic Summary]
    E --> F
    F --> G[ONNX Embedder]
    G --> H[(DuckDB VSS)]
    H --> I[Semantic Search / JSON API]

✨ Key Features

• ⚡ No PyTorch: Uses onnxruntime and tokenizers (Rust) for a tiny footprint and instant startup.
• 💾 DuckDB VSS: High-performance vector similarity search stored in a single local file.
• 🔄 Delta-Sync: Uses SHA-256 hashing to only re-distill changed code, saving your API budget.
• 🔌 Hybrid Intelligence: Works offline using name-based embeddings; adds AI-distilled reasoning when an LLM is connected.

---

📡 API Discovery

To help your agent understand a specific library version installed in your environment:

agent-coderag api pydantic

Returns the live public API, methods, and signatures.

---

🏃 Quick Start

1. Install

pip install agent-coderag

2. Setup AI Models

Download the lightweight paraphrase-multilingual-MiniLM ONNX model to your global cache:

agent-coderag setup

3. Configure your LLM (For Distillation)

Option A: Cloud (OpenAI)

agent-coderag config --url "https://api.openai.com/v1" --model "gpt-4o-mini" --key "sk-..."

Option B: Local (Ollama) - Recommended

agent-coderag config --url "http://localhost:11434" --provider "ollama" --model "qwen2.5-coder:7b"

We recommend using qwen2.5-coder or llama3.2 for fast and private local distillation.

4. Index your Project

agent-coderag sync --all

5. Search

• Human Mode (Compact): agent-coderag search "how to handle errors"
• Agent Mode (JSON): agent-coderag --json search "data storage" --limit 1

🐳 Docker (Alternative)

docker build -t agent-coderag .
docker run -v ~/.cache/agent-coderag:/root/.cache/agent-coderag agent-coderag setup

---

🤖 For AI Agents

Agent-CodeRAG is built specifically for programmatic consumption.

Agent Strategy

1. Search First: Use agent-coderag --json search "topic" to find relevant code units before reading files.
2. Use Intent: The summary field provides technical intent, allowing you to skip reading complex implementation details.

---

🔧 Development

Running Tests

pytest tests/
pytest e2e_tests/

Pre-commit Hooks

We use pre-commit to maintain high code standards:

pip install pre-commit
pre-commit install

---

📄 License

MIT © 2026 Igor Boloban

🙏 Acknowledgments

This project stands on the shoulders of giants. See THIRD_PARTY_LICENSES.md for a full list of open-source libraries used in Agent-CodeRAG.