agent-coderag 1.1.0__py3-none-any.whl

agent_coderag-1.1.0.dist-info/METADATA

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: agent-coderag
+Version: 1.1.0
+Summary: 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.
+Author-email: Igor Boloban <naranor@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/naranor/agent-coderag
+Project-URL: Repository, https://github.com/naranor/agent-coderag
+Project-URL: Issues, https://github.com/naranor/agent-coderag/issues
+Project-URL: Changelog, https://github.com/naranor/agent-coderag/blob/main/CHANGELOG.md
+Keywords: rag,ai-agents,semantic-search,code-analysis,context-compression,onnx,local-embeddings
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Indexing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: duckdb
+Requires-Dist: numpy
+Requires-Dist: litellm
+Requires-Dist: onnxruntime
+Requires-Dist: tokenizers
+Requires-Dist: pydantic
+Requires-Dist: httpx
+Requires-Dist: aiofiles
+Dynamic: license-file
+
+# Agent-CodeRAG: Semantic Intelligence for AI Coding Agents
+
+> **Fast. Local. Agent-First. Token-Efficient.**
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![No PyTorch](https://img.shields.io/badge/Footprint-No_PyTorch-green.svg)](#-key-technologies)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+
+---
+
+## 📖 Table of Contents
+- [🧠 The Problem: The API Knowledge Gap](#-the-problem-the-api-knowledge-gap)
+- [🚀 The Solution: Real-Time Contextual Truth](#-the-solution-real-time-contextual-truth)
+- [🛠 How it Works](#-how-it-works)
+- [📡 API Discovery](#-api-discovery)
+- [🏃 Quick Start](#-quick-start)
+- [🤖 For AI Agents](#-for-ai-agents)
+- [🔧 Development](#-development)
+- [📄 License](#-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
+
+```mermaid
+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:
+```bash
+agent-coderag api pydantic
+```
+Returns the *live* public API, methods, and signatures.
+
+---
+
+## 🏃 Quick Start
+
+### 1. Install
+```bash
+pip install agent-coderag
+```
+
+### 2. Setup AI Models
+Download the lightweight `paraphrase-multilingual-MiniLM` ONNX model to your global cache:
+```bash
+agent-coderag setup
+```
+
+### 3. Configure your LLM (For Distillation)
+
+**Option A: Cloud (OpenAI)**
+```bash
+agent-coderag config --url "https://api.openai.com/v1" --model "gpt-4o-mini" --key "sk-..."
+```
+
+**Option B: Local (Ollama) - Recommended**
+```bash
+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
+```bash
+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)
+```bash
+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
+```bash
+pytest tests/
+pytest e2e_tests/
+```
+
+### Pre-commit Hooks
+We use `pre-commit` to maintain high code standards:
+```bash
+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](THIRD_PARTY_LICENSES.md) for a full list of open-source libraries used in Agent-CodeRAG.

agent_coderag-1.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+agent_coderag-1.1.0.dist-info/licenses/LICENSE,sha256=OV_lazXI3hc0Pqgm9hZhnJpHRUXWK4GS3sxaWmCDSHY,1069
+agent_coderag-1.1.0.dist-info/licenses/NOTICE,sha256=Ssc-bWjkZBz0sx1egO429_fmuKz9_vZxmO2frUZe5uk,802
+code_rag/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+code_rag/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+code_rag/core/interfaces.py,sha256=V9f2JLBxx2R9zwC8jk2gQGRS1ZC7UNh8C0pYxBKfFG4,867
+code_rag/core/manager.py,sha256=W_G8AeKf63pGEhqByB0DQUfiZJCf-wcn2btCzqH-wSo,2832
+code_rag/core/models.py,sha256=m9qd_eGqIhTgu4cHQGNfzIcvQk4XUz0mngHKgYc4QUM,881
+code_rag/discovery/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+code_rag/discovery/dependency.py,sha256=yatONVT_ubx0c_uaGQ9G5Yy1jgTivjtEsKcrLVuUsR4,1450
+code_rag/entry/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+code_rag/entry/cli.py,sha256=Tj3VCdc0VGJa9ypAiWdtkdo9eCwjK7-b-sHYOUIFv7A,7576
+code_rag/intelligence/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+code_rag/intelligence/distiller.py,sha256=P9NkgqSJJtAZm4Ngr98gW_WoP-Xk9gtvCfGp_q5jV9I,2732
+code_rag/intelligence/embedder.py,sha256=hbgv8OiLkvFIsMgTxwBekDGC7Xu853Mt_zWHeex1nrA,4264
+code_rag/parsers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+code_rag/parsers/ast_index.py,sha256=1SCAR7glGesFtEg26-GGvzqqqsUD-i7nWiXodVYK2OE,2776
+code_rag/storage/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+code_rag/storage/duckdb_impl.py,sha256=kU87-4qaERGv9pcZzwUWilxhbBYvp6GQygl49GVeaJ4,3986
+agent_coderag-1.1.0.dist-info/METADATA,sha256=Q7a5TmjFZlctVBEwBT1rWTa7z8_22DiywGKAhkOWH2E,6798
+agent_coderag-1.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+agent_coderag-1.1.0.dist-info/entry_points.txt,sha256=qt05eUIhUxid27O-C1RK1-Dz9uvKqSBeGpbzZCkm1fk,58
+agent_coderag-1.1.0.dist-info/top_level.txt,sha256=8W3_FE9oVHnpu46qinUXMuDnvAGnGWd1AHqsqvpIzOw,9
+agent_coderag-1.1.0.dist-info/RECORD,,

agent_coderag-1.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agent_coderag-1.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agent-coderag = code_rag.entry.cli:main

agent_coderag-1.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Boloban
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_coderag-1.1.0.dist-info/licenses/NOTICE

@@ -0,0 +1,17 @@
+CodeRAG
+Copyright 2026 Igor Boloban
+
+This product includes software developed by the following third-party projects:
+
+- DuckDB (MIT License) - https://duckdb.org/
+- NumPy (BSD License) - https://numpy.org/
+- LiteLLM (MIT License) - https://litellm.ai/
+- ONNX Runtime (MIT License) - https://onnxruntime.ai/
+- Tokenizers (Apache License 2.0) - https://github.com/huggingface/tokenizers
+- Pydantic (MIT License) - https://github.com/pydantic/pydantic
+- HTTPX (BSD License) - https://github.com/encode/httpx
+- Aiofiles (Apache License 2.0) - https://github.com/Tinche/aiofiles
+- Sentence Transformers (Apache License 2.0) - https://www.sbert.net/
+
+This product also uses various other open-source libraries as listed in THIRD_PARTY_LICENSES.md.
+All trademarks are the property of their respective owners.

agent_coderag-1.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+code_rag

code_rag/core/interfaces.py

@@ -0,0 +1,29 @@
+from abc import ABC, abstractmethod
+from typing import List, Optional
+from .models import KnowledgeUnit
+
+class IParser(ABC):
+    """Interface for extracting structure from code."""
+    @abstractmethod
+    async def distill_file(self, file_path: str) -> List[KnowledgeUnit]:
+        pass
+
+class IStorage(ABC):
+    """Interface for storing the index."""
+    @abstractmethod
+    async def upsert_unit(self, unit: KnowledgeUnit):
+        pass
+    
+    @abstractmethod
+    async def get_unit(self, unit_id: str) -> Optional[KnowledgeUnit]:
+        pass
+    
+    @abstractmethod
+    async def search_units(self, query: str, limit: int = 5) -> List[KnowledgeUnit]:
+        pass
+
+class IIntelligence(ABC):
+    """Interface for LLM-based analysis (distillation, embeddings)."""
+    @abstractmethod
+    async def summarize(self, code: str, unit_name: str) -> str:
+        pass

code_rag/core/manager.py

@@ -0,0 +1,70 @@
+import logging
+import asyncio
+from typing import List
+from .interfaces import IStorage, IParser, IIntelligence
+from .models import KnowledgeUnit
+
+logger = logging.getLogger(__name__)
+
+class CodeRAGManager:
+    """
+    Orchestrates the RAG workflow: parsing, distillation, and storage.
+    """
+    
+    def __init__(self, storage: IStorage, parser: IParser, intelligence: IIntelligence):
+        self.storage = storage
+        self.parser = parser
+        self.intelligence = intelligence
+
+    async def sync_file(self, file_path: str, force_distill: bool = False):
+        """
+        Processes a single file and syncs it with the storage.
+        """
+        # 1. Parse AST to get units
+        current_units = await self.parser.distill_file(file_path)
+        
+        for unit in current_units:
+            # v5.40: Delta-distillation logic
+            raw_code = unit.metadata.pop("raw_code", "")
+            
+            # 2. Get existing unit to check hash
+            existing_unit = await self.storage.get_unit(unit.id)
+            
+            should_distill = force_distill
+            if not existing_unit:
+                should_distill = True
+                logger.info("New unit discovered: %s", unit.name)
+            elif existing_unit.code_hash != unit.code_hash:
+                should_distill = True
+                logger.info("Unit %s changed (hash mismatch)", unit.name)
+            elif not existing_unit.summary:
+                should_distill = True
+                logger.info("Summary missing for %s", unit.name)
+            
+            if should_distill:
+                logger.info("Distilling summary for %s...", unit.id)
+                try:
+                    unit.summary = await self.intelligence.summarize(raw_code, unit.name)
+                except Exception as e:
+                    logger.error("Failed to distill %s: %s", unit.name, e)
+                    # Keep old summary if available, otherwise stay None
+                    unit.summary = existing_unit.summary if existing_unit else None
+            else:
+                # Reuse existing summary if code hasn't changed
+                unit.summary = existing_unit.summary if existing_unit else None
+            
+            # 3. Save to storage (includes embedding generation)
+            await self.storage.upsert_unit(unit)
+
+    async def search(self, query: str, limit: int = 5) -> List[KnowledgeUnit]:
+        """
+        Performs semantic search across all indexed units.
+        """
+        return await self.storage.search_units(query, limit=limit)
+
+    async def sync_project(self, paths: List[str], force_distill: bool = False):
+        """
+        Concurrent synchronization of multiple files.
+        """
+        tasks = [self.sync_file(p, force_distill=force_distill) for p in paths]
+        await asyncio.gather(*tasks)

code_rag/core/models.py

@@ -0,0 +1,33 @@
+from enum import Enum
+from typing import List, Dict, Any, Optional
+from pydantic import BaseModel, Field
+
+class UnitKind(str, Enum):
+    MODULE = "module"
+    CLASS = "class"
+    FUNCTION = "function"
+    METHOD = "method"
+
+class RelationType(str, Enum):
+    IMPORTS = "imports" # used
+    CALLS = "calls" # used
+    INHERITS = "inherits" # used
+    DEFINES = "defines" # used
+
+class KnowledgeUnit(BaseModel):
+    """Represents a piece of code (function, class, module)."""
+    id: str
+    kind: UnitKind
+    name: str
+    path: str
+    signature: Optional[str] = None
+    summary: Optional[str] = None
+    code_hash: str
+    tags: List[str] = Field(default_factory=list)
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+class Relation(BaseModel):
+    """Connection between knowledge units."""
+    from_id: str # used
+    to_id: str # used
+    type: RelationType # used

code_rag/discovery/dependency.py

@@ -0,0 +1,40 @@
+import importlib
+import inspect
+import logging
+
+logger = logging.getLogger(__name__)
+
+def _get_method_signature(obj) -> str:
+    """Helper to safely get a signature string."""
+    try:
+        return str(inspect.signature(obj))
+    except (ValueError, TypeError):
+        return "(...)"
+
+async def extract_library_api(library_name: str) -> str:
+    """
+    Extracts the public API (classes, methods) of an installed library using introspection.
+    """
+    try:
+        lib = importlib.import_module(library_name)
+        output = [f"# Public API for '{library_name}':"]
+
+        for name, obj in inspect.getmembers(lib):
+            if name.startswith("_"):
+                continue
+
+            if inspect.isclass(obj):
+                output.append(f"- **Class: {name}**")
+                for m_name, m_obj in inspect.getmembers(obj):
+                    if m_name.startswith("_"):
+                        continue
+                    if inspect.isfunction(m_obj) or inspect.ismethod(m_obj):
+                        sig = _get_method_signature(m_obj)
+                        output.append(f"  - `{m_name}{sig}`")
+            elif inspect.isfunction(obj) or inspect.isbuiltin(obj):
+                sig = _get_method_signature(obj)
+                output.append(f"- **Function: {name}{sig}**")
+
+        return "\n".join(output[:100]) # Limit output length
+    except Exception as e:
+        return f"Failed to extract API for '{library_name}': {e}"

code_rag/entry/cli.py

@@ -0,0 +1,214 @@
+import asyncio
+import argparse
+import os
+import sys
+import logging
+import json
+from pathlib import Path
+from typing import Optional
+import httpx
+
+# Suppress external library noise before they are imported by other modules
+os.environ["LITELLM_VERBOSE"] = "FALSE"
+logging.getLogger("LiteLLM").setLevel(logging.WARNING)
+logging.getLogger("onnxruntime").setLevel(logging.ERROR)
+
+# pylint: disable=wrong-import-position
+from ..core.manager import CodeRAGManager
+from ..storage.duckdb_impl import DuckDBStorage
+from ..parsers.ast_index import AstIndexParser
+from ..intelligence.embedder import Embedder, get_default_model_dir
+from ..intelligence.distiller import Distiller, DistillerConfig
+from ..discovery.dependency import extract_library_api
+# pylint: enable=wrong-import-position
+
+# Setup basic logging - default to WARNING for clean output
+logging.basicConfig(level=logging.WARNING, format="%(levelname)s: %(message)s")
+logger = logging.getLogger("agent-coderag")
+
+def get_manager(db_path: str, onnx_path: Optional[str] = None, verbose: bool = False):
+    """Initializes the RAG manager."""
+    if verbose:
+        logging.getLogger().setLevel(logging.INFO)
+        
+    config = DistillerConfig.load()
+    config.api_base = os.getenv("AGENT_PROXY_URL", config.api_base)
+    config.api_key = os.getenv("AGENT_PROXY_KEY", config.api_key)
+    config.model = os.getenv("AGENT_MODEL", config.model)
+    config.provider = os.getenv("AGENT_PROVIDER", config.provider)
+    
+    embedder = Embedder(model_path=onnx_path)
+    storage = DuckDBStorage(db_path, embedder=embedder)
+    parser = AstIndexParser()
+    distiller = Distiller(config)
+    
+    return CodeRAGManager(storage, parser, distiller)
+
+def should_index(path: Path) -> bool:
+    """Filters files that should NOT be indexed."""
+    p_str = str(path)
+    exclude_patterns = ["tests/", "venv/", "__pycache__/", ".git/"]
+    for pattern in exclude_patterns:
+        if pattern in p_str:
+            return False
+    return path.suffix == ".py"
+
+async def sync_cmd(args):
+    manager = get_manager(args.db, args.onnx, args.verbose)
+    if args.path:
+        target_path = Path(args.path)
+        if target_path.is_file():
+            await manager.sync_file(str(target_path), force_distill=args.force)
+        else:
+            paths = [str(p) for p in target_path.rglob("*.py") if should_index(p)]
+            if args.verbose:
+                logger.info("Indexing %d files...", len(paths))
+            await manager.sync_project(paths, force_distill=args.force)
+    elif args.all:
+        paths = [str(p) for p in Path(".").rglob("*.py") if should_index(p)]
+        if args.verbose:
+            logger.info("Indexing %d files...", len(paths))
+        await manager.sync_project(paths, force_distill=args.force)
+    
+    if not args.json:
+        print("Done.")
+    else:
+        print(json.dumps({"status": "success"}))
+
+async def search_cmd(args):
+    manager = get_manager(args.db, args.onnx, args.verbose)
+    results = await manager.search(args.query, limit=args.limit)
+    
+    if args.json:
+        output = [unit.model_dump() for unit in results]
+        print(json.dumps(output, indent=2, ensure_ascii=False))
+        return
+
+    if not results:
+        print("No results.")
+        return
+
+    for unit in results:
+        print(f"[{unit.kind.value}] {unit.name} | {unit.path}")
+        if unit.summary:
+            print(f"  {unit.summary}")
+        print("-" * 20)
+
+async def api_cmd(args):
+    output = await extract_library_api(args.library)
+    if args.json:
+        print(json.dumps({"api": output}))
+    else:
+        print(output)
+
+async def download_file(url: str, dest: Path):
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    async with httpx.AsyncClient(follow_redirects=True) as client:
+        async with client.stream("GET", url) as response:
+            if response.status_code != 200:
+                return False
+            with open(dest, "wb") as f:
+                async for chunk in response.aiter_bytes():
+                    f.write(chunk)
+    return True
+
+async def setup_cmd(args):
+    dest_dir = get_default_model_dir()
+    base_url = "https://huggingface.co/sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2/resolve/main"
+    files = {
+        "model.onnx": f"{base_url}/onnx/model.onnx",
+        "tokenizer.json": f"{base_url}/tokenizer.json"
+    }
+    force = getattr(args, "force", False)
+    for filename, url in files.items():
+        dest_path = dest_dir / filename
+        if not dest_path.exists() or force:
+            await download_file(url, dest_path)
+    print("Setup complete.")
+
+def config_cmd(args):
+    config = DistillerConfig.load()
+    if args.url:
+        config.api_base = args.url
+    if args.key:
+        config.api_key = args.key
+    if args.model:
+        config.model = args.model
+    if args.provider:
+        config.provider = args.provider
+    config.save()
+    if args.json:
+        print(json.dumps(config.model_dump()))
+    else:
+        print("Config updated.")
+
+async def rebuild_cmd(args):
+    db_path = Path(args.db)
+    if db_path.exists():
+        if args.verbose:
+            logger.info("Removing old database: %s", db_path)
+        db_path.unlink()
+    
+    # Trigger full sync
+    args.all = True
+    args.force = True
+    args.path = None
+    await sync_cmd(args)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Agent-CodeRAG CLI Tool")
+    parser.add_argument("--db", default=".code_rag.db", help="Path to DuckDB database")
+    parser.add_argument("--onnx", help="Path to ONNX embedding model")
+    parser.add_argument("--verbose", action="store_true", help="Show debug logs")
+    parser.add_argument("--json", action="store_true", help="Output results in JSON format")
+    
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # Commands
+    subparsers.add_parser("setup", help="Download models")
+    subparsers.add_parser("rebuild", help="Nuke database and re-index everything")
+    
+    conf_p = subparsers.add_parser("config", help="AI settings")
+    conf_p.add_argument("--url", help="API base URL")
+    conf_p.add_argument("--key", help="API key")
+    conf_p.add_argument("--model", help="Model name")
+    conf_p.add_argument("--provider", help="Provider")
+
+    sync_p = subparsers.add_parser("sync", help="Index files")
+    sync_p.add_argument("path", nargs="?", help="Path to index")
+    sync_p.add_argument("--all", action="store_true", help="Index all python files")
+    sync_p.add_argument("--force", action="store_true", help="Force distillation")
+
+    search_p = subparsers.add_parser("search", help="Semantic search")
+    search_p.add_argument("query", help="Query")
+    search_p.add_argument("--limit", type=int, default=5, help="Max results")
+
+    api_p = subparsers.add_parser("api", help="Discover library API")
+    api_p.add_argument("library", help="Library name")
+
+    args = parser.parse_args()
+
+    try:
+        if args.command == "setup":
+            asyncio.run(setup_cmd(args))
+        elif args.command == "config":
+            config_cmd(args)
+        elif args.command == "rebuild":
+            asyncio.run(rebuild_cmd(args))
+        elif args.command == "sync":
+            asyncio.run(sync_cmd(args))
+        elif args.command == "search":
+            asyncio.run(search_cmd(args))
+        elif args.command == "api":
+            asyncio.run(api_cmd(args))
+    except Exception as e:
+        if args.json:
+            print(json.dumps({"error": str(e)}))
+        else:
+            logger.error(e)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

code_rag/intelligence/distiller.py

@@ -0,0 +1,80 @@
+import logging
+import json
+import litellm
+from pydantic import BaseModel
+from ..core.interfaces import IIntelligence
+from .embedder import get_global_dir
+
+logger = logging.getLogger(__name__)
+
+class DistillerConfig(BaseModel):
+    model: str = "auto"
+    api_base: str = "http://localhost:8081/api/v1"
+    api_key: str = "sk-not-required"
+    provider: str = "openai"
+    temperature: float = 0.0
+
+    @classmethod
+    def load(cls) -> "DistillerConfig":
+        """Loads config from the global agent-coderag directory."""
+        config_path = get_global_dir() / "config.json"
+        if config_path.exists():
+            try:
+                with open(config_path, "r", encoding="utf-8") as f:
+                    data = json.load(f)
+                    return cls(**data)
+            except Exception as e:
+                logger.error("Failed to load config from %s: %s", config_path, e)
+        return cls()
+
+    def save(self):
+        """Saves current config to the global agent-coderag directory."""
+        config_path = get_global_dir() / "config.json"
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            with open(config_path, "w", encoding="utf-8") as f:
+                json.dump(self.model_dump(), f, indent=4)
+            logger.info("Config saved to %s", config_path)
+        except Exception as e:
+            logger.error("Failed to save config to %s: %s", config_path, e)
+
+class Distiller(IIntelligence):
+    """
+    LLM-based code analyst that extracts the 'intent' from raw code.
+    """
+    
+    def __init__(self, config: DistillerConfig):
+        self.config = config
+
+    async def summarize(self, code: str, unit_name: str) -> str:
+        """
+        Generates a concise technical summary of what the code DOES.
+        """
+        prompt = f"""
+Analyze the following code block for '{unit_name}'. 
+Provide a concise, 1-2 sentence technical description of its core logic and intent. 
+Focus on WHAT it accomplishes and its role in the system. 
+DO NOT repeat the signature. 
+DO NOT include docstrings or comments in your summary.
+
+CODE:
+{code}
+
+SUMMARY:
+"""
+        model_id = self.config.model
+        if self.config.provider == "ollama" and not model_id.startswith("ollama/"):
+            model_id = f"ollama/{model_id}"
+
+        response = await litellm.acompletion(
+            model=model_id,
+            messages=[{"role": "user", "content": prompt}],
+            api_base=self.config.api_base,
+            api_key=self.config.api_key,
+            temperature=self.config.temperature,
+            timeout=30,
+            custom_llm_provider=self.config.provider
+        )
+        
+        summary = response.choices[0].message.content.strip()
+        return summary

code_rag/intelligence/embedder.py

@@ -0,0 +1,100 @@
+import os
+import logging
+import numpy as np
+from typing import List, Optional
+from pathlib import Path
+import onnxruntime as ort
+from tokenizers import Tokenizer
+
+logger = logging.getLogger(__name__)
+
+def get_global_dir() -> Path:
+    """Returns the default global directory for agent-coderag data (cross-platform)."""
+    if os.name == 'nt': # Windows
+        base_dir = Path(os.environ.get('LOCALAPPDATA', Path.home() / 'AppData' / 'Local'))
+    else: # Linux/macOS
+        base_dir = Path(os.environ.get('XDG_CACHE_HOME', Path.home() / '.cache'))
+    
+    return base_dir / "agent-coderag"
+
+def get_default_model_dir() -> Path:
+    """Returns the default global directory for models."""
+    return get_global_dir() / "models" / "mini-lm"
+
+class Embedder:
+    """
+    Local multilingual embedder using ONNX Runtime and Tokenizers.
+    """
+    
+    def __init__(self, model_path: Optional[str] = None):
+        self.model_path = model_path
+        self.session: Optional[ort.InferenceSession] = None
+        self.tokenizer: Optional[Tokenizer] = None
+        
+        if not self.model_path:
+            global_dir = get_default_model_dir()
+            potential_path = global_dir / "model.onnx"
+            if potential_path.exists():
+                self.model_path = str(potential_path)
+                logger.info("Using global model from %s", self.model_path)
+            else:
+                logger.warning("No model found at %s. Please run 'agent-coderag setup'.", potential_path)
+        
+        if self.model_path and os.path.exists(self.model_path):
+            self._init_tokenizer()
+            self._init_session()
+
+    def _init_tokenizer(self):
+        if not self.model_path:
+            return
+            
+        model_dir = os.path.dirname(self.model_path)
+        tokenizer_file = os.path.join(model_dir, "tokenizer.json")
+        if not os.path.exists(tokenizer_file):
+            tokenizer_file = os.path.join(os.path.dirname(model_dir), "tokenizer.json")
+            
+        if os.path.exists(tokenizer_file):
+            try:
+                self.tokenizer = Tokenizer.from_file(tokenizer_file)
+                self.tokenizer.enable_padding(pad_id=0, pad_token="[PAD]")  # nosec B106
+                self.tokenizer.enable_truncation(max_length=512)
+                logger.debug("Loaded tokenizer from %s", tokenizer_file)
+            except Exception as e:
+                logger.error("Failed to load tokenizer from %s: %s", tokenizer_file, e)
+        else:
+            logger.error("tokenizer.json not found near %s", self.model_path)
+
+    def _init_session(self):
+        if not self.model_path:
+            return
+            
+        try:
+            self.session = ort.InferenceSession(self.model_path, providers=['CPUExecutionProvider'])
+            logger.info("ONNX session initialized with model: %s", self.model_path)
+        except Exception as e:
+            logger.error("Failed to initialize ONNX session: %s", e)
+
+    def embed(self, texts: List[str]) -> np.ndarray:
+        if not self.session or not self.tokenizer:
+            return np.zeros((len(texts), 384), dtype=np.float32)
+
+        encodings = self.tokenizer.encode_batch(texts)
+        input_ids = np.array([e.ids for e in encodings], dtype=np.int64)
+        attention_mask = np.array([e.attention_mask for e in encodings], dtype=np.int64)
+        
+        inputs = {"input_ids": input_ids, "attention_mask": attention_mask}
+        model_inputs = [i.name for i in self.session.get_inputs()]
+        if "token_type_ids" in model_inputs:
+            inputs["token_type_ids"] = np.array([e.type_ids for e in encodings], dtype=np.int64)
+
+        outputs = self.session.run(None, inputs)
+        embeddings = self._mean_pooling(outputs[0], attention_mask)
+        norms = np.linalg.norm(embeddings, axis=1, keepdims=True)
+        norms = np.clip(norms, a_min=1e-12, a_max=None)
+        return embeddings / norms
+
+    def _mean_pooling(self, last_hidden_state, attention_mask):
+        input_mask_expanded = np.expand_dims(attention_mask, -1).astype(float)
+        sum_embeddings = np.sum(last_hidden_state * input_mask_expanded, axis=1)
+        sum_mask = np.clip(input_mask_expanded.sum(axis=1), a_min=1e-9, a_max=None)
+        return sum_embeddings / sum_mask

code_rag/parsers/ast_index.py

@@ -0,0 +1,81 @@
+import ast
+import hashlib
+import os
+import logging
+from typing import List, Optional
+from ..core.interfaces import IParser
+from ..core.models import KnowledgeUnit, UnitKind
+
+logger = logging.getLogger(__name__)
+
+class AstIndexParser(IParser):
+    """
+    Parses Python code using the built-in AST module to extract units.
+    """
+    
+    async def distill_file(self, file_path: str) -> List[KnowledgeUnit]:
+        """
+        Parses a file and returns a list of knowledge units.
+        """
+        if not os.path.exists(file_path):
+            return []
+
+        try:
+            with open(file_path, "r", encoding="utf-8") as f:
+                source = f.read()
+            
+            tree = ast.parse(source)
+            units = []
+            
+            # Module level unit
+            file_hash = hashlib.sha256(source.strip().encode()).hexdigest()
+            units.append(KnowledgeUnit(
+                id=f"{file_path}:module",
+                kind=UnitKind.MODULE,
+                name=os.path.basename(file_path),
+                path=file_path,
+                code_hash=file_hash,
+                metadata={"raw_code": source}
+            ))
+
+            for node in ast.walk(tree):
+                if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+                    unit = self._parse_node(node, file_path, source)
+                    if unit:
+                        units.append(unit)
+            
+            return units
+        except Exception as e:
+            logger.error("Failed to parse %s: %s", file_path, e)
+            return []
+
+    def _parse_node(self, node, file_path: str, source: str) -> Optional[KnowledgeUnit]:
+        """Helper to create a KnowledgeUnit from an AST node."""
+        kind = UnitKind.FUNCTION
+        if isinstance(node, ast.ClassDef):
+            kind = UnitKind.CLASS
+        elif hasattr(node, "parent") and isinstance(node.parent, ast.ClassDef):
+            kind = UnitKind.METHOD
+
+        # Extract source code for the node
+        try:
+            node_source = ast.get_source_segment(source, node) or ""
+            node_hash = hashlib.sha256(node_source.strip().encode()).hexdigest()
+            
+            # Simplified signature extraction
+            signature = None
+            if hasattr(node, "args"):
+                args = [arg.arg for arg in node.args.args]
+                signature = f"({', '.join(args)})"
+
+            return KnowledgeUnit(
+                id=f"{file_path}:{node.name}",
+                kind=kind,
+                name=node.name,
+                path=file_path,
+                signature=signature,
+                code_hash=node_hash,
+                metadata={"raw_code": node_source}
+            )
+        except Exception:
+            return None

code_rag/storage/duckdb_impl.py

@@ -0,0 +1,111 @@
+import json
+import logging
+import duckdb
+from typing import List, Optional
+from ..core.interfaces import IStorage
+from ..core.models import KnowledgeUnit, UnitKind
+
+logger = logging.getLogger(__name__)
+
+class DuckDBStorage(IStorage):
+    """
+    DuckDB-based storage with Vector Similarity Search (VSS) capabilities.
+    """
+    
+    def __init__(self, db_path: str, embedder=None):
+        self.db_path = db_path
+        self.embedder = embedder
+        self.conn = duckdb.connect(self.db_path)
+        self._setup_db()
+
+    def _setup_db(self):
+        """Initializes tables and extensions."""
+        self.conn.execute("INSTALL vss;")
+        self.conn.execute("LOAD vss;")
+        
+        # Metadata table
+        self.conn.execute("""
+            CREATE TABLE IF NOT EXISTS units (
+                id VARCHAR PRIMARY KEY,
+                kind VARCHAR,
+                name VARCHAR,
+                path VARCHAR,
+                signature VARCHAR,
+                summary VARCHAR,
+                code_hash VARCHAR,
+                tags VARCHAR[],
+                metadata JSON
+            )
+        """)
+        
+        # Vector table (MiniLM dimension is 384)
+        self.conn.execute("""
+            CREATE TABLE IF NOT EXISTS unit_embeddings (
+                id VARCHAR PRIMARY KEY,
+                vec FLOAT[384]
+            )
+        """)
+        logger.info("Storage initialized at %s", self.db_path)
+
+    async def upsert_unit(self, unit: KnowledgeUnit):
+        """Inserts or updates a knowledge unit and its embedding."""
+        # 1. Upsert metadata
+        self.conn.execute("""
+            INSERT OR REPLACE INTO units (id, kind, name, path, signature, summary, code_hash, tags, metadata)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+        """, [
+            unit.id, unit.kind.value, unit.name, unit.path, 
+            unit.signature, unit.summary, unit.code_hash, 
+            unit.tags, json.dumps(unit.metadata)
+        ])
+
+        # 2. Update embedding
+        if self.embedder:
+            # Fallback to name/signature if summary is missing
+            text_to_embed = unit.summary or f"{unit.kind.value} {unit.name} {unit.signature or ''}"
+            vec = self.embedder.embed([text_to_embed])[0]
+            self.conn.execute("""
+                INSERT OR REPLACE INTO unit_embeddings (id, vec)
+                VALUES (?, ?)
+            """, [unit.id, vec.tolist()])
+
+    async def get_unit(self, unit_id: str) -> Optional[KnowledgeUnit]:
+        """Retrieves a unit by its unique ID."""
+        res = self.conn.execute("SELECT * FROM units WHERE id = ?", [unit_id]).fetchone()
+        if not res:
+            return None
+        return self._map_row_to_unit(res)
+
+    async def search_units(self, query: str, limit: int = 5) -> List[KnowledgeUnit]:
+        """Hybrid search using VSS and FTS."""
+        if not self.embedder:
+            # Fallback to basic text search if no embedder
+            res = self.conn.execute("""
+                SELECT * FROM units 
+                WHERE name ILIKE ? OR summary ILIKE ? 
+                LIMIT ?
+            """, [f"%{query}%", f"%{query}%", limit]).fetchall()
+        else:
+            query_vec = self.embedder.embed([query])[0]
+            res = self.conn.execute("""
+                SELECT u.*, array_distance(e.vec, ?::FLOAT[384]) as dist
+                FROM units u
+                JOIN unit_embeddings e ON u.id = e.id
+                ORDER BY dist ASC
+                LIMIT ?
+            """, [query_vec.tolist(), limit]).fetchall()
+            
+        return [self._map_row_to_unit(row) for row in res]
+
+    def _map_row_to_unit(self, row) -> KnowledgeUnit:
+        return KnowledgeUnit(
+            id=row[0],
+            kind=UnitKind(row[1]),
+            name=row[2],
+            path=row[3],
+            signature=row[4],
+            summary=row[5],
+            code_hash=row[6],
+            tags=row[7] if row[7] else [],
+            metadata=json.loads(row[8]) if row[8] else {}
+        )