contextguardrail 0.1.0__tar.gz

contextguardrail-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: contextguardrail
+Version: 0.1.0
+Summary: Local-first token firewall for AI coding agents
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13.0
+Requires-Dist: networkx>=3.0
+Requires-Dist: tiktoken>=0.7
+
+# ContextGuardrail
+
+ContextGuardrail is a local-first MVP for reducing AI coding-agent context. It scans a repo, builds a lightweight code graph, selects relevant files for a prompt, prevents replaying already-sent files, caches repeated asks, and reports estimated token/cost savings.
+
+## Install locally
+
+```bash
+cd /Users/homesachin/Desktop/zoneone/contextguardrail
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Use
+
+```bash
+contextguardrail init
+contextguardrail index /path/to/repo
+contextguardrail ask "Where is authentication handled?"
+contextguardrail stats
+contextguardrail export
+contextguardrail clean
+```
+
+All state is stored in the indexed repo under `.contextguardrail/`.
+
+## MVP Features
+
+- Repo scanner with incremental hashing
+- Python AST parser for imports, classes, functions, and summaries
+- Lightweight dependency graph
+- Context selector using prompt keywords and graph metadata
+- Token counting with `tiktoken` when available, word-count fallback otherwise
+- Semantic cache for repeated prompt and selected-file sets
+- Replay prevention so already-sent files are skipped unless changed
+- Context diffing via file hashes
+- Cost observability through `contextguardrail stats`
+
+This version intentionally skips dashboards, multi-user support, Neo4j, and agent orchestration.
+
+
+## Project Layout
+
+```
+contextguardrail/
+├── pyproject.toml              # Package metadata, dependencies, CLI entrypoints
+├── README.md                   # Project documentation and usage guide
+├── contextguardrail/
+│   ├── scanner.py              # Scan repo and detect files, hashes, changes
+│   ├── config.py               # Global settings and configuration loading
+│   ├── budget.py               # Token estimation and budget enforcement
+│   ├── exporter.py             # Export graph, summaries, and reports
+│   ├── graph.py                # Build dependency graph from source code
+│   ├── selector.py             # Select most relevant context for a prompt
+│   ├── cache.py                # Semantic cache and replay prevention
+│   ├── cli.py                  # Main CLI commands exposed to users
+│   ├── stats.py                # Usage metrics and cost-saving reports
+│   └── storage.py              # SQLite helpers and persistence layer
+└── tests/
+    └── test_budget.py          # Unit tests for token budgeting logic
+```

contextguardrail-0.1.0/README.md

@@ -0,0 +1,61 @@
+# ContextGuardrail
+
+ContextGuardrail is a local-first MVP for reducing AI coding-agent context. It scans a repo, builds a lightweight code graph, selects relevant files for a prompt, prevents replaying already-sent files, caches repeated asks, and reports estimated token/cost savings.
+
+## Install locally
+
+```bash
+cd /Users/homesachin/Desktop/zoneone/contextguardrail
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Use
+
+```bash
+contextguardrail init
+contextguardrail index /path/to/repo
+contextguardrail ask "Where is authentication handled?"
+contextguardrail stats
+contextguardrail export
+contextguardrail clean
+```
+
+All state is stored in the indexed repo under `.contextguardrail/`.
+
+## MVP Features
+
+- Repo scanner with incremental hashing
+- Python AST parser for imports, classes, functions, and summaries
+- Lightweight dependency graph
+- Context selector using prompt keywords and graph metadata
+- Token counting with `tiktoken` when available, word-count fallback otherwise
+- Semantic cache for repeated prompt and selected-file sets
+- Replay prevention so already-sent files are skipped unless changed
+- Context diffing via file hashes
+- Cost observability through `contextguardrail stats`
+
+This version intentionally skips dashboards, multi-user support, Neo4j, and agent orchestration.
+
+
+## Project Layout
+
+```
+contextguardrail/
+├── pyproject.toml              # Package metadata, dependencies, CLI entrypoints
+├── README.md                   # Project documentation and usage guide
+├── contextguardrail/
+│   ├── scanner.py              # Scan repo and detect files, hashes, changes
+│   ├── config.py               # Global settings and configuration loading
+│   ├── budget.py               # Token estimation and budget enforcement
+│   ├── exporter.py             # Export graph, summaries, and reports
+│   ├── graph.py                # Build dependency graph from source code
+│   ├── selector.py             # Select most relevant context for a prompt
+│   ├── cache.py                # Semantic cache and replay prevention
+│   ├── cli.py                  # Main CLI commands exposed to users
+│   ├── stats.py                # Usage metrics and cost-saving reports
+│   └── storage.py              # SQLite helpers and persistence layer
+└── tests/
+    └── test_budget.py          # Unit tests for token budgeting logic
+```

contextguardrail-0.1.0/contextguardrail/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

contextguardrail-0.1.0/contextguardrail/budget.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+
+def estimate_tokens(text: str, model: str = "gpt-4o-mini") -> int:
+    try:
+        import tiktoken
+
+        encoding = tiktoken.encoding_for_model(model)
+        return len(encoding.encode(text))
+    except Exception:
+        return int(len(text.split()) * 1.3)
+
+
+def cost_usd(input_tokens: int, output_tokens: int = 0) -> float:
+    input_cost_per_million = 0.15
+    output_cost_per_million = 0.60
+    return (input_tokens / 1_000_000 * input_cost_per_million) + (
+        output_tokens / 1_000_000 * output_cost_per_million
+    )

contextguardrail-0.1.0/contextguardrail/cache.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+
+from contextguardrail.storage import connect
+
+
+def cache_key(prompt: str, selected_hash: str, model: str) -> str:
+    return hashlib.sha256(f"{prompt}\n{selected_hash}\n{model}".encode()).hexdigest()
+
+
+def selected_files_hash(files: list[dict]) -> str:
+    payload = "|".join(f"{item['path']}:{item['hash']}" for item in files)
+    return hashlib.sha256(payload.encode()).hexdigest()
+
+
+def get_cache(repo: str | Path, key: str) -> str | None:
+    with connect(repo, "cache.db") as db:
+        row = db.execute("SELECT response FROM cache WHERE key = ?", (key,)).fetchone()
+    return row["response"] if row else None
+
+
+def set_cache(repo: str | Path, key: str, response: str) -> None:
+    with connect(repo, "cache.db") as db:
+        db.execute(
+            "INSERT OR REPLACE INTO cache(key, response) VALUES (?, ?)",
+            (key, response),
+        )
+
+
+def prompt_hash(prompt: str) -> str:
+    return hashlib.sha256(prompt.strip().lower().encode()).hexdigest()
+
+
+def already_sent(repo: str | Path, prompt: str) -> dict[str, str]:
+    with connect(repo, "cache.db") as db:
+        row = db.execute("SELECT file_hashes FROM replay WHERE prompt_hash = ?", (prompt_hash(prompt),)).fetchone()
+    return json.loads(row["file_hashes"]) if row else {}
+
+
+def remember_sent(repo: str | Path, prompt: str, files: list[dict]) -> None:
+    file_hashes = {item["path"]: item["hash"] for item in files}
+    with connect(repo, "cache.db") as db:
+        db.execute(
+            "INSERT OR REPLACE INTO replay(prompt_hash, files, file_hashes) VALUES (?, ?, ?)",
+            (prompt_hash(prompt), json.dumps(list(file_hashes)), json.dumps(file_hashes)),
+        )
+
+
+def clean_cache(repo: str | Path) -> int:
+    with connect(repo, "cache.db") as db:
+        count = db.execute("SELECT COUNT(*) AS count FROM cache").fetchone()["count"]
+        db.execute("DELETE FROM cache")
+        db.execute("DELETE FROM replay")
+    return int(count)

contextguardrail-0.1.0/contextguardrail/cli.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from contextguardrail.budget import cost_usd
+from contextguardrail.cache import (
+    already_sent,
+    cache_key,
+    clean_cache,
+    get_cache,
+    remember_sent,
+    selected_files_hash,
+    set_cache,
+)
+from contextguardrail.config import DEFAULT_BUDGET, DEFAULT_MODEL, ensure_state, repo_root
+from contextguardrail.exporter import export_repo
+from contextguardrail.graph import graph_counts
+from contextguardrail.scanner import index_repo
+from contextguardrail.selector import select_context
+from contextguardrail.stats import record_request, show_stats
+from contextguardrail.storage import init_storage
+
+app = typer.Typer(help="Local-first token firewall for AI coding agents.")
+console = Console()
+
+
+@app.command()
+def init(path: str = typer.Argument(".")):
+    """Create .contextguardrail storage for a repo."""
+    root = repo_root(path)
+    init_storage(root)
+    console.print(f"[green]Initialized[/green] {ensure_state(root)}")
+
+
+@app.command()
+def index(
+    path: str = typer.Argument("."),
+    incremental: bool = typer.Option(False, "--incremental", "-i"),
+):
+    """Scan a repo and build the local code graph."""
+    root = repo_root(path)
+    result = index_repo(root, incremental=incremental)
+    functions, classes = graph_counts(root)
+    console.print(f"Files scanned: [bold]{result['files_scanned']}[/bold]")
+    if incremental:
+        console.print(f"Files skipped: [bold]{result['files_skipped']}[/bold]")
+    console.print(f"Functions: [bold]{functions}[/bold]")
+    console.print(f"Classes: [bold]{classes}[/bold]")
+    console.print("[green]Graph built.[/green]")
+
+
+@app.command()
+def ask(
+    prompt: str,
+    path: str = typer.Option(".", "--path", "-p"),
+    model: str = typer.Option(DEFAULT_MODEL, "--model", "-m"),
+    budget: int = typer.Option(DEFAULT_BUDGET, "--budget", "-b"),
+    include_replay: bool = typer.Option(False, "--include-replay"),
+):
+    """Select optimized context for a coding prompt."""
+    root = repo_root(path)
+    base_selected, raw_tokens = select_context(root, prompt, budget=budget)
+    base_optimized = estimated_optimized_tokens(base_selected)
+    key = cache_key(prompt, selected_files_hash(base_selected), model)
+    cached = get_cache(root, key)
+    if cached is not None:
+        console.print(cached.replace("Cache: miss", "Cache: hit"))
+        record_request(root, raw_tokens, 0, cache_hit=True)
+        return
+
+    replay = {} if include_replay else already_sent(root, prompt)
+    selected, raw_tokens = select_context(root, prompt, budget=budget, exclude_unchanged=replay)
+    optimized_tokens = sum(max(30, min(item["tokens"], int(item["tokens"] * 0.25))) for item in selected)
+
+    lines = ["Files selected:", ""]
+    if selected:
+        lines.extend(item["path"] for item in selected)
+    else:
+        lines.append("No changed files since this prompt was last sent.")
+    lines.extend(
+        [
+            "",
+            f"Raw Tokens: {raw_tokens:,}",
+            f"Optimized Tokens: {optimized_tokens:,}",
+            f"Savings: {savings_percent(raw_tokens, optimized_tokens):.1f}%",
+            f"Estimated Cost Saved: ${cost_usd(max(0, raw_tokens - optimized_tokens)):.4f}",
+        ]
+    )
+    lines.append("Cache: miss")
+    if base_optimized == optimized_tokens or not replay:
+        set_cache(root, key, "\n".join(lines))
+    remember_sent(root, prompt, selected)
+    record_request(root, raw_tokens, optimized_tokens, cache_hit=False)
+    console.print("\n".join(lines))
+
+
+@app.command()
+def analyze(
+    prompt: str,
+    path: str = typer.Option(".", "--path", "-p"),
+    budget: int = typer.Option(DEFAULT_BUDGET, "--budget", "-b"),
+):
+    """Killer-demo alias for ask with cost framing."""
+    ask(prompt=prompt, path=path, budget=budget)
+
+
+@app.command()
+def stats(path: str = typer.Argument(".")):
+    """Show token and cache savings."""
+    data = show_stats(repo_root(path))
+    table = Table(title="ContextGuardrail Stats")
+    table.add_column("Metric")
+    table.add_column("Value", justify="right")
+    table.add_row("Requests", f"{data['requests']:,}")
+    table.add_row("Input tokens saved", f"{data['input_tokens_saved']:,}")
+    table.add_row("Output tokens saved", f"{data['output_tokens_saved']:,}")
+    table.add_row("Cache hits", f"{data['cache_hits']:,}")
+    table.add_row("Raw tokens observed", f"{data['raw_tokens']:,}")
+    table.add_row("Optimized tokens sent", f"{data['optimized_tokens']:,}")
+    table.add_row("Estimated cost saved", f"${data['estimated_cost_saved']:.4f}")
+    console.print(table)
+
+
+@app.command("clean")
+def clean(path: str = typer.Argument(".")):
+    """Clean semantic cache and replay memory."""
+    count = clean_cache(repo_root(path))
+    console.print(f"[green]Cleaned[/green] {count} cached responses")
+
+
+@app.command("export")
+def export_command(path: str = typer.Argument(".")):
+    """Export repo-brain.json, code-dna.json, and ai-gossip.md."""
+    files = export_repo(repo_root(path))
+    for file in files:
+        console.print(file)
+
+
+def savings_percent(raw_tokens: int, optimized_tokens: int) -> float:
+    if raw_tokens <= 0:
+        return 0.0
+    return max(0.0, (raw_tokens - optimized_tokens) / raw_tokens * 100)
+
+
+def estimated_optimized_tokens(files: list[dict]) -> int:
+    return sum(max(30, min(item["tokens"], int(item["tokens"] * 0.25))) for item in files)
+
+
+if __name__ == "__main__":
+    app()

contextguardrail-0.1.0/contextguardrail/config.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+STATE_DIR = ".contextguardrail"
+DEFAULT_MODEL = "gpt-4o-mini"
+DEFAULT_BUDGET = 8_000
+
+SKIP_DIRS = {
+    ".git",
+    ".hg",
+    ".svn",
+    ".venv",
+    "venv",
+    "env",
+    "__pycache__",
+    "node_modules",
+    "dist",
+    "build",
+    ".contextguardrail",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".ruff_cache",
+}
+
+CODE_EXTENSIONS = {
+    ".py",
+    ".js",
+    ".jsx",
+    ".ts",
+    ".tsx",
+    ".go",
+    ".java",
+    ".rs",
+    ".rb",
+    ".php",
+    ".c",
+    ".cc",
+    ".cpp",
+    ".h",
+    ".hpp",
+    ".cs",
+    ".swift",
+    ".kt",
+    ".kts",
+    ".scala",
+    ".sh",
+    ".sql",
+    ".yaml",
+    ".yml",
+    ".json",
+    ".toml",
+    ".md",
+}
+
+
+def repo_root(path: str | Path = ".") -> Path:
+    return Path(path).expanduser().resolve()
+
+
+def state_dir(path: str | Path = ".") -> Path:
+    return repo_root(path) / STATE_DIR
+
+
+def ensure_state(path: str | Path = ".") -> Path:
+    root = state_dir(path)
+    (root / "cache").mkdir(parents=True, exist_ok=True)
+    (root / "summaries").mkdir(parents=True, exist_ok=True)
+    return root

contextguardrail-0.1.0/contextguardrail/exporter.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from contextguardrail.config import ensure_state
+from contextguardrail.graph import load_graph
+from contextguardrail.storage import connect, load_stats
+
+
+def export_repo(repo: str | Path = ".") -> list[Path]:
+    state = ensure_state(repo)
+    with connect(repo, "hashes.db") as files_db, connect(repo, "graph.db") as graph_db:
+        files = [dict(row) for row in files_db.execute("SELECT * FROM files ORDER BY path").fetchall()]
+        symbols = [dict(row) for row in graph_db.execute("SELECT * FROM symbols ORDER BY path").fetchall()]
+    graph = load_graph(repo)
+    brain = {
+        "files": files,
+        "symbols": symbols,
+        "edges": [{"source": a, "target": b, **data} for a, b, data in graph.edges(data=True)],
+        "stats": load_stats(repo),
+    }
+    repo_brain = state / "repo-brain.json"
+    code_dna = state / "code-dna.json"
+    ai_gossip = state / "ai-gossip.md"
+    repo_brain.write_text(json.dumps(brain, indent=2) + "\n", encoding="utf-8")
+    code_dna.write_text(
+        json.dumps({"files": len(files), "symbols": len(symbols), "edges": graph.number_of_edges()}, indent=2) + "\n",
+        encoding="utf-8",
+    )
+    lines = ["# AI Gossip", "", "Most connected files:"]
+    for node, degree in sorted(graph.degree, key=lambda item: item[1], reverse=True)[:20]:
+        lines.append(f"- {node}: {degree} links")
+    ai_gossip.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return [repo_brain, code_dna, ai_gossip]

contextguardrail-0.1.0/contextguardrail/graph.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import ast
+import re
+from pathlib import Path
+from typing import Any
+
+import networkx as nx
+
+from contextguardrail.storage import connect
+
+
+WORD_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]+")
+
+
+def parse_python(text: str) -> dict[str, list[str]]:
+    tree = ast.parse(text)
+    imports: list[str] = []
+    classes: list[str] = []
+    functions: list[str] = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            imports.extend(alias.name for alias in node.names)
+        elif isinstance(node, ast.ImportFrom):
+            if node.module:
+                imports.append(node.module)
+        elif isinstance(node, ast.ClassDef):
+            classes.append(node.name)
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            functions.append(node.name)
+    return {
+        "imports": sorted(set(imports)),
+        "classes": sorted(set(classes)),
+        "functions": sorted(set(functions)),
+    }
+
+
+def parse_file(path: Path, rel_path: str, text: str) -> dict[str, Any]:
+    data: dict[str, Any] = {"imports": [], "classes": [], "functions": []}
+    if path.suffix == ".py":
+        try:
+            data = parse_python(text)
+        except SyntaxError:
+            pass
+    words = WORD_RE.findall(rel_path + " " + text[:8_000])
+    symbols = data["imports"] + data["classes"] + data["functions"]
+    data["keywords"] = sorted(set(w.lower() for w in words + symbols if len(w) > 2))
+    return data
+
+
+def summarize_file(rel_path: str, text: str, parsed: dict[str, Any]) -> str:
+    lines = [f"File: {rel_path}"]
+    if parsed["functions"]:
+        lines.append("Functions: " + ", ".join(parsed["functions"][:30]))
+    if parsed["classes"]:
+        lines.append("Classes: " + ", ".join(parsed["classes"][:30]))
+    if parsed["imports"]:
+        lines.append("Imports: " + ", ".join(parsed["imports"][:20]))
+    doc = next((line.strip("# ").strip() for line in text.splitlines() if line.strip()), "")
+    if doc:
+        lines.append("First line: " + doc[:240])
+    return "\n".join(lines)
+
+
+def upsert_symbols(repo: str | Path, rel_path: str, parsed: dict[str, Any]) -> None:
+    with connect(repo, "graph.db") as db:
+        db.execute(
+            """
+            INSERT INTO symbols(path, imports, classes, functions, keywords)
+            VALUES (?, ?, ?, ?, ?)
+            ON CONFLICT(path) DO UPDATE SET
+              imports=excluded.imports,
+              classes=excluded.classes,
+              functions=excluded.functions,
+              keywords=excluded.keywords
+            """,
+            (
+                rel_path,
+                "\n".join(parsed["imports"]),
+                "\n".join(parsed["classes"]),
+                "\n".join(parsed["functions"]),
+                "\n".join(parsed["keywords"]),
+            ),
+        )
+
+
+def load_graph(repo: str | Path) -> nx.DiGraph:
+    graph = nx.DiGraph()
+    with connect(repo, "graph.db") as db:
+        rows = db.execute("SELECT path, imports, classes, functions FROM symbols").fetchall()
+    paths = {row["path"] for row in rows}
+    module_to_path = {Path(path).with_suffix("").as_posix().replace("/", "."): path for path in paths}
+    for row in rows:
+        path = row["path"]
+        graph.add_node(path, classes=row["classes"].splitlines(), functions=row["functions"].splitlines())
+        for imported in row["imports"].splitlines():
+            target = module_to_path.get(imported)
+            if target:
+                graph.add_edge(path, target, type="imports")
+    return graph
+
+
+def graph_counts(repo: str | Path) -> tuple[int, int]:
+    with connect(repo, "graph.db") as db:
+        rows = db.execute("SELECT classes, functions FROM symbols").fetchall()
+    classes = sum(len(row["classes"].splitlines()) for row in rows if row["classes"])
+    functions = sum(len(row["functions"].splitlines()) for row in rows if row["functions"])
+    return functions, classes

contextguardrail-0.1.0/contextguardrail/scanner.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+from contextguardrail.budget import estimate_tokens
+from contextguardrail.config import CODE_EXTENSIONS, SKIP_DIRS, ensure_state, repo_root
+from contextguardrail.graph import parse_file, summarize_file, upsert_symbols
+from contextguardrail.storage import connect, init_storage
+
+
+def file_hash(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def should_scan(path: Path, rel_path: Path) -> bool:
+    if any(part in SKIP_DIRS for part in rel_path.parts):
+        return False
+    return path.is_file() and path.suffix.lower() in CODE_EXTENSIONS
+
+
+def iter_files(root: Path):
+    for path in root.rglob("*"):
+        if should_scan(path, path.relative_to(root)):
+            yield path
+
+
+def read_text(path: Path) -> str:
+    return path.read_text(encoding="utf-8", errors="ignore")
+
+
+def index_repo(path: str | Path = ".", incremental: bool = False) -> dict[str, int]:
+    root = repo_root(path)
+    state = ensure_state(root)
+    init_storage(root)
+
+    scanned = changed = skipped = raw_tokens = 0
+    for file_path in iter_files(root):
+        rel_path = file_path.relative_to(root).as_posix()
+        digest = file_hash(file_path)
+        stat = file_path.stat()
+        with connect(root, "hashes.db") as db:
+            existing = db.execute("SELECT hash FROM files WHERE path = ?", (rel_path,)).fetchone()
+        if incremental and existing and existing["hash"] == digest:
+            skipped += 1
+            continue
+
+        text = read_text(file_path)
+        tokens = estimate_tokens(text)
+        parsed = parse_file(file_path, rel_path, text)
+        summary = summarize_file(rel_path, text, parsed)
+        summary_path = state / "summaries" / f"{hashlib.sha256(rel_path.encode()).hexdigest()}.md"
+        summary_path.write_text(summary + "\n", encoding="utf-8")
+
+        with connect(root, "hashes.db") as db:
+            db.execute(
+                """
+                INSERT INTO files(path, hash, size, mtime, tokens, summary)
+                VALUES (?, ?, ?, ?, ?, ?)
+                ON CONFLICT(path) DO UPDATE SET
+                  hash=excluded.hash,
+                  size=excluded.size,
+                  mtime=excluded.mtime,
+                  tokens=excluded.tokens,
+                  summary=excluded.summary,
+                  updated_at=CURRENT_TIMESTAMP
+                """,
+                (rel_path, digest, stat.st_size, stat.st_mtime, tokens, summary),
+            )
+        upsert_symbols(root, rel_path, parsed)
+        scanned += 1
+        changed += 1
+        raw_tokens += tokens
+
+    return {
+        "files_scanned": scanned,
+        "files_changed": changed,
+        "files_skipped": skipped,
+        "raw_tokens": raw_tokens,
+    }

contextguardrail-0.1.0/contextguardrail/selector.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from contextguardrail.config import DEFAULT_BUDGET
+from contextguardrail.storage import connect
+
+
+WORD_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]+")
+
+
+def prompt_terms(prompt: str) -> set[str]:
+    return {word.lower() for word in WORD_RE.findall(prompt) if len(word) > 2}
+
+
+def score_row(row, terms: set[str]) -> int:
+    haystack = "\n".join(
+        [row["path"], row["summary"], row["keywords"], row["classes"], row["functions"]]
+    ).lower()
+    score = sum(5 for term in terms if term in row["path"].lower())
+    score += sum(3 for term in terms if term in row["classes"].lower() or term in row["functions"].lower())
+    score += sum(1 for term in terms if term in haystack)
+    if any(term in row["path"].lower() for term in ("auth", "user", "api", "cache", "config", "setting")):
+        score += 1
+    return score
+
+
+def select_context(
+    repo: str | Path,
+    prompt: str,
+    budget: int = DEFAULT_BUDGET,
+    exclude_unchanged: dict[str, str] | None = None,
+) -> tuple[list[dict], int]:
+    terms = prompt_terms(prompt)
+    exclude_unchanged = exclude_unchanged or {}
+    with connect(repo, "hashes.db") as files_db, connect(repo, "graph.db") as graph_db:
+        rows = files_db.execute(
+            "SELECT path, hash, tokens, summary FROM files ORDER BY path"
+        ).fetchall()
+        symbols = {
+            row["path"]: row
+            for row in graph_db.execute(
+                "SELECT path, classes, functions, keywords FROM symbols"
+            ).fetchall()
+        }
+
+    candidates = []
+    raw_tokens = 0
+    for row in rows:
+        raw_tokens += int(row["tokens"])
+        if exclude_unchanged.get(row["path"]) == row["hash"]:
+            continue
+        symbol = symbols.get(row["path"])
+        merged = {
+            "path": row["path"],
+            "hash": row["hash"],
+            "tokens": int(row["tokens"]),
+            "summary": row["summary"],
+            "classes": symbol["classes"] if symbol else "",
+            "functions": symbol["functions"] if symbol else "",
+            "keywords": symbol["keywords"] if symbol else "",
+        }
+        score = score_row(merged, terms)
+        if score > 0:
+            candidates.append((score, merged))
+
+    candidates.sort(key=lambda item: (-item[0], item[1]["tokens"], item[1]["path"]))
+    selected = []
+    used = 0
+    for _, item in candidates:
+        summary_tokens = max(30, min(item["tokens"], int(item["tokens"] * 0.25)))
+        if selected and used + summary_tokens > budget:
+            continue
+        selected.append(item)
+        used += summary_tokens
+        if used >= budget:
+            break
+
+    if not selected:
+        selected = [item for _, item in candidates[:5]]
+    return selected, raw_tokens

contextguardrail-0.1.0/contextguardrail/stats.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from contextguardrail.budget import cost_usd
+from contextguardrail.storage import load_stats, save_stats
+
+
+def record_request(
+    repo: str | Path,
+    raw_tokens: int,
+    optimized_tokens: int,
+    cache_hit: bool = False,
+) -> dict:
+    stats = load_stats(repo)
+    saved = max(0, raw_tokens - optimized_tokens)
+    stats["requests"] += 1
+    stats["raw_tokens"] += raw_tokens
+    stats["optimized_tokens"] += optimized_tokens
+    stats["input_tokens_saved"] += saved
+    stats["estimated_cost_saved"] = round(
+        stats.get("estimated_cost_saved", 0.0) + cost_usd(saved), 4
+    )
+    if cache_hit:
+        stats["cache_hits"] += 1
+    save_stats(repo, stats)
+    return stats
+
+
+def show_stats(repo: str | Path = ".") -> dict:
+    return load_stats(repo)

contextguardrail-0.1.0/contextguardrail/storage.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+from contextguardrail.config import ensure_state
+
+
+def db_path(repo: str | Path, name: str) -> Path:
+    return ensure_state(repo) / name
+
+
+def connect(repo: str | Path, name: str) -> sqlite3.Connection:
+    connection = sqlite3.connect(db_path(repo, name))
+    connection.row_factory = sqlite3.Row
+    return connection
+
+
+def init_storage(repo: str | Path = ".") -> None:
+    ensure_state(repo)
+    with connect(repo, "hashes.db") as db:
+        db.execute(
+            """
+            CREATE TABLE IF NOT EXISTS files(
+                path TEXT PRIMARY KEY,
+                hash TEXT NOT NULL,
+                size INTEGER NOT NULL,
+                mtime REAL NOT NULL,
+                tokens INTEGER NOT NULL,
+                summary TEXT NOT NULL,
+                updated_at TEXT DEFAULT CURRENT_TIMESTAMP
+            )
+            """
+        )
+    with connect(repo, "graph.db") as db:
+        db.execute(
+            """
+            CREATE TABLE IF NOT EXISTS symbols(
+                path TEXT PRIMARY KEY,
+                imports TEXT NOT NULL,
+                classes TEXT NOT NULL,
+                functions TEXT NOT NULL,
+                keywords TEXT NOT NULL
+            )
+            """
+        )
+    with connect(repo, "cache.db") as db:
+        db.execute(
+            """
+            CREATE TABLE IF NOT EXISTS cache(
+                key TEXT PRIMARY KEY,
+                response TEXT NOT NULL,
+                created_at TEXT DEFAULT CURRENT_TIMESTAMP
+            )
+            """
+        )
+        db.execute(
+            """
+            CREATE TABLE IF NOT EXISTS replay(
+                prompt_hash TEXT PRIMARY KEY,
+                files TEXT NOT NULL,
+                file_hashes TEXT NOT NULL,
+                created_at TEXT DEFAULT CURRENT_TIMESTAMP
+            )
+            """
+        )
+    stats_file(repo).write_text(
+        json.dumps(load_stats(repo), indent=2) + "\n", encoding="utf-8"
+    )
+
+
+def stats_file(repo: str | Path) -> Path:
+    return ensure_state(repo) / "costs.json"
+
+
+def load_stats(repo: str | Path) -> dict[str, Any]:
+    path = stats_file(repo)
+    if not path.exists():
+        return {
+            "requests": 0,
+            "input_tokens_saved": 0,
+            "output_tokens_saved": 0,
+            "cache_hits": 0,
+            "raw_tokens": 0,
+            "optimized_tokens": 0,
+            "estimated_cost_saved": 0.0,
+        }
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def save_stats(repo: str | Path, stats: dict[str, Any]) -> None:
+    stats_file(repo).write_text(json.dumps(stats, indent=2) + "\n", encoding="utf-8")

contextguardrail-0.1.0/contextguardrail.egg-info/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: contextguardrail
+Version: 0.1.0
+Summary: Local-first token firewall for AI coding agents
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13.0
+Requires-Dist: networkx>=3.0
+Requires-Dist: tiktoken>=0.7
+
+# ContextGuardrail
+
+ContextGuardrail is a local-first MVP for reducing AI coding-agent context. It scans a repo, builds a lightweight code graph, selects relevant files for a prompt, prevents replaying already-sent files, caches repeated asks, and reports estimated token/cost savings.
+
+## Install locally
+
+```bash
+cd /Users/homesachin/Desktop/zoneone/contextguardrail
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Use
+
+```bash
+contextguardrail init
+contextguardrail index /path/to/repo
+contextguardrail ask "Where is authentication handled?"
+contextguardrail stats
+contextguardrail export
+contextguardrail clean
+```
+
+All state is stored in the indexed repo under `.contextguardrail/`.
+
+## MVP Features
+
+- Repo scanner with incremental hashing
+- Python AST parser for imports, classes, functions, and summaries
+- Lightweight dependency graph
+- Context selector using prompt keywords and graph metadata
+- Token counting with `tiktoken` when available, word-count fallback otherwise
+- Semantic cache for repeated prompt and selected-file sets
+- Replay prevention so already-sent files are skipped unless changed
+- Context diffing via file hashes
+- Cost observability through `contextguardrail stats`
+
+This version intentionally skips dashboards, multi-user support, Neo4j, and agent orchestration.
+
+
+## Project Layout
+
+```
+contextguardrail/
+├── pyproject.toml              # Package metadata, dependencies, CLI entrypoints
+├── README.md                   # Project documentation and usage guide
+├── contextguardrail/
+│   ├── scanner.py              # Scan repo and detect files, hashes, changes
+│   ├── config.py               # Global settings and configuration loading
+│   ├── budget.py               # Token estimation and budget enforcement
+│   ├── exporter.py             # Export graph, summaries, and reports
+│   ├── graph.py                # Build dependency graph from source code
+│   ├── selector.py             # Select most relevant context for a prompt
+│   ├── cache.py                # Semantic cache and replay prevention
+│   ├── cli.py                  # Main CLI commands exposed to users
+│   ├── stats.py                # Usage metrics and cost-saving reports
+│   └── storage.py              # SQLite helpers and persistence layer
+└── tests/
+    └── test_budget.py          # Unit tests for token budgeting logic
+```

contextguardrail-0.1.0/contextguardrail.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+README.md
+pyproject.toml
+contextguardrail/__init__.py
+contextguardrail/budget.py
+contextguardrail/cache.py
+contextguardrail/cli.py
+contextguardrail/config.py
+contextguardrail/exporter.py
+contextguardrail/graph.py
+contextguardrail/scanner.py
+contextguardrail/selector.py
+contextguardrail/stats.py
+contextguardrail/storage.py
+contextguardrail.egg-info/PKG-INFO
+contextguardrail.egg-info/SOURCES.txt
+contextguardrail.egg-info/dependency_links.txt
+contextguardrail.egg-info/entry_points.txt
+contextguardrail.egg-info/requires.txt
+contextguardrail.egg-info/top_level.txt
+tests/test_budget.py

contextguardrail-0.1.0/contextguardrail.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

contextguardrail-0.1.0/contextguardrail.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+contextguardrail = contextguardrail.cli:app

contextguardrail-0.1.0/contextguardrail.egg-info/requires.txt

@@ -0,0 +1,4 @@
+typer>=0.12
+rich>=13.0
+networkx>=3.0
+tiktoken>=0.7

contextguardrail-0.1.0/contextguardrail.egg-info/top_level.txt

@@ -0,0 +1 @@
+contextguardrail

contextguardrail-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "contextguardrail"
+version = "0.1.0"
+description = "Local-first token firewall for AI coding agents"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "typer>=0.12",
+  "rich>=13.0",
+  "networkx>=3.0",
+  "tiktoken>=0.7"
+]
+
+[project.scripts]
+contextguardrail = "contextguardrail.cli:app"
+
+[tool.setuptools.packages.find]
+include = ["contextguardrail*"]

contextguardrail-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

contextguardrail-0.1.0/tests/test_budget.py

@@ -0,0 +1,5 @@
+from contextguardrail.budget import estimate_tokens
+
+
+def test_estimate_tokens_returns_positive_count():
+    assert estimate_tokens("hello world") > 0