code-context-engine 0.4.4__py3-none-any.whl → 0.4.6__py3-none-any.whl

{code_context_engine-0.4.4.dist-info → code_context_engine-0.4.6.dist-info}/METADATA

@@ -1,14 +1,14 @@
 Metadata-Version: 2.4
 Name: code-context-engine
-Version: 0.4.4
-Summary: Index your codebase. AI searches instead of re-reading files. Save 70%+ on tokens. Works with Claude Code, Cursor, VS Code, Gemini CLI, and Codex.
+Version: 0.4.6
+Summary: Index your codebase. AI searches instead of re-reading files. 94% token savings, benchmarked on FastAPI. Works with Claude Code, Cursor, VS Code, Gemini CLI, and Codex.
 Author-email: Fazle Elahee <felahee@gmail.com>, Raj <rajkumar.sakti@gmail.com>
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/elara-labs/code-context-engine
 Project-URL: Repository, https://github.com/elara-labs/code-context-engine
 Project-URL: Issues, https://github.com/elara-labs/code-context-engine/issues
 Keywords: claude,context,mcp,llm,code-indexing,vector-search
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
@@ -37,6 +37,7 @@ Requires-Dist: httpx>=0.27
 Requires-Dist: fastapi>=0.110
 Requires-Dist: uvicorn>=0.29
 Requires-Dist: aiohttp>=3.9
+Requires-Dist: psutil>=5.9
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
@@ -53,10 +54,11 @@ Dynamic: license-file
 <h1 align="center">Code Context Engine</h1>
 
 <p align="center">
-  <strong>Index your codebase. AI searches instead of re-reading files. 93% token savings, benchmarked.</strong>
+  <strong>Index your codebase. AI searches instead of re-reading files. 94% token savings, benchmarked.</strong>
 </p>
 
 <p align="center">
+  <a href="https://github.com/elara-labs/code-context-engine/actions/workflows/ci.yml"><img src="https://github.com/elara-labs/code-context-engine/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://pypi.org/project/code-context-engine/"><img src="https://img.shields.io/pypi/v/code-context-engine?color=blue&label=PyPI" alt="PyPI"></a>
   <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+"></a>
   <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-green.svg" alt="MCP Compatible"></a>
@@ -87,6 +89,14 @@ Dynamic: license-file
 
 ---
 
+## System requirements
+
+- Python 3.11+
+- A C compiler and `cmake` (needed to build tree-sitter grammars)
+  - **macOS:** `xcode-select --install`
+  - **Ubuntu/Debian:** `sudo apt install build-essential cmake`
+  - **Windows:** Visual Studio Build Tools (C++ workload)
+
 ## Install and see savings in 60 seconds
 
 ```bash
@@ -112,7 +122,7 @@ Multiple editors in the same project? All get configured in one command.
 ```
   my-project · 38 queries
 
-  ⛁ ⛁ ⛁ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶  93% tokens saved
+  ⛁ ⛁ ⛁ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶  94% tokens saved
 
   Without CCE   48.0k  tokens   $0.24
   With CCE       3.4k  tokens   $0.02
@@ -126,7 +136,7 @@ Multiple editors in the same project? All get configured in one command.
 
 ## Why this matters
 
-Input tokens are 85-95% of your Claude Code bill. CCE cuts them by 93% ([benchmarked on FastAPI](#benchmark-fastapi-independently-verified)).
+Input tokens are 85-95% of your Claude Code bill. CCE cuts them by 94% ([benchmarked on FastAPI](#benchmark-fastapi-independently-verified)).
 
 ```
 Without CCE:    Claude reads payments.py + shipping.py   = 45,000 tokens
@@ -144,17 +154,16 @@ With CCE:       context_search "payment flow"            =    800 tokens
 
 ## Benchmark: FastAPI (independently verified)
 
-We benchmarked CCE against [FastAPI](https://github.com/fastapi/fastapi) (48 source files, 19K lines of Python) with 20 real coding questions. No cherry-picking, no synthetic queries.
+We benchmarked CCE against [FastAPI](https://github.com/fastapi/fastapi) (53 source files, 180K tokens) with 20 real coding questions. No cherry-picking, no synthetic queries.
 
 **Methodology:** For each query, "without CCE" means reading the full content of every file the query touches. "With CCE" means the relevant chunks after compression. This is conservative (agents often read more files than needed).
 
 | Metric | Result |
 |--------|--------|
-| **Retrieval** | **93%** savings (75,355 → 5,381 tokens/query) |
-| **+ Compression** | **90%** additional (5,381 → 541 tokens/query) |
-| **Combined** | **99.3%** (75,355 → 541 tokens/query) |
-| Recall@10 (found the right files) | 0.80 |
-| Precision@10 | 0.30 |
+| **Retrieval** | **94%** savings (83,681 → 4,927 tokens/query) |
+| **+ Compression** | **89%** additional (4,927 → 523 tokens/query) |
+| **Combined** | **99.4%** (83,681 → 523 tokens/query) |
+| Recall@10 (found the right files) | 0.90 |
 | Latency p50 | 0.4ms |
 | Queries tested | 20 |
 
@@ -162,8 +171,8 @@ We benchmarked CCE against [FastAPI](https://github.com/fastapi/fastapi) (48 sou
 
 | Layer | What it does | Savings | Method |
 |-------|-------------|---------|--------|
-| **Retrieval** | Full files → relevant code chunks | 93% | measured |
-| **Chunk Compression** | Raw chunks → signatures + docstrings | 90% | measured |
+| **Retrieval** | Full files → relevant code chunks | 94% | measured |
+| **Chunk Compression** | Raw chunks → signatures + docstrings | 89% | measured |
 | **Output Compression** | Reduces Claude's reply length | 65% | estimated |
 | **Grammar** | Drops articles/fillers from memory text | 13% | measured |
 
@@ -210,6 +219,14 @@ cce savings --all    # see savings across all projects
 
 ---
 
+## How is CCE different?
+
+CCE is editor-agnostic, local-first, and gives you measurable token savings. Your code never leaves your machine. Unlike built-in indexing (Cursor, Continue), CCE works across Claude Code, VS Code, Cursor, Gemini CLI, and Codex with a single index. Unlike cloud tools (Greptile), it's free and private.
+
+See the [full comparison with alternatives](docs/comparison.md) for an honest look at trade-offs.
+
+---
+
 ## How it works (the short version)
 
 1. **Index:** Tree-sitter parses your code into semantic chunks (functions, classes, modules). Stored as vector embeddings locally.
@@ -228,7 +245,7 @@ Re-indexing after edits takes under 1 second (96% embedding cache hit rate). Git
 
 Output compression tools (like Caveman) save 20-75% on output tokens. Output is 5-15% of your bill. Net savings: ~11%.
 
-CCE saves on **input** tokens (93% retrieval + 90% compression on FastAPI, [independently benchmarked](#benchmark-fastapi-independently-verified)). Input is 85-95% of your bill.
+CCE saves on **input** tokens (94% retrieval + 89% compression on FastAPI, [independently benchmarked](#benchmark-fastapi-independently-verified)). Input is 85-95% of your bill.
 
 ### It actually understands your code
 
@@ -398,7 +415,7 @@ No GPU required. Embedding model runs on CPU via ONNX Runtime.
 - [x] Clean uninstall (removes all CCE artifacts)
 - [x] AST-aware chunking for PHP, Go, Rust, Java (tree-sitter)
 - [x] Multi-editor support (Cursor, VS Code/Copilot, Gemini CLI)
-- [x] Reproducible benchmark suite (93% savings on FastAPI, per-layer breakdown)
+- [x] Reproducible benchmark suite (94% savings on FastAPI, per-layer breakdown)
 - [x] Session savings visibility (shown at every session start)
 - [ ] Tree-sitter support for C, C++, Ruby, Swift, Kotlin
 - [ ] Docker support for remote mode

{code_context_engine-0.4.4.dist-info → code_context_engine-0.4.6.dist-info}/RECORD

@@ -1,8 +1,8 @@
-code_context_engine-0.4.4.dist-info/licenses/LICENSE,sha256=vLbw0GGCVJSIRppMus7Oq0PyMDhDXz-dfvz2rPpWtjQ,1069
+code_context_engine-0.4.6.dist-info/licenses/LICENSE,sha256=vLbw0GGCVJSIRppMus7Oq0PyMDhDXz-dfvz2rPpWtjQ,1069
 context_engine/__init__.py,sha256=qThGxB7xfZi5M9jDpUno0MKBp7KKrEOdH1hG4wHMuLc,193
-context_engine/cli.py,sha256=KcOO3WSbo8joKcSPJlKKhpVFsnLDIffKmqTLx5PGs14,113198
+context_engine/cli.py,sha256=3m4UHGkURqlhnyr6AslU7fuansvD6TMR2VDrPjd0Yhc,113375
 context_engine/cli_style.py,sha256=a3l3Smq1gIN2asbNalFUz0i_5x7Tmkp_wEhyGMoo8a4,2460
-context_engine/config.py,sha256=FU8Hn8-9KCLGhjImsMbmV9WGNZyWp_qOtWW4BxI-URQ,7202
+context_engine/config.py,sha256=2pCe-nJbB1IgrFwT3iMOmUSZMaaH2IBamm867CULdnY,7129
 context_engine/editors.py,sha256=LT_WdYwyB1EeH1xsB6DDtJlbGMKXOTIVSOWXOOfXh1U,8970
 context_engine/event_bus.py,sha256=g4r9QKuC-Y7RmrjOTlUrJSB-bBTpAqp0-_IXeMUg4wo,775
 context_engine/models.py,sha256=XBbM0CUqNDQ5MOp6F3STST2qLqy2Zk0m050ZtWdXkrk,2048
@@ -46,9 +46,9 @@ context_engine/memory/hook_server.py,sha256=y62r7TGxXIDIAMiAcebIyqHE0fU5u-1dq3qG
 context_engine/memory/hooks.py,sha256=q3UAOOsRJAiYh_OFj6AsemUVy95tsZAp-S8ok3WRTUg,14129
 context_engine/memory/migrate.py,sha256=X5w6t96mWXz5p_CtEHYNQEpmCvcnwJ0uVsXeM9k3Xro,9447
 context_engine/retrieval/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-context_engine/retrieval/confidence.py,sha256=gOjL_T-_s1OSg0rKIzCh0ishmZ0Vw6LMB9qq7pr6WsE,1621
+context_engine/retrieval/confidence.py,sha256=y7fcIPKzSE0dXRNmoHid4z4otxiE-at901G0jK2gujA,1621
 context_engine/retrieval/query_parser.py,sha256=ljxkD25HVE4yrikmq2UJO6aLPTnDM43RLpYWQ1huh6k,3532
-context_engine/retrieval/retriever.py,sha256=w-4A59aVA1kJtLixdlk0q9mG7M5k91DfNz7Pzu1EdG0,8240
+context_engine/retrieval/retriever.py,sha256=LeZROv0k-WGjJTZ_A4WDK5pNivq-s6b2-Mk-9A5YAO0,8947
 context_engine/storage/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 context_engine/storage/backend.py,sha256=2GjQ8wqs09lG-plqJOH9pBjvb3hZrFLIq1332BRnF2E,1062
 context_engine/storage/fts_store.py,sha256=cUvftCeBxD_2jLG-rjV2iOjg-LeUI0dmtxfUYA_ICjQ,3991
@@ -56,8 +56,8 @@ context_engine/storage/graph_store.py,sha256=mftuJFvlkFeBlzMsQorY5YS4l5wsDUxCMw5
 context_engine/storage/local_backend.py,sha256=5MVoAn6Jkiltho-9BjClisLkyXMkSZZc2Z_h3N7Vfcg,4200
 context_engine/storage/remote_backend.py,sha256=u77lnGIvqrL3PwInjT6nfRgyNn6oVxW92KUK66oWrvI,5504
 context_engine/storage/vector_store.py,sha256=tA0ol_v5B2KRNMt2hE2kI4qnYe_AoYP_HSp1MvzcsFU,14704
-code_context_engine-0.4.4.dist-info/METADATA,sha256=CHQ_RdzQCryh6CJi_bUjrPtY2KPxdiZPC5GOuovwTsM,17592
-code_context_engine-0.4.4.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-code_context_engine-0.4.4.dist-info/entry_points.txt,sha256=DQuRWUuVFM7nPcXtDmJzlem7QA0IboD_4N8AnTtDD9Q,144
-code_context_engine-0.4.4.dist-info/top_level.txt,sha256=X1-RUqb61WXBjy3JjsW2oXwfvqk2ydXKDNidxmw4CZ4,15
-code_context_engine-0.4.4.dist-info/RECORD,,
+code_context_engine-0.4.6.dist-info/METADATA,sha256=EMG78MwkTq3rKZK-PBuafCTw95vh2n8URpfmN_r9JC8,18507
+code_context_engine-0.4.6.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+code_context_engine-0.4.6.dist-info/entry_points.txt,sha256=DQuRWUuVFM7nPcXtDmJzlem7QA0IboD_4N8AnTtDD9Q,144
+code_context_engine-0.4.6.dist-info/top_level.txt,sha256=X1-RUqb61WXBjy3JjsW2oXwfvqk2ydXKDNidxmw4CZ4,15
+code_context_engine-0.4.6.dist-info/RECORD,,

context_engine/cli.py

@@ -1674,12 +1674,10 @@ def search(ctx: click.Context, query: str, top_k: int) -> None:
             lines.append(f"    {DOT} {dim('No results found')}")
         else:
             # Compute tokens
-            raw_tokens = 0
             served_tokens = 0
             seen_files: set[str] = set()
             for r in results:
                 chunk_tokens = max(1, len(r.content) // 4)
-                raw_tokens += chunk_tokens
                 served_tokens += chunk_tokens
                 seen_files.add(r.file_path)
 
@@ -1702,7 +1700,8 @@ def search(ctx: click.Context, query: str, top_k: int) -> None:
                 lines.append(f"       {dim(first_line)}")
 
             lines.append("")
-            lines.append(f"    {CHECK} {success(f'{len(results)} results')}  {dim(f'{served_tokens} tokens served vs {full_file_tokens} full file tokens')}")
+            savings_pct = int((1 - served_tokens / full_file_tokens) * 100) if full_file_tokens > 0 else 0
+            lines.append(f"    {CHECK} {success(f'{len(results)} results')}  {dim(f'{served_tokens} tokens served vs {full_file_tokens} full file tokens ({savings_pct}% saved)')}")
 
             # Update stats
             stats_path = storage_dir / "stats.json"
@@ -1711,10 +1710,8 @@ def search(ctx: click.Context, query: str, top_k: int) -> None:
             except (json.JSONDecodeError, OSError):
                 stats = {}
             stats["queries"] = stats.get("queries", 0) + 1
-            stats["raw_tokens"] = stats.get("raw_tokens", 0) + raw_tokens
+            stats["full_file_tokens"] = stats.get("full_file_tokens", 0) + full_file_tokens
             stats["served_tokens"] = stats.get("served_tokens", 0) + served_tokens
-            stats.setdefault("full_file_tokens", 0)
-            stats["full_file_tokens"] = max(stats["full_file_tokens"], full_file_tokens)
             stats_path.write_text(json.dumps(stats))
 
         lines.append("")
@@ -1724,12 +1721,19 @@ def search(ctx: click.Context, query: str, top_k: int) -> None:
 
 
 @main.command()
-def uninstall() -> None:
+@click.option("--yes", "-y", is_flag=True, help="Skip confirmation prompt")
+def uninstall(yes: bool) -> None:
     """Remove CCE from the current project (hooks, .mcp.json entry, CLAUDE.md block)."""
     from context_engine.cli_style import section, animate, value, dim, success, warn, CHECK, CROSS, DOT
 
     project_dir = Path.cwd()
     project_name = project_dir.name
+
+    if not yes:
+        if not click.confirm(f"Remove CCE from {project_name}?", default=False):
+            click.echo("Cancelled.")
+            return
+
     lines: list[str] = []
     lines.append("")
     lines.append(section(f"Uninstall · {project_name}"))

context_engine/config.py

@@ -90,11 +90,8 @@ class Config:
     storage_path: str = str(_CCE_HOME / "projects")
 
     def detect_resource_profile(self) -> str:
-        try:
-            import psutil
-            ram_gb = psutil.virtual_memory().total / (1024 ** 3)
-        except ImportError:
-            ram_gb = 16
+        import psutil
+        ram_gb = psutil.virtual_memory().total / (1024 ** 3)
         if ram_gb >= 32:
             return "full"
         if ram_gb >= 12:

context_engine/retrieval/confidence.py

@@ -14,8 +14,8 @@ import time
 from context_engine.models import Chunk
 
 _VECTOR_WEIGHT = 0.5
-_KEYWORD_WEIGHT = 0.3
-_RECENCY_WEIGHT = 0.2
+_KEYWORD_WEIGHT = 0.4
+_RECENCY_WEIGHT = 0.1
 _MAX_KEYWORD_DISTANCE = 5
 _RECENCY_HALF_LIFE = 7 * 24 * 3600  # 1 week
 

context_engine/retrieval/retriever.py

@@ -15,6 +15,9 @@ _RRF_K = 60
 # [0,1] by the best score in the candidate set so an exact-match FTS rank-1 hit
 # scores the same as a vector rank-1 hit instead of being clamped to ~1.0.
 _CONFIDENCE_WEIGHT = 0.5
+# Max chunks from the same file in the final result set. Prevents one large
+# file from dominating results and improves file-level precision.
+_MAX_CHUNKS_PER_FILE = 3
 # When the parsed query looks like a code lookup, give FTS more pull because
 # exact-identifier hits are usually what the user wants.
 _FTS_BOOST_CODE_LOOKUP = 1.5
@@ -129,7 +132,20 @@ class HybridRetriever:
                 scored.append((chunk, final_score))
 
         scored.sort(key=lambda x: x[1], reverse=True)
-        ranked = [chunk for chunk, _ in scored[:top_k]]
+
+        # File diversity: cap chunks per file so one large file doesn't
+        # dominate the result set. This improves precision by letting
+        # chunks from more files surface into the top-k.
+        file_counts: dict[str, int] = {}
+        diverse: list[Chunk] = []
+        for chunk, _ in scored:
+            count = file_counts.get(chunk.file_path, 0)
+            if count < _MAX_CHUNKS_PER_FILE:
+                diverse.append(chunk)
+                file_counts[chunk.file_path] = count + 1
+                if len(diverse) >= top_k:
+                    break
+        ranked = diverse
 
         # Graph expansion: fetch 1-2 bonus chunks from files reachable via
         # CALLS/IMPORTS edges from the top results.