devkb 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. devkb/__init__.py +11 -0
  2. devkb/audit.py +173 -0
  3. devkb/bench/add_packs.py +52 -0
  4. devkb/bench/cli_tasks.py +105 -0
  5. devkb/bench/confirm_tasks.py +149 -0
  6. devkb/bench/module_truth.py +249 -0
  7. devkb/bench/oco_tasks.py +216 -0
  8. devkb/bench/pipeline.py +313 -0
  9. devkb/bench/process_tasks.py +135 -0
  10. devkb/bench/report.py +74 -0
  11. devkb/bench/run.py +174 -0
  12. devkb/bench/truth_check.py +148 -0
  13. devkb/bench/workflow_report.py +64 -0
  14. devkb/bench/workflow_run.py +206 -0
  15. devkb/bench/workflow_tasks.py +227 -0
  16. devkb/build.py +258 -0
  17. devkb/build_symbols.py +1394 -0
  18. devkb/call_recall.py +159 -0
  19. devkb/cli.py +53 -0
  20. devkb/coverage.py +155 -0
  21. devkb/edge_truth.py +272 -0
  22. devkb/extractors/backlog.py +113 -0
  23. devkb/extractors/component_subsystem.py +116 -0
  24. devkb/extractors/configuration.py +267 -0
  25. devkb/extractors/files_tests.py +220 -0
  26. devkb/extractors/flows.py +117 -0
  27. devkb/extractors/lifecycle.py +258 -0
  28. devkb/extractors/members.py +160 -0
  29. devkb/extractors/pull_requests.py +271 -0
  30. devkb/extractors/releases.py +49 -0
  31. devkb/extractors/source_baseline.py +66 -0
  32. devkb/extractors/spec_docs.py +220 -0
  33. devkb/extractors/symbol_tests.py +131 -0
  34. devkb/extractors/test_inventory.py +38 -0
  35. devkb/extractors/ticket_similarity.py +193 -0
  36. devkb/extractors/tickets_git.py +151 -0
  37. devkb/extractors/warnings.py +230 -0
  38. devkb/extractors/work_units.py +90 -0
  39. devkb/github.py +515 -0
  40. devkb/gitutil.py +16 -0
  41. devkb/index.py +51 -0
  42. devkb/init.py +178 -0
  43. devkb/mcp_server.py +216 -0
  44. devkb/model.py +221 -0
  45. devkb/module_file_bridge.py +57 -0
  46. devkb/ontology.md +178 -0
  47. devkb/packs.py +462 -0
  48. devkb/process_api.py +1601 -0
  49. devkb/project_context.py +191 -0
  50. devkb/query.py +251 -0
  51. devkb/service.py +324 -0
  52. devkb/startup.py +103 -0
  53. devkb/test_discovery.py +76 -0
  54. devkb/ts_symbols.py +291 -0
  55. devkb-0.2.0.dist-info/METADATA +162 -0
  56. devkb-0.2.0.dist-info/RECORD +61 -0
  57. devkb-0.2.0.dist-info/WHEEL +5 -0
  58. devkb-0.2.0.dist-info/entry_points.txt +2 -0
  59. devkb-0.2.0.dist-info/licenses/LICENSE +202 -0
  60. devkb-0.2.0.dist-info/licenses/NOTICE +11 -0
  61. devkb-0.2.0.dist-info/top_level.txt +1 -0
devkb/ts_symbols.py ADDED
@@ -0,0 +1,291 @@
1
+ """TypeScript/TSX Symbol extraction (devkb BL-3c, body/legs model).
2
+
3
+ Regex-based, mirroring discovery/extract_typescript.py's own established
4
+ approach (no TS parser in Python's stdlib, and the factory's discovery tooling already
5
+ established regex-over-source as an acceptable tradeoff for this class of
6
+ tool -- confirmed proven and shipped, not a shortcut unique to this file).
7
+ Extracts function/component/class-level Symbols -- discovery's own
8
+ extractor only goes to file (Module) level; this is the missing piece that
9
+ made the frontend invisible to devkb entirely (BL-3 was Python-only until
10
+ now, so 0 of any registered project's real TypeScript/React code -- the
11
+ actual user-facing behavior -- was in the graph at all).
12
+
13
+ Per-Symbol, also captures get/post/put(...) API-client call sites within
14
+ that symbol's own body -- porting extract_typescript.py's CALL_RE/
15
+ QUOTED_RE/DEFAULT_BASE_PARAM_RE/CONST_STR_RE patterns verbatim (same
16
+ regexes, same reasoning already proven against pms-web/src/lib/api.ts's
17
+ real 3 helper names) rather than reinventing the same regex differently.
18
+ This is the frontend half of BL-4b's cross-language CALLS_API edge --
19
+ resolution against real backend Symbols happens in build_symbols.py, which
20
+ has visibility into both languages; this module only extracts.
21
+
22
+ **Known remaining gap, confirmed live, not silently worked around**: OCO's
23
+ own `webapp/frontend/src/lib/api.ts` routes every call through a single
24
+ generic `apiFetch<T>(path, init?)` wrapper (HTTP method carried in `init`,
25
+ defaulting to GET) rather than three separately-named `get`/`post`/`put`
26
+ helpers -- `CALL_RE` (below, ported from `discovery/extract_typescript.py`)
27
+ doesn't match that shape, so `route_calls` comes back real-but-empty for
28
+ OCO even though Symbol extraction itself (including the object-literal
29
+ fix below) now correctly finds `api.qualityScore` etc. as real Symbols.
30
+ Not fixed here: it's a materially different call shape (an `init.method`
31
+ value to parse, not a function name), and `discovery/extract_typescript.py`
32
+ itself -- the already-shipped pattern this ports from -- has the exact
33
+ same gap (confirmed: its own `CALL_RE` also finds zero matches against
34
+ this file). Extending past what's already proven and shipped elsewhere in
35
+ this codebase is a real follow-up, not this pass's job.
36
+
37
+ Deliberately narrower than a real parser: only top-level `function Name(...)`,
38
+ `const Name = (...) => {...}`, `class Name`, and object-literal-method
39
+ entries (`export const pmsApi = { overview: () => get<T>("/overview") }`)
40
+ are extracted as Symbols. The object-literal case is not cosmetic --
41
+ confirmed live against both real frontends this was built for: ODSF's own
42
+ `pms-web/src/lib/api.ts` (`pmsApi = { overview: () => get<PMSOverview>
43
+ ("/overview"), ... }`) and OCO's `webapp/frontend/src/lib/api.ts`
44
+ (`api = { graphStats: () => apiFetch<T>("/graph/stats"), ... }`) BOTH
45
+ route 100% of their real API calls through this shape, not a bare
46
+ top-level `function`/arrow-const -- without object-literal-method
47
+ detection, `CALLS_API` (BL-4b) produced zero edges on either project's
48
+ actual code. A call inside a genuinely undetected symbol's body (nested
49
+ object literals beyond the outer container, computed keys, spread) is
50
+ still simply not attributed to anything, not mis-attributed to the wrong
51
+ one -- the same precision-over-recall choice BL-4 already made.
52
+ """
53
+ from __future__ import annotations
54
+
55
+ import re
56
+ from pathlib import Path
57
+
58
+ _FUNC_DECL_RE = re.compile(
59
+ r'^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*\(',
60
+ re.MULTILINE,
61
+ )
62
+ _ARROW_CONST_RE = re.compile(
63
+ r'^\s*(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*(?:async\s*)?\([^)]*\)\s*(?::[^=]+)?=>\s*\{',
64
+ re.MULTILINE,
65
+ )
66
+ _CLASS_RE = re.compile(r'^\s*(?:export\s+)?(?:default\s+)?class\s+([A-Za-z_$][\w$]*)', re.MULTILINE)
67
+ _OBJECT_LITERAL_RE = re.compile(
68
+ r'^\s*(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*\{',
69
+ re.MULTILINE,
70
+ )
71
+ _OBJECT_METHOD_RE = re.compile(
72
+ r'^\s*([A-Za-z_$][\w$]*)\s*:\s*(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*(?::[^=]+)?=>\s*',
73
+ re.MULTILINE,
74
+ )
75
+
76
+ # Ported verbatim from discovery/extract_typescript.py -- same helper-name
77
+ # convention (pms-web/src/lib/api.ts's own get/post/put), same reasoning.
78
+ CALL_RE = re.compile(r'\b(get|post|put)(?:<[^>]*>)?\(\s*[`"]([^`"]+)[`"]([^)]*)\)')
79
+ QUOTED_RE = re.compile(r'[`"]([^`"]+)[`"]')
80
+ DEFAULT_BASE_PARAM_RE = re.compile(r'base\s*=\s*([A-Za-z_$][\w$]*)')
81
+ CONST_STR_RE = re.compile(r'\bconst\s+([A-Za-z_$][\w$]*)\s*=\s*["\']([^"\']+)["\']')
82
+
83
+ _METHOD_MAP = {"get": "GET", "post": "POST", "put": "PUT"}
84
+
85
+ # ── ODSF-314: the call shapes OCO's frontend actually uses (CALLS_API was 0 there) ──────────────────────────────
86
+ # fetch(`/api/v1/jobs/${id}`, {method: "POST"}); a wrapper `apiFetch(path)` that prefixes a module constant;
87
+ # a URL builder `acknowledgeAnomalyUrl(id)` defined in one file and passed to fetch in another.
88
+ _TEMPLATE_PARAM = re.compile(r"\$\{\s*([A-Za-z_$][\w$.]*)?[^}]*\}")
89
+ _FETCH_LITERAL = re.compile(r"\bfetch\(\s*([`\"'])(.+?)\1(.{0,240})", re.S)
90
+ _FETCH_BUILDER = re.compile(r"\bfetch\(\s*([A-Za-z_$][\w$]*)\((.{0,240})", re.S)
91
+ _METHOD_OPT = re.compile(r"method\s*:\s*[`\"'](\w+)[`\"']")
92
+ _BUILDER_FN = re.compile(r"(?:export\s+)?function\s+([A-Za-z_$][\w$]*)\s*\([^)]*\)\s*(?::\s*string)?\s*\{\s*return\s+([`\"'])(.+?)\2", re.S)
93
+ _BUILDER_ARROW = re.compile(r"(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*\([^)]*\)\s*(?::\s*string)?\s*=>\s*([`\"'])(.+?)\2", re.S)
94
+ _WRAPPER_FN = re.compile(r"function\s+([A-Za-z_$][\w$]*)\s*(?:<[^>]*>)?\(\s*([A-Za-z_$][\w$]*)\s*:\s*string[^)]*\)[^{]*\{(.{0,600})", re.S)
95
+
96
+
97
+ def normalise_path(raw: str, consts: dict[str, str]) -> str | None:
98
+ """A URL as a route-shaped path: `${CONST}` becomes the constant's value, any other `${...}` a `{}` slot, the
99
+ query string and an origin are dropped, and a leading unknown base is dropped. None when it is not a path."""
100
+ def sub(m):
101
+ name = m.group(1) or ""
102
+ return consts.get(name, "{}")
103
+ path = _TEMPLATE_PARAM.sub(sub, raw.split("?")[0].strip())
104
+ path = re.sub(r"^https?://[^/]+", "", path)
105
+ while path.startswith("{}"):
106
+ path = path[2:]
107
+ path = path.rstrip("/")
108
+ return path if path.startswith("/") and len(path) > 1 else None
109
+
110
+
111
+ def route_shape(path: str) -> str:
112
+ """`/api/v1/jobs/{job_id}` and `/api/v1/jobs/{}` compare equal."""
113
+ return re.sub(r"\{[^}]*\}|<[^>]+>", "{}", path.rstrip("/"))
114
+
115
+
116
+ def collect_url_helpers(files: list[Path]) -> tuple[dict[str, str], dict[str, str]]:
117
+ """Repository-wide (builders, wrappers): a function returning a URL template, by name -> its path; a function
118
+ whose first string parameter is fetched behind a module constant, by name -> that prefix."""
119
+ builders: dict[str, str] = {}
120
+ wrappers: dict[str, str] = {}
121
+ for path in files:
122
+ try:
123
+ text = path.read_text(errors="replace")
124
+ except OSError:
125
+ continue
126
+ consts = dict(CONST_STR_RE.findall(text))
127
+ for rx in (_BUILDER_FN, _BUILDER_ARROW):
128
+ for name, _q, url in rx.findall(text):
129
+ norm = normalise_path(url, consts)
130
+ if norm:
131
+ builders.setdefault(name, norm)
132
+ for name, param, body in _WRAPPER_FN.findall(text):
133
+ m = re.search(r"fetch\(\s*`\$\{\s*([A-Za-z_$][\w$]*)\s*\}\$\{\s*" + re.escape(param) + r"\s*\}`", body)
134
+ if m and m.group(1) in consts:
135
+ wrappers.setdefault(name, consts[m.group(1)].rstrip("/"))
136
+ return builders, wrappers
137
+
138
+
139
+ def _method(tail: str, default: str = "GET") -> str:
140
+ m = _METHOD_OPT.search(tail.split(");")[0][:240]) # up to the end of this call, past any nested call's ")"
141
+ return m.group(1).upper() if m else default
142
+
143
+
144
+ def _matching_brace_end(text: str, open_brace_pos: int) -> int:
145
+ """Index just past the closing brace matching the `{` at open_brace_pos,
146
+ via depth counting -- not string/comment-aware (a `{` inside a string
147
+ literal or comment can throw this off), the same class of imprecision
148
+ discovery/extract_typescript.py's own regex approach already accepts.
149
+ Unbalanced input (a parse this heuristic can't follow) falls back to
150
+ "rest of file" rather than raising."""
151
+ depth = 0
152
+ for i in range(open_brace_pos, len(text)):
153
+ if text[i] == "{":
154
+ depth += 1
155
+ elif text[i] == "}":
156
+ depth -= 1
157
+ if depth == 0:
158
+ return i + 1
159
+ return len(text)
160
+
161
+
162
+ def _expr_body_end(text: str, start: int, container_end: int) -> int:
163
+ """End of a single-expression arrow body (no `{...}` block) -- the
164
+ first top-level `,` before the enclosing object literal's own closing
165
+ brace, tracking paren/bracket/brace depth so a call's own commas
166
+ (`get<T>(a, b)`) don't end the body early. Not string/template-literal
167
+ aware, same class of imprecision `_matching_brace_end` already
168
+ accepts."""
169
+ depth = 0
170
+ i = start
171
+ while i < container_end:
172
+ c = text[i]
173
+ if c in "([{":
174
+ depth += 1
175
+ elif c in ")]}":
176
+ if depth == 0:
177
+ return i
178
+ depth -= 1
179
+ elif c == "," and depth == 0:
180
+ return i
181
+ i += 1
182
+ return container_end
183
+
184
+
185
+ def _find_symbols(source: str) -> list[tuple[str, str, int, int, int]]:
186
+ """[(name, kind, line_start, body_start, body_end), ...] -- body_start/
187
+ end bound the text a call-scan should search within for THIS symbol
188
+ only, not the whole file (the same function-body scoping BL-4 already
189
+ established for precision over recall)."""
190
+ out: list[tuple[str, str, int, int, int]] = []
191
+ for pat, kind in ((_FUNC_DECL_RE, "function"), (_ARROW_CONST_RE, "function"), (_CLASS_RE, "class")):
192
+ for m in pat.finditer(source):
193
+ name = m.group(1)
194
+ open_brace = source.find("{", m.end() - 1)
195
+ if open_brace == -1:
196
+ continue
197
+ body_end = _matching_brace_end(source, open_brace)
198
+ line_start = source.count("\n", 0, m.start()) + 1
199
+ out.append((name, kind, line_start, m.end(), body_end))
200
+
201
+ # Object-literal methods (`export const pmsApi = { overview: () =>
202
+ # get<T>("/overview"), ... }`) -- the real, dominant shape both real
203
+ # frontends this was built for actually use (see module docstring).
204
+ # Qualified by the outer container's own name, e.g. "pmsApi.overview" --
205
+ # entries in a container nested deeper than one level flatten onto the
206
+ # outermost container's name, an accepted approximation, not a full
207
+ # recursive object-literal parser.
208
+ for lit_m in _OBJECT_LITERAL_RE.finditer(source):
209
+ container_name = lit_m.group(1)
210
+ open_brace = source.find("{", lit_m.end() - 1)
211
+ if open_brace == -1:
212
+ continue
213
+ container_end = _matching_brace_end(source, open_brace)
214
+ for em in _OBJECT_METHOD_RE.finditer(source, open_brace, container_end):
215
+ entry_name = em.group(1)
216
+ line_start = source.count("\n", 0, em.start()) + 1
217
+ body_start = em.end()
218
+ if body_start < len(source) and source[body_start] == "{":
219
+ body_end = _matching_brace_end(source, body_start)
220
+ else:
221
+ body_end = _expr_body_end(source, body_start, container_end)
222
+ out.append((f"{container_name}.{entry_name}", "function", line_start, body_start, body_end))
223
+ return out
224
+
225
+
226
+ def extract_file_calls(body: str, consts: dict[str, str], builders: dict[str, str], wrappers: dict[str, str]) -> list[tuple[str, str]]:
227
+ """(method, normalised path) for each API call in a symbol's body (ODSF-314 shapes)."""
228
+ out: list[tuple[str, str]] = []
229
+ for _q, url, tail in _FETCH_LITERAL.findall(body):
230
+ norm = normalise_path(url, consts)
231
+ if norm:
232
+ out.append((_method(tail), norm))
233
+ for name, tail in _FETCH_BUILDER.findall(body):
234
+ if name in builders:
235
+ out.append((_method(tail), builders[name]))
236
+ for name, prefix in wrappers.items():
237
+ for m in re.finditer(r"\b" + re.escape(name) + r"(?:<[^>]*>)?\(\s*([`\"'])(.+?)\1(.{0,240})", body, re.S):
238
+ norm = normalise_path(m.group(2), consts)
239
+ if norm:
240
+ out.append((_method(m.group(3)), prefix + norm))
241
+ return out
242
+
243
+
244
+ def extract_file(path: Path, repo_root: Path, helpers: tuple[dict[str, str], dict[str, str]] | None = None,
245
+ ) -> tuple[list[dict], list[tuple[str, str, str]]]:
246
+ """Returns (symbols, route_calls) for one .ts/.tsx file.
247
+ symbols: [{qualified_name (bare name, no nesting -- top-level only),
248
+ kind, line_start}, ...]
249
+ route_calls: [(symbol_qualified_name, method, path), ...] -- the
250
+ frontend half of BL-4b; build_symbols.py resolves these against real
251
+ backend Symbol routes, this function has no visibility into those."""
252
+ try:
253
+ source = path.read_text(errors="replace")
254
+ except OSError:
255
+ return [], []
256
+
257
+ consts = dict(CONST_STR_RE.findall(source))
258
+ default_base_match = DEFAULT_BASE_PARAM_RE.search(source)
259
+ default_base = consts.get(default_base_match.group(1), "") if default_base_match else ""
260
+
261
+ symbols: list[dict] = []
262
+ route_calls: list[tuple[str, str, str]] = []
263
+ for name, kind, line_start, body_start, body_end in _find_symbols(source):
264
+ symbols.append({"qualified_name": name, "kind": kind, "line_start": line_start})
265
+
266
+ body = source[body_start:body_end]
267
+ for m in CALL_RE.finditer(body):
268
+ helper, call_path, rest = m.group(1), m.group(2), m.group(3)
269
+ if call_path.startswith("$") or "{" in call_path:
270
+ # ODSF-314: a template path is still a route, with its interpolations as parameter slots
271
+ norm = normalise_path(call_path, consts)
272
+ if norm:
273
+ route_calls.append((name, _METHOD_MAP[helper], norm))
274
+ continue
275
+ trailing_quoted = QUOTED_RE.findall(rest)
276
+ explicit_base = trailing_quoted[-1] if trailing_quoted else None
277
+ base = explicit_base if explicit_base is not None else default_base
278
+ route_calls.append((name, _METHOD_MAP[helper], f"{base}{call_path}"))
279
+ builders, wrappers = helpers or ({}, {})
280
+ for method, call_path in extract_file_calls(body, consts, builders, wrappers):
281
+ route_calls.append((name, method, call_path))
282
+ return symbols, route_calls
283
+
284
+
285
+ def list_ts_files(repo_root: Path) -> list[Path]:
286
+ return sorted(
287
+ p for p in repo_root.rglob("*")
288
+ if p.suffix in (".ts", ".tsx")
289
+ and "node_modules" not in p.parts and ".next" not in p.parts and p.name.endswith((".ts", ".tsx"))
290
+ and not p.name.endswith(".d.ts")
291
+ )
@@ -0,0 +1,162 @@
1
+ Metadata-Version: 2.4
2
+ Name: devkb
3
+ Version: 0.2.0
4
+ Summary: A software-process knowledge graph for software development agents: extraction, pre-computed context packs, and an MCP server
5
+ Author: Hung T. Le
6
+ License-Expression: Apache-2.0
7
+ Project-URL: Repository, https://github.com/namiq-ai/devkb
8
+ Project-URL: Issues, https://github.com/namiq-ai/devkb/issues
9
+ Project-URL: Benchmark, https://github.com/namiq-ai/devkb/blob/main/docs/BENCHMARK.md
10
+ Keywords: knowledge graph,software development agents,coding agents,mcp,code intelligence,call graph,software process
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Environment :: Console
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3 :: Only
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Topic :: Software Development
21
+ Classifier: Topic :: Software Development :: Quality Assurance
22
+ Requires-Python: >=3.10
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ License-File: NOTICE
26
+ Requires-Dist: pyyaml>=6
27
+ Provides-Extra: mcp
28
+ Requires-Dist: mcp<2,>=1.23; extra == "mcp"
29
+ Provides-Extra: study
30
+ Requires-Dist: scipy>=1.10; extra == "study"
31
+ Provides-Extra: dev
32
+ Requires-Dist: pytest>=8; extra == "dev"
33
+ Requires-Dist: mcp<2,>=1.23; extra == "dev"
34
+ Requires-Dist: scipy>=1.10; extra == "dev"
35
+ Dynamic: license-file
36
+
37
+ # devkb
38
+
39
+ [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.24267143.svg)](https://doi.org/10.5281/zenodo.24267143)
40
+
41
+ **A knowledge graph of your repository for software development agents.** Agents answer "what calls this, what breaks, which tests"
42
+ in one step instead of searching file by file: 55% cheaper, with better answers, in our benchmark.
43
+
44
+ <picture>
45
+ <source media="(prefers-color-scheme: dark)" srcset="docs/img/benchmark-dark.svg">
46
+ <img alt="Median cost per task: plain search $0.070 (quality 0.931); devkb 12 tools $0.059, 18% cheaper (0.955); devkb 7 tools $0.040, 38% cheaper (0.963); devkb pack $0.025, 55% cheaper (0.981)" src="docs/img/benchmark-light.svg">
47
+ </picture>
48
+
49
+ ## 1. What devkb is
50
+
51
+ - **A graph** built from your source and git history: functions, calls, tests, routes, errors, configuration,
52
+ commits, pull requests, tickets ([ontology](devkb/ontology.md)).
53
+ - **Packs**: one command answers a whole question (who calls this, what breaks, which tests to run), each item with
54
+ the source line that proves it, and a statement of what the graph could not see.
55
+ - **An MCP server** giving agents the same answers as tools, for Claude Code, Codex and any MCP client.
56
+
57
+ Everything runs locally: devkb reads files and runs `git`, never your code (unless `devkb.json` opts in), and the graph never leaves your machine.
58
+
59
+ ### Languages
60
+
61
+ | Language | Status | What devkb understands |
62
+ |---|---|---|
63
+ | Python | ✅ Supported | functions, classes, calls (through imports, re-exports, typed objects, base classes), tests, FastAPI/Flask routes, raised and logged errors, environment variables; every pack |
64
+ | TypeScript, TSX | 🟡 Partial | functions, components, classes, and the HTTP calls they make to backend routes; not calls between them |
65
+ | JavaScript (`.js`, `.mjs`) | 🟡 Partial | as TypeScript |
66
+ | Odoo XML | 🟡 Partial | templates and menus |
67
+ | Bash / shell | ⬜ Not yet | files and history only |
68
+ | C, C++, Java, Rust, Go, C#, others | ⬜ Not yet | files and history only |
69
+
70
+ "Files and history" is the language-independent layer every repository gets: files, commits, pull requests and
71
+ tickets.
72
+
73
+ ## 2. How much it saves
74
+
75
+ Latest benchmark: the 7 open-source repositories in [`bench/repos.yaml`](bench/repos.yaml), 57 tasks, 1,138 agent
76
+ runs, the same model (Sonnet) in every arm, answers scored against truth computed from the source. Cost, turns and
77
+ tokens are the median run; saving is per task against plain search, averaged over tasks; quality is the mean score:
78
+
79
+ | | Plain search | devkb, 12 tools | devkb, 7 tools | devkb pack |
80
+ |---|---|---|---|---|
81
+ | **Cost per task** | $0.070 | $0.059 | $0.040 | **$0.025** |
82
+ | **Saving** | — | 18% | 38% | **55%** |
83
+ | **Quality** (0–1) | 0.931 | 0.955 (+0.024) | 0.963 (+0.032) | **0.981 (+0.050)** |
84
+ | Turns | 4 | 6 | 5 | **3** |
85
+ | Context processed (tokens) | 126k | 169k | 147k | **75k** |
86
+ | of which cache reads | 123k | 163k | 141k | 74k |
87
+ | of which new input and cache writes | 8.3k | 4.1k | 2.0k | 1.3k |
88
+ | Output tokens | 1.4k | 1.8k | 1.3k | 0.9k |
89
+
90
+ Saving and quality gain by repository (95% intervals in the results):
91
+
92
+ | Repository | Tasks | 7 tools: saving / quality | pack: saving / quality |
93
+ |---|---|---|---|
94
+ | lnbits | 10 | 53% / +0.032 | **66%** / +0.049 |
95
+ | Netflix Dispatch | 8 | 45% / +0.040 | **61%** / +0.081 |
96
+ | Prefect | 9 | 41% / −0.017 | **59%** / +0.047 |
97
+ | lattice-scan | 12 | 36% / +0.052 | **51%** / +0.058 |
98
+ | Mealie | 6 | 18% / +0.095 | **42%** / +0.062 |
99
+ | devkb | 4 | 1% / +0.004 | **40%** / +0.004 |
100
+ | click | 8 | 6% / +0.016 | 15% / +0.023 |
101
+
102
+ The saving is in call chains (66–77% on tasks that trace an error or a change to the route handlers that reach it);
103
+ on one-hop questions, as in click, plain search is already good. An earlier pre-registered study (30 held-out tasks,
104
+ 1,020 runs, two model sizes) found packs 41% cheaper and the lean tools 35% ([`study/`](study/); `make verify`
105
+ recomputes it). Details and corrections: [`bench/results/2026-11-15-registry`](bench/results/2026-11-15-registry/);
106
+ add a repository: [`docs/BENCHMARK.md`](docs/BENCHMARK.md).
107
+
108
+ ## 3. Set up
109
+
110
+ ```bash
111
+ pip install "devkb[mcp]"
112
+ cd your-repo
113
+ devkb init --hooks
114
+ ```
115
+
116
+ This builds the graph into `.devkb/`, adds a short devkb section to `AGENTS.md` and `CLAUDE.md`, registers the MCP
117
+ server in `.mcp.json`, and rebuilds the graph after each commit. Your own content in those files is kept;
118
+ `devkb init --remove` undoes it.
119
+
120
+ Ask it directly:
121
+
122
+ ```bash
123
+ devkb pack --project . refactor my_function # who calls it, which tests
124
+ devkb pack --project . error "message text" # which route handlers reach it
125
+ devkb pack --project . file path/to/file.py # before editing a file
126
+ ```
127
+
128
+ ### Your agent
129
+
130
+ **Claude Code**: nothing more to do. `devkb init` registered the server in `.mcp.json` and pointed `CLAUDE.md` at the
131
+ instructions. Start `claude` in the repository, approve the `devkb` server when asked, and check it with `/mcp`.
132
+
133
+ **Cursor**: add `.cursor/mcp.json` to the repository, then enable `devkb` under Settings → MCP:
134
+
135
+ ```json
136
+ {"mcpServers": {"devkb": {"command": "devkb", "args": ["mcp", "--project", ".", "--toolset", "lean-pack"]}}}
137
+ ```
138
+
139
+ **Codex**: add to `~/.codex/config.toml`:
140
+
141
+ ```toml
142
+ [mcp_servers.devkb]
143
+ command = "devkb"
144
+ args = ["mcp", "--project", ".", "--toolset", "lean-pack"]
145
+ ```
146
+
147
+ Codex and Cursor read the instructions in `AGENTS.md`; Claude Code reads them through `CLAUDE.md`.
148
+
149
+ What agents get by default (`--toolset lean-pack`): a `pack` tool that returns a whole answer in one call, and the
150
+ seven single-question tools. The instructions tell them to ask for a pack when a question follows a chain (a file
151
+ before editing, a change, an error) and to search as usual for a one-hop lookup, which is where the benchmark found
152
+ the saving and where it did not. Measured with agents asking for the pack themselves (lnbits and Dispatch, 400 runs):
153
+ 53% cheaper than plain search with the highest quality of any arm, against 42% for the seven tools alone
154
+ ([`bench/results/2026-11-15-lean-pack`](bench/results/2026-11-15-lean-pack/)).
155
+
156
+ ## 4. Licence and citation
157
+
158
+ Code: [Apache-2.0](LICENSE). The study in [`study/`](study/) (paper, figures, pre-registration, data):
159
+ [CC BY 4.0](study/LICENSE). Benchmark results quote third-party code under its own licences
160
+ ([`bench/results/NOTICE`](bench/results/NOTICE)). Releases: [`docs/RELEASING.md`](docs/RELEASING.md).
161
+
162
+ > Hung T. Le. *Precomputed Context, Not More Tools: A Pre-Registered Study of Process Graphs for Coding Agents.* 2026.
@@ -0,0 +1,61 @@
1
+ devkb/__init__.py,sha256=O5q8anVDql91x_pmNPGcWc7wE_P7rkVHji9Vx3pbaHI,616
2
+ devkb/audit.py,sha256=A-158J2t9lVg-fuaOw7GscWROkYmQnkaIRO9hr6ohs8,8765
3
+ devkb/build.py,sha256=xmpZ-GG0g8jcIUEO25zqUfdxJ9bqvpd4inThX7GLEok,12747
4
+ devkb/build_symbols.py,sha256=zyPPvsLZ-nwpIfUlEi1DlKffdGt66ZSlwnTKOH_vZts,72782
5
+ devkb/call_recall.py,sha256=H8rTJ_O-0Pl_NqOelkpm6jKK-wwA_vT-8dV5ZytmR3c,6873
6
+ devkb/cli.py,sha256=LN_vxCtzroKggw1YWHMVN5tv0-TJsTGSA4TEao_3UX4,1941
7
+ devkb/coverage.py,sha256=sCLre1le2qceZegPDejQZIw9jK0Kx9dAh119NpkBVZ4,7032
8
+ devkb/edge_truth.py,sha256=ouT8z1O0Ijdpq1TLIhKHnfvs0-4NJCG3NiUzQv2LC9k,12714
9
+ devkb/github.py,sha256=BrrdwrwXfS0qfNrKrJWjj-lliainZyW2dv89ZQIXG00,25792
10
+ devkb/gitutil.py,sha256=FJiAhggpE_tThsUZkDXuHsyAIMyBM3dikWLuF5sZT5k,616
11
+ devkb/index.py,sha256=x-l2SyfHPdh69vvuA9cq_n4aN7HqsLuZBUNZ6Rp8VnM,1924
12
+ devkb/init.py,sha256=ZknV1tG6UOw56Cfh1SusK11gwxofVxCr9lzARhW8YH0,8462
13
+ devkb/mcp_server.py,sha256=nmwKDrKMDNEwRfjoJnEZOS8-tmetWRuBLXQ-ydX6JBA,11247
14
+ devkb/model.py,sha256=bX8RDdazil6OtMTnQ84KXiGtneuLNXXBS7-Ej-Wi57A,10197
15
+ devkb/module_file_bridge.py,sha256=TGeEH5gFT1_pdc4Em_ELE--KSh1ErZJfxE0g1OGvxvs,2546
16
+ devkb/ontology.md,sha256=WLZP3VEcMv5Fhaw8gGMMD2v5HK4PdnbI6agaoF08GZA,18592
17
+ devkb/packs.py,sha256=vOMLOC21gIozvGFIreS1_Rfop1hfl0QEkHflU4u7MGU,28462
18
+ devkb/process_api.py,sha256=M08SgOoi9_hEey7ZmhhaCLbJsTTKzRPgUad8ztnsHuw,96970
19
+ devkb/project_context.py,sha256=Sw8dwK1R-Pm9wObNDdmCOCkhuJ0ZWk5QrD5uHsd152w,9489
20
+ devkb/query.py,sha256=sMVlPmKtkm3bgYOu8sVzHI54zf-4mytlNWNr2HQ8ihs,10885
21
+ devkb/service.py,sha256=QmBz8YjESSdkGiZK-OXJCQqBmPcPQvI08XqoGM6hkSE,15342
22
+ devkb/startup.py,sha256=dAAra5q3tZcxyqDTebEM0wT3efenakFtGXEys_wlOrA,4776
23
+ devkb/test_discovery.py,sha256=65l5jGbVhPP5S96b0--CF6z3Nla7KHz1WO1y5sBFJAA,3116
24
+ devkb/ts_symbols.py,sha256=U2J5tT93c2nFIkJ2a76wPY_S0jpS-wShFROxX3p7QuM,14805
25
+ devkb/bench/add_packs.py,sha256=f2siiU1dS5aOdn0bveZI_qJy_o-FUCIlCxnV8DMyLIc,1968
26
+ devkb/bench/cli_tasks.py,sha256=lVDv9ZR8gvU7Z0AneQqLJNyGTILFNNh_lQZSOzy5CAo,4902
27
+ devkb/bench/confirm_tasks.py,sha256=ZCQQS1lSzIFgPJNX6bleFmAwkrNymMNJJVQHLkob1Es,7729
28
+ devkb/bench/module_truth.py,sha256=7wCP5wPFpjHDfXWPxltHeiphzM7clugtxzWWI3o0EM0,11765
29
+ devkb/bench/oco_tasks.py,sha256=1Cyb84gKH6hoD-qOv9UE8Mgwyuz1AyyxngJGVJFcbKs,12463
30
+ devkb/bench/pipeline.py,sha256=0CHioo69cXwpXmpGMGZWK49wHHF1qBDLmC8VuIomefg,16314
31
+ devkb/bench/process_tasks.py,sha256=IGIEmBbIq0_kwZ3eWtTa-0YcTPWFg02NldFODo5geqM,6584
32
+ devkb/bench/report.py,sha256=Zp1H_8miBZlqna_t4RHBWQpgclTg3w1hQfpHJlpio0Y,3111
33
+ devkb/bench/run.py,sha256=RTHewqWFPoTQO3SJBE1W5pnadmJ4lnr0vw9pEa9VXLk,8757
34
+ devkb/bench/truth_check.py,sha256=j_9f-Q5vxL81jSSStoJhvOPYyESkDP0UMJfMsUOUvmI,7230
35
+ devkb/bench/workflow_report.py,sha256=XupmfGFYqIoVFN0xUXVkR-bK6S05q2gxqKq07s7w7Ew,2851
36
+ devkb/bench/workflow_run.py,sha256=9T5qivW_dTlTFpI3X6c7fhGF6OBtNz7D-_ryGl7lWWM,12162
37
+ devkb/bench/workflow_tasks.py,sha256=dA_SfEti3KaBtF5Dqo3MTki64jB1rkdEY2PkduLTRpU,11456
38
+ devkb/extractors/backlog.py,sha256=eqPAMNfCN7Pqj_PSuSs4KsCMcYQWMX6oU2jD00gIJ2w,4255
39
+ devkb/extractors/component_subsystem.py,sha256=kbv_akJKYehiDKmFaDJh0GRwOz43R1dmwAViPnRfj0s,4950
40
+ devkb/extractors/configuration.py,sha256=DaOJxKcLFmgXJLEVE3fiNCNk9zS-bwH2AzagH5pO3YI,12907
41
+ devkb/extractors/files_tests.py,sha256=POAbsWBLM1mPeLlsGtz2XYx4FNzt6mJI6LksgqmHRDI,11026
42
+ devkb/extractors/flows.py,sha256=x2D3nJ1bCScKgYK9Vb6i5280_0IE8xnVbho7ApdGTvM,5141
43
+ devkb/extractors/lifecycle.py,sha256=DduwMKSHd4Po5RbRgupFo2GfFGgf8bkynpvCwkltgN4,11833
44
+ devkb/extractors/members.py,sha256=sVI5B5YyyzMxWqBAyb422rzWkUhYpj_iXXQQoD1wzKw,7636
45
+ devkb/extractors/pull_requests.py,sha256=hSPuIpMx4E-r8tdlAQpjRqGkxVAQx3GbZk8jcMhZP3A,14513
46
+ devkb/extractors/releases.py,sha256=_snlSqMxxkvsauP39gtmpUCelqckYwjMAzanIVzWEv0,1900
47
+ devkb/extractors/source_baseline.py,sha256=0IgULo8kbDtD0_2EWOfiBP10jxYP6JxN_RNPSZUIgao,2965
48
+ devkb/extractors/spec_docs.py,sha256=Lzzi3VOTXeEVxNIyH7uf8pmAXpR2iV3uuf5yngxuZ_w,10331
49
+ devkb/extractors/symbol_tests.py,sha256=HgmH0ghWsx5mGqJ4axc4INWEOYkjh88-1AXMHJ1FIcU,6577
50
+ devkb/extractors/test_inventory.py,sha256=OIJ02X0XBByuR30PZl4hU77RWDvxh1EGN-w-40zH2tQ,1597
51
+ devkb/extractors/ticket_similarity.py,sha256=WpYIaSlLFhfJ1Z8_QNeEIw-mJEXtu2rcAjwqO22fciA,9924
52
+ devkb/extractors/tickets_git.py,sha256=JRflFngL_w8GlZ-KarFf3QK2JB3pEGsU_GiQPCcP-Bo,6244
53
+ devkb/extractors/warnings.py,sha256=sfR53S4_s2fVKSkpsRGy9O5VVHnhUYLXpm1tG_ZXSkQ,10557
54
+ devkb/extractors/work_units.py,sha256=6fAcAHPI-FVPHJxnJgtkGtSu8bk8qSWJMN6wmaDHPDM,3984
55
+ devkb-0.2.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
56
+ devkb-0.2.0.dist-info/licenses/NOTICE,sha256=C0Tp2eLG0fnkr1YD2DiZWPhQGq6K9G-oUmqiiAo6qTM,532
57
+ devkb-0.2.0.dist-info/METADATA,sha256=l4rhZiVx5yxduZg29eBRgQR7-S0uHeo1-21XxjELGTY,8023
58
+ devkb-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
59
+ devkb-0.2.0.dist-info/entry_points.txt,sha256=dMyM4r2uYlB7SeL3keNXA2pWtRrwmRSLBEBHiJ4qbtg,41
60
+ devkb-0.2.0.dist-info/top_level.txt,sha256=vM5y5cuKDRtyO6ZKtD-BzBzoJzMzuE8DhRGYsbWRSnQ,6
61
+ devkb-0.2.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ devkb = devkb.cli:main