know-cli 0.7.0__tar.gz → 0.7.2__tar.gz

{know_cli-0.7.0 → know_cli-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: know-cli
-Version: 0.7.0
+Version: 0.7.2
 Summary: Context Intelligence for AI Coding Agents — smart, token-budgeted code context
 Project-URL: Homepage, https://github.com/sushilk1991/know-cli
 Project-URL: Repository, https://github.com/sushilk1991/know-cli
@@ -18,6 +18,7 @@ Classifier: Topic :: Software Development :: Documentation
 Classifier: Topic :: Utilities
 Requires-Python: >=3.10
 Requires-Dist: click>=8.1.0
+Requires-Dist: numpy>=1.24.0
 Requires-Dist: pathspec>=0.11.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.0.0
@@ -46,7 +47,6 @@ Provides-Extra: mcp
 Requires-Dist: mcp>=1.0.0; extra == 'mcp'
 Provides-Extra: search
 Requires-Dist: fastembed>=0.3.0; extra == 'search'
-Requires-Dist: numpy>=1.24.0; extra == 'search'
 Description-Content-Type: text/markdown
 
 # know — 3x Fewer Tokens for AI Coding Agents
@@ -81,26 +81,39 @@ Session dedup means the second query never re-sends code from the first.
 
 ## Benchmarks
 
-### Token efficiency: know context vs Grep+Read
+**farfield** (764 files, 2487 functions, production TypeScript+Python monorepo)
 
-**farfield** (762 files, production TypeScript+Python):
+### Token efficiency: 3-tier vs single-context vs Grep+Read (8 scenarios)
 
-| Scenario | Grep+Read | know context | Reduction |
-|---|---|---|---|
-| WebSocket handling | 12,936 tokens | 1,714 tokens | **7.5x** |
-| Auth and API keys | 3,383 tokens | 1,623 tokens | **2.1x** |
-| Model routing | 27,556 tokens | 1,772 tokens | **15.6x** |
-| Error handling | 25,160 tokens | 1,773 tokens | **14.2x** |
-| Database + storage | 5,357 tokens | 1,773 tokens | **3.0x** |
-| **Total** | **74,392** | **8,655** | **8.6x** |
+| Scenario | Grep+Read | v0.6 context-only | v0.7 3-tier | v0.7 vs v0.6 |
+|---|---|---|---|---|
+| WebSocket handling | 106,257 | 5,976 | 3,549 | **-41%** |
+| Auth & API keys | 145,690 | 4,063 | 3,569 | **-12%** |
+| Model routing | 125,453 | 5,271 | 3,251 | **-38%** |
+| Error handling | 45,205 | 7,517 | 4,226 | **-44%** |
+| Database storage | 180,329 | 5,479 | 3,138 | **-43%** |
+| Billing | 41,789 | 5,424 | 3,295 | **-39%** |
+| LLM providers | 176,184 | 5,085 | 3,184 | **-37%** |
+| Agent execution | 175,338 | 2,250 | 2,445 | -9% |
+| **Total** | **996,245** | **41,065** | **26,657** | **-35%** |
 
-### Head-to-head agent benchmark (farfield, 762 files)
+v0.7 3-tier = `know map` → `know context --session` → `know deep`
+
+- **37.4x** fewer tokens than grep+read
+- **35%** fewer tokens than v0.6 context-only
+
+### Live head-to-head agent benchmark
+
+Two Claude Opus agents answered 3 identical questions about the farfield codebase. One used `know` CLI, the other used grep+read.
 
 | Metric | Agent with `know` | Agent with Grep+Read |
 |---|---|---|
-| Tool calls | 14 | 36 |
-| Total tokens | 105,950 | 113,471 |
-| Quality | Equivalent | Equivalent |
+| Tool calls | **28** | 40 |
+| Total tokens | **98,593** | 107,060 |
+| Duration | 215s | 206s |
+| Answer quality | Equivalent | Equivalent |
+
+**30% fewer tool calls. 8% fewer tokens. Same answer quality.**
 
 ---
 

{know_cli-0.7.0 → know_cli-0.7.2}/README.md

@@ -30,26 +30,39 @@ Session dedup means the second query never re-sends code from the first.
 
 ## Benchmarks
 
-### Token efficiency: know context vs Grep+Read
+**farfield** (764 files, 2487 functions, production TypeScript+Python monorepo)
 
-**farfield** (762 files, production TypeScript+Python):
+### Token efficiency: 3-tier vs single-context vs Grep+Read (8 scenarios)
 
-| Scenario | Grep+Read | know context | Reduction |
-|---|---|---|---|
-| WebSocket handling | 12,936 tokens | 1,714 tokens | **7.5x** |
-| Auth and API keys | 3,383 tokens | 1,623 tokens | **2.1x** |
-| Model routing | 27,556 tokens | 1,772 tokens | **15.6x** |
-| Error handling | 25,160 tokens | 1,773 tokens | **14.2x** |
-| Database + storage | 5,357 tokens | 1,773 tokens | **3.0x** |
-| **Total** | **74,392** | **8,655** | **8.6x** |
+| Scenario | Grep+Read | v0.6 context-only | v0.7 3-tier | v0.7 vs v0.6 |
+|---|---|---|---|---|
+| WebSocket handling | 106,257 | 5,976 | 3,549 | **-41%** |
+| Auth & API keys | 145,690 | 4,063 | 3,569 | **-12%** |
+| Model routing | 125,453 | 5,271 | 3,251 | **-38%** |
+| Error handling | 45,205 | 7,517 | 4,226 | **-44%** |
+| Database storage | 180,329 | 5,479 | 3,138 | **-43%** |
+| Billing | 41,789 | 5,424 | 3,295 | **-39%** |
+| LLM providers | 176,184 | 5,085 | 3,184 | **-37%** |
+| Agent execution | 175,338 | 2,250 | 2,445 | -9% |
+| **Total** | **996,245** | **41,065** | **26,657** | **-35%** |
 
-### Head-to-head agent benchmark (farfield, 762 files)
+v0.7 3-tier = `know map` → `know context --session` → `know deep`
+
+- **37.4x** fewer tokens than grep+read
+- **35%** fewer tokens than v0.6 context-only
+
+### Live head-to-head agent benchmark
+
+Two Claude Opus agents answered 3 identical questions about the farfield codebase. One used `know` CLI, the other used grep+read.
 
 | Metric | Agent with `know` | Agent with Grep+Read |
 |---|---|---|
-| Tool calls | 14 | 36 |
-| Total tokens | 105,950 | 113,471 |
-| Quality | Equivalent | Equivalent |
+| Tool calls | **28** | 40 |
+| Total tokens | **98,593** | 107,060 |
+| Duration | 215s | 206s |
+| Answer quality | Equivalent | Equivalent |
+
+**30% fewer tool calls. 8% fewer tokens. Same answer quality.**
 
 ---
 

know_cli-0.7.2/benchmark/answer_keys/q1.json

@@ -0,0 +1,49 @@
+{
+  "question_id": "q1",
+  "topic": "Billing/Subscription System",
+  "facts": [
+    {
+      "id": "f1",
+      "description": "Names the Subscription model or equivalent billing model class",
+      "keywords": ["Subscription", "subscription", "model"],
+      "weight": 2
+    },
+    {
+      "id": "f2",
+      "description": "Identifies billing plan tiers (e.g. free, pro, team, enterprise or sandbox, paid)",
+      "keywords": ["plan", "tier", "free", "pro", "team", "enterprise", "sandbox"],
+      "weight": 2
+    },
+    {
+      "id": "f3",
+      "description": "Explains how sandbox limits are enforced (rate limits, usage caps, middleware)",
+      "keywords": ["sandbox", "limit", "enforce", "rate", "cap", "usage"],
+      "weight": 2
+    },
+    {
+      "id": "f4",
+      "description": "Names specific files involved in billing (e.g. billing router, subscription service)",
+      "keywords": ["billing", "router", "service", "file"],
+      "weight": 1
+    },
+    {
+      "id": "f5",
+      "description": "Describes the payment processing flow (Stripe integration, webhooks)",
+      "keywords": ["Stripe", "payment", "webhook", "checkout"],
+      "weight": 1
+    },
+    {
+      "id": "f6",
+      "description": "Names specific functions involved in subscription management",
+      "keywords": ["create_subscription", "cancel", "update", "function"],
+      "weight": 1
+    },
+    {
+      "id": "f7",
+      "description": "Describes how plan limits map to features or quotas",
+      "keywords": ["quota", "feature", "limit", "plan"],
+      "weight": 1
+    }
+  ],
+  "max_score": 10
+}

know_cli-0.7.2/benchmark/answer_keys/q2.json

@@ -0,0 +1,49 @@
+{
+  "question_id": "q2",
+  "topic": "LLM Provider System",
+  "facts": [
+    {
+      "id": "f1",
+      "description": "Names provider_discovery module and explains its purpose",
+      "keywords": ["provider_discovery", "discover", "provider"],
+      "weight": 2
+    },
+    {
+      "id": "f2",
+      "description": "Lists supported LLM providers (OpenAI, Anthropic, Gemini, etc.)",
+      "keywords": ["OpenAI", "Anthropic", "Gemini", "provider"],
+      "weight": 2
+    },
+    {
+      "id": "f3",
+      "description": "Explains workspace-level model settings and how they're stored",
+      "keywords": ["workspace", "model", "settings", "config"],
+      "weight": 2
+    },
+    {
+      "id": "f4",
+      "description": "Describes how provider selection/routing works",
+      "keywords": ["select", "route", "routing", "choose"],
+      "weight": 1
+    },
+    {
+      "id": "f5",
+      "description": "Names specific files involved in provider configuration",
+      "keywords": ["file", "config", "provider"],
+      "weight": 1
+    },
+    {
+      "id": "f6",
+      "description": "Explains API key management for different providers",
+      "keywords": ["api_key", "key", "credential", "secret"],
+      "weight": 1
+    },
+    {
+      "id": "f7",
+      "description": "Describes model fallback or default behavior",
+      "keywords": ["fallback", "default", "model"],
+      "weight": 1
+    }
+  ],
+  "max_score": 10
+}

know_cli-0.7.2/benchmark/answer_keys/q3.json

@@ -0,0 +1,49 @@
+{
+  "question_id": "q3",
+  "topic": "Agent Execution Pipeline",
+  "facts": [
+    {
+      "id": "f1",
+      "description": "Describes the flow from user message to agent response",
+      "keywords": ["message", "flow", "pipeline", "request", "response"],
+      "weight": 2
+    },
+    {
+      "id": "f2",
+      "description": "Explains LangGraph's role in the agent execution",
+      "keywords": ["LangGraph", "langgraph", "graph", "state"],
+      "weight": 2
+    },
+    {
+      "id": "f3",
+      "description": "Describes how tools/MCP servers are integrated",
+      "keywords": ["tool", "MCP", "mcp", "server", "integrate"],
+      "weight": 2
+    },
+    {
+      "id": "f4",
+      "description": "Names specific files in the execution pipeline",
+      "keywords": ["file", "agent", "executor", "runner"],
+      "weight": 1
+    },
+    {
+      "id": "f5",
+      "description": "Describes the agent loop or turn-based execution",
+      "keywords": ["loop", "turn", "iteration", "step"],
+      "weight": 1
+    },
+    {
+      "id": "f6",
+      "description": "Explains how agent state is managed between turns",
+      "keywords": ["state", "memory", "context", "history"],
+      "weight": 1
+    },
+    {
+      "id": "f7",
+      "description": "Names specific classes or functions in the pipeline",
+      "keywords": ["class", "function", "agent", "run"],
+      "weight": 1
+    }
+  ],
+  "max_score": 10
+}