ctxgraph-code 0.6.1__tar.gz → 0.6.2__tar.gz

{ctxgraph_code-0.6.1/src/ctxgraph_code.egg-info → ctxgraph_code-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctxgraph-code
-Version: 0.6.1
+Version: 0.6.2
 Summary: Code knowledge graph for Claude Code. Build a relationship graph of your Python codebase and query it during coding sessions.
 Author: ctxgraph-code contributors
 License: MIT
@@ -26,7 +26,13 @@ Requires-Dist: pytest>=7.0; extra == "dev"
 
 # ctxgraph-code
 
-**Code knowledge graph for Claude Code.** Build a relationship graph of your codebase (Python, JavaScript, TypeScript, C, Go, Rust, and more) so Claude Code understands imports, class hierarchies, function calls, and cross-file dependencies without reading every file.
+**How do we give AI the right context without sending the entire codebase every time?**
+
+`ctxgraph-code` answers that question. Instead of dumping files into the context window, it builds a **relationship graph** of your codebase using static AST analysis, stores it in a local SQLite database, and retrieves only the relevant symbols and dependencies when Claude Code needs to understand your code.
+
+**Result:** One codebase question drops from ~25,000 tokens to ~800 tokens — a **95% reduction** in context usage. A full 30-question benchmark showed **90% fewer tokens** than traditional file reading, and **16% fewer than graph-based alternatives**.
+
+![Product Overview](https://raw.githubusercontent.com/shashi3070/ctxgraph-code/master/docs/benchmark2.jpg)
 
 ```bash
 pip install ctxgraph-code
@@ -67,6 +73,29 @@ ctxgraph-code setup
 #   /ctxgraph-code
 ```
 
+## How It Works (At a Glance)
+
+```
+Your Codebase
+     │
+     ▼
+1. Static AST Analysis ──► Extract imports, classes, functions, calls, relationships
+     │
+     ▼
+2. Knowledge Graph ──► Store everything in local SQLite (files, symbols, edges)
+     │
+     ▼
+3. Query Engine ──► Search graph by relevance, expand to neighbors via BFS
+     │
+     ▼
+4. Context Retrieval ──► Only the relevant snippets, not whole files
+     │
+     ▼
+5. Claude Code ──► Receives focused context → Better answers, fewer tokens, less noise
+```
+
+No huge graph-building prompts sent to the LLM. The graph is built locally with Python's AST parser — zero LLM calls, zero API costs.
+
 ## Commands
 
 ### `setup` (recommended)
@@ -113,6 +142,37 @@ ctxgraph-code init
 
 Creates the `.ctxgraph/` directory with a default `config.toml`.
 
+### `subgraph`
+
+```bash
+ctxgraph-code subgraph "add pagination to the users endpoint"
+```
+
+Extracts a **focused subgraph** relevant to a task description — returns matching nodes, their relationships, and inline source code in a single compact response. Saves 1-2 tool calls by combining graph search, dependency resolution, and file reading.
+
+- `--max-nodes` / `-n` — max nodes in subgraph (default: 10)
+
+### `diff`
+
+```bash
+ctxgraph-code diff
+ctxgraph-code diff --ref main
+```
+
+Compares the graph with the filesystem. Shows files that have been **added, removed, or changed** since the graph was built. Use `--ref` for a git-aware diff against a branch. Essential for knowing when to run `ctxgraph-code build --incremental`.
+
+### `mermaid`
+
+```bash
+ctxgraph-code mermaid classDiagram
+ctxgraph-code mermaid flowchart --output diagram.md
+```
+
+Exports the graph as a **Mermaid diagram** for embedding in documentation or PRs. Supported types: `classDiagram`, `flowchart`, `sequence`.
+
+- `--output` / `-o` — save to file instead of stdout
+- `--max-nodes` / `-n` — maximum nodes in diagram (default: 50)
+
 ### `build`
 
 ```bash
@@ -348,6 +408,105 @@ This catches the common case where you edit a file after building the graph and
 
 ---
 
+## Benchmark Results
+
+Real-world benchmarks against a production Python/UI codebase. Three approaches compared across 30 code understanding questions.
+
+### Repository Profile
+
+| Metric | Value |
+|---|---|
+| Backend Python LOC | 45,570 |
+| UI Source LOC | 37,317 |
+| Documentation LOC | 9,120 |
+| Source Files | 143 |
+| Raw Tokens | ~140,000 |
+
+### Three Retrieval Methods Compared
+
+| Approach | How It Works |
+|---|---|
+| **Baseline** (File Reading) | `grep` → read entire files → answer. Every question repeatedly loads large source files. |
+| **Graphify** (Knowledge Graph) | Build full graph → compressed node summaries → answer. Incurs large upfront graph-building cost. |
+| **CtxGraph-Code** (Symbol Graph) | Local AST → SQLite symbol graph → retrieve only relevant files → answer. Only targeted files opened. |
+
+### Combined Results (30 Questions)
+
+| Approach | Total Tokens | Avg/Question | Reduction |
+|---|---|---|---|
+| Baseline (File Reading) | 203,590 | 6,786 | — |
+| Graphify | 25,100 | 837 | 88% |
+| **CtxGraph-Code** | **21,120** | **704** | **90%** |
+
+CtxGraph-Code is **9.6× more efficient** than reading raw files, and uses **16% fewer tokens** than Graphify.
+
+![Benchmark Comparison](https://raw.githubusercontent.com/shashi3070/ctxgraph-code/master/docs/Benchmark%20Vs%20Graphify.jpg)
+
+### Per-Suite Breakdown
+
+| Suite | Baseline | Graphify | CtxGraph-Code | Winner |
+|---|---|---|---|---|
+| BM1: Architecture | 73,500 | 12,100 | 10,150 | CtxGraph-Code |
+| BM2: Data Flow & UI Logic | 130,090 | 13,000 | 10,970 | CtxGraph-Code |
+| **Combined** | **203,590** | **25,100** | **21,120** | **CtxGraph-Code** |
+
+### Biggest Win: File Comparison
+
+Question: *"How does tasks_fixed.py differ from tasks.py?"*
+
+- `tasks.py`: 2,372 lines
+- `tasks_fixed.py`: 1,512 lines
+
+| Approach | Tokens |
+|---|---|
+| Baseline | 31,070 |
+| Graphify | 1,400 |
+| **CtxGraph-Code** | **1,150 (96% savings)** |
+
+Instead of reading both files completely, CtxGraph-Code compares symbols and retrieves only relevant differences.
+
+### Context Window Longevity
+
+With a 200K token context window:
+
+| Approach | Tokens/Question | Questions Before Exhaustion |
+|---|---|---|
+| Baseline | 6,786 | ~29 |
+| Graphify | 837 | ~239 |
+| **CtxGraph-Code** | **704** | **~284 (10× longer sessions)** |
+
+### Graphify vs CtxGraph-Code: Detailed Comparison
+
+![Phase-by-Phase Comparison](https://raw.githubusercontent.com/shashi3070/ctxgraph-code/master/docs/Benchmark%20Vs%20Graphify.jpg)
+
+| Metric | Graphify | CtxGraph-Code |
+|---|---|---|
+| **Build approach** | Full knowledge graph first | Local symbol graph via AST + SQLite |
+| **Upfront LLM cost** | ~141,728 input tokens | ~0 tokens (local AST parse, ~246s) |
+| **Total input tokens** | ~157,728 | ~22,500 (**85.7% fewer**) |
+| **Output tokens** | ~12,000 | ~3,500 (**70.8% fewer**) |
+| **Query speed** | Moderate (BFS/DFS traversal) | Fast (SQLite indexed lookup) |
+| **Strengths** | Architecture visualization, community detection, cross-file relationship discovery | Inline source retrieval, indexed search, symbol resolution, implementation-focused answers |
+| **Weaknesses** | No implementation snippets; often requires opening source files after | Less visualization; relationship discovery less deep |
+| **Best for** | Architecture discovery, planning, cross-cutting concerns | Code navigation, execution flow, symbol lookup, implementation questions |
+
+**Bottom line:** Use CtxGraph-Code for fast code search and implementation answers. Use Graphify when you need architecture visualization and cross-file relationship discovery.
+
+### Real-World Example Results
+
+| Question | Without | With CtxGraph-Code | Savings |
+|---|---|---|---|
+| Learning Mode | 9,498 | 3,267 | 66% |
+| Planner Node | 13,166 | 7,043 | 47% |
+| Dashboard Embedding | 5,180 | 2,840 | 45% |
+| Authentication | 9,498 | 3,267 | 66% |
+| Deep Learning Mode | 25,000 | 800 | 95% |
+| **Overall (30 questions)** | **203,590** | **21,120** | **90%** |
+
+![Detailed Benchmark Results](https://raw.githubusercontent.com/shashi3070/ctxgraph-code/master/docs/benchmark1.jpg)
+
+---
+
 ## Using with Claude Code
 
 After `ctxgraph-code setup`, the `/ctxgraph-code` slash command is installed globally by default — it works in every Claude Code session. Claude sees:
@@ -367,6 +526,9 @@ After `ctxgraph-code setup`, the `/ctxgraph-code` slash command is installed glo
 - `ctxgraph-code overview --dir <name>` -- Show project structure for a specific graph
 - `ctxgraph-code symbols <path>` -- List classes/functions defined in a file
 - `ctxgraph-code context "task"` -- Generate a focused context summary
+- `ctxgraph-code subgraph "task"` -- Focused subgraph with inline source
+- `ctxgraph-code diff` -- Files changed since build
+- `ctxgraph-code mermaid --type classDiagram` -- Export as Mermaid diagram
 - `ctxgraph-code view --dir <name>` -- Visualize a graph interactively
 ```
 
@@ -404,13 +566,30 @@ Built-in default exclusion patterns (always applied): `__pycache__`, `*.pyc`, `.
 
 ---
 
+## Where It Helps
+
+`ctxgraph-code` delivers the most value when working with **existing codebases built over months or years**:
+
+| Helps Most | Helps Less |
+|---|---|
+| 🐛 Debugging production issues | Tiny projects (2–3 files) |
+| 🏗 Understanding architecture | Throwaway scripts |
+| 🔍 Tracing dependencies | Greenfield projects created entirely in the same Claude session |
+| 🔄 Safe refactoring | Short experiments |
+| 📚 Onboarding into large existing codebases | |
+| 🧩 Multi-module repositories | |
+
+The biggest gains come when AI needs to understand **existing code written over months or years**, not when starting from scratch.
+
+---
+
 ## Differences from `ctxgraph`
 
 `ctxgraph-code` is a **focused subset** of [ctxgraph](https://github.com/shashi3070/ctxgraph) designed specifically for Claude Code.
 
 | Feature | ctxgraph | ctxgraph-code |
 |---------|----------|---------------|
-| CLI commands | 9+ | 17 (init, build, query, deps, usedby, overview, symbols, context, setup, view, info, install-slash, build-status, probe, install-hooks, uninstall-hooks, version) |
+| CLI commands | 9+ | 20 (init, build, query, deps, usedby, overview, symbols, context, subgraph, diff, mermaid, setup, view, info, install-slash, build-status, probe, install-hooks, uninstall-hooks, version) |
 | LLM integration | Built-in (Ollama, Claude, OpenAI, Azure) | None (delegates to Claude Code) |
 | Chat sessions | Yes | No |
 | Visualizer | D3.js HTML + SVG | D3.js HTML (`view` opens in browser, `--tree` for text) |