@nanonets/graft 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Context Graph Engine contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,228 @@
+<div align="center">
+
+<!-- placeholder: swap for the Graft logo asset when ready -->
+<!-- <img src="assets/graft.png" alt="Graft" width="220"/> -->
+
+# Graft
+
+**Your coding agent reads 30 files to change 3.**
+**Graft gives it the map it should have read first.**
+
+<p>
+  <a href="https://www.npmjs.com/package/@nanonets/graft"><img src="https://img.shields.io/npm/v/%40nanonets%2Fgraft?style=for-the-badge&logo=npm&logoColor=white&label=npm" /></a>
+  <a href="https://www.npmjs.com/package/@nanonets/graft"><img src="https://img.shields.io/npm/dm/%40nanonets%2Fgraft?style=for-the-badge&logo=npm&logoColor=white&label=downloads" /></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/%40nanonets%2Fgraft?style=for-the-badge&logo=nodedotjs&logoColor=white" /></a>
+  <img src="https://img.shields.io/badge/TypeScript-strict-3178C6?style=for-the-badge&logo=typescript&logoColor=white" />
+  <img src="https://img.shields.io/badge/License-MIT-20C997?style=for-the-badge" />
+  <img src="https://img.shields.io/badge/runs-100%25%20local-546FFF?style=for-the-badge&logo=ollama&logoColor=white" />
+</p>
+
+<!-- placeholder: numbers pending a committed benchmark run, see Benchmark below -->
+**31% fewer tool calls · 23% less cost · 17% lower latency.** That is what an agent gets from reading the graph first instead of going in cold.
+
+</div>
+
+<!-- placeholder: swap this diagram for a produced hero gif/screenshot (assets/hero.gif) when ready -->
+
+```mermaid
+flowchart LR
+    A["Your code"] -->|"graft init"| B[".context/<br/>a graph of linked<br/>markdown nodes"]
+    B -->|"git commit"| C[("your repo")]
+    C -->|"git clone"| D["teammate + their agent"]
+    D -->|"reads the graph first"| E["starts already knowing<br/>how the repo fits together"]
+```
+
+---
+
+## Quick start
+
+```bash
+npx @nanonets/graft init
+# builds .context/ from your code, one node per system, API, or concept
+
+git add .context && git commit -m "add context graph"
+# commit it so everyone who clones the repo (and their agents) gets the graph
+```
+
+Or install it once and get the `graft` command everywhere:
+
+```bash
+npm install -g @nanonets/graft
+graft init
+```
+
+That is it. Point your agent at `.context/` and it reads the graph before it starts working.
+
+---
+
+## The problem
+
+Every task, your coding agent starts blind. Before it changes anything, it re-explores the repo: grep a term, open a file, follow an import, back out, try again. It is rebuilding a picture of a codebase it mapped an hour ago and threw away. That rediscovery burns most of a run's tool calls, tokens, and latency, and it is pure overhead:
+
+- **Repeated.** Every task pays the exploration cost again, from zero.
+- **Discarded.** Whatever the agent figured out dies with the session.
+- **Unshared.** The next teammate, and their agent, start from scratch too.
+
+Humans onboard to a codebase once. Agents onboard every single time.
+
+---
+
+## What Graft does
+
+Graft builds that understanding **once** and writes it into your repo as a folder of linked markdown files, one node per system, API, or concept.
+
+- **Real explanations, not a list of symbols.** Each node says, in plain English, what a part of the system does and how it connects to the rest, the way a senior engineer would explain it. That is the part an agent actually needs so it can skip the exploration. It is not a dump of function names.
+- **A real graph you can read.** No embeddings, no similarity search, no index to keep warm. The graph is a set of linked files your agent opens, greps, and follows, exactly the way it reads any other file in the repo.
+- **Grafted into git.** The graph is just files in `.context/`. Commit it, and anyone who clones the repo has it. No database, no server, no setup. Git does the syncing, and a stale graph shows up as a diff in review instead of rotting in some external store.
+- **The diff lives with the code.** When a change moves things around, you see it in the graph diff in the same pull request, right next to the code that caused it.
+- **Local by default.** The graph builds with a local model, so your code stays on your machine. Cloud models are opt-in for richer summaries.
+
+---
+
+## How the graph gets built
+
+Graft builds the graph in two passes, both powered by a language model:
+
+1. **Read each file.** Every source file is summarized once into a short description of what it does.
+2. **Group into nodes.** Those summaries are grouped into a curated set of nodes (subsystems, key files, and concepts) with typed links between them. Graft chooses the right level of detail for you instead of making one node per file, so a big repo becomes a few dozen readable nodes.
+
+Both passes are cached by content hash. Re-running only touches the files that changed, so the second build is fast and cheap.
+
+---
+
+## What's in a node
+
+A node is a single markdown file. Most code maps stop at an address: this thing lives in that file, on that line. That tells an agent where to look, not what it will find, so it still has to open the source and read. A Graft node holds the meaning inline, so the agent learns what it needs up front and opens the file only when it wants more.
+
+Each node holds:
+
+| Part | What it holds |
+|---|---|
+| **Summary** | A plain-English explanation of what the code does, written by the model and cached. It is there whether or not the code was ever documented, and it is regenerated when the source changes. |
+| **Crux** | The handful of lines that actually carry the logic: the guard, the skip condition, the state change. Lifted straight from the source and stored inline, so the agent sees *how* it works, not just what. |
+| **Sources** | The exact files the node is built from, each tracked by a content hash, so Graft can tell precisely when a node has gone stale. |
+| **Links** | Typed connections to other nodes (`depends_on`, `part_of`, `uses`, `implements`, `produces`), written as `[[wikilinks]]` your agent can follow. |
+| **Notes** | Anything you write below the generated block. It is preserved across regenerations, so your own context is never overwritten. |
+
+That is three depths in one file: the summary says *what* the code does, the crux shows *how*, and the sources point to the rest if the agent needs it. A plain index makes it read a whole file to learn one thing. A Graft node hands it the answer inline, and the follow-up read often never happens.
+
+The crux is stored as the code itself, not as a line range, on purpose. Line numbers drift whenever unrelated code above them shifts, but the lines that matter do not. Keeping the text, not the numbers, means the crux stays correct even as the file around it moves.
+
+_Summary, sources, links, and notes ship today. The inline crux excerpt is rolling out as the node schema lands._
+
+---
+
+## Keeping it honest (CI)
+
+A graph that has drifted from the code is worse than no graph. `graft check` compares each node's tracked source hashes against the current files and fails if the graph is stale. Drop it in CI so a pull request cannot merge with an out-of-date map.
+
+```bash
+graft check          # exits non-zero if .context/ has drifted
+graft check --json   # machine-readable drift report
+```
+
+<!-- placeholder: planned, not yet in the CLI -->
+> **Planned: auto-sync on commit.** `graft hook install` will add a post-commit hook that regenerates changed nodes automatically, so the graph stays current without anyone remembering to run `init`. Until then, regenerate with `graft init` and commit it alongside your code.
+
+---
+
+## Runs locally
+
+Everything runs on your machine. No accounts, no cloud calls, no keys required.
+
+- **Default.** A local model via [Ollama](https://ollama.com) builds the graph. Nothing leaves your machine.
+- **Optional.** Set `OPENROUTER_API_KEY` to use a cloud model for richer summaries. Pass `--local` to force local even when a key is set.
+- **No telemetry** and no analytics.
+
+See [`.env.example`](.env.example) for the full list of settings (model names, base URLs).
+
+---
+
+## CLI
+
+```bash
+graft init [dir]                     # build .context/ from the code at [dir] (default: .)
+graft init --extensions .ts .py      # only include these code extensions
+graft init --local                   # force local Ollama even if OPENROUTER_API_KEY is set
+
+graft check [dir]                    # fail (exit 1) if .context/ has drifted from the code
+graft check --json                   # print the drift report as JSON
+
+graft viz [dir]                      # see the graph: serves an interactive viewer on localhost
+graft viz --port 5000 --no-open      # pick a port; don't auto-open the browser
+
+# global
+graft --dir <path>                   # use a context dir other than <repo>/.context
+```
+
+## Visualize it (`graft viz`)
+
+`graft viz` opens a local, interactive view of both graphs — no install, no dev
+server; the viewer ships prebuilt inside the package.
+
+- **Context** tab — the architecture graph from `.context/*.md`. Nodes colored by
+  type, sized by connectedness.
+- **Code** tab — the per-symbol graph from `graph.json` (run `graft graph` first).
+- **Outline** tab — the file → class → method hierarchy as a collapsible tree.
+
+Edges speak the code's language. Every link is one of a closed set of verbs, each
+answering a question someone building or reviewing code actually asks:
+
+| Verb | The question it answers |
+|---|---|
+| `part_of` / `contains` | where does this live? |
+| `uses` / `calls` / `imports` / `depends_on` | what breaks if I change this? |
+| `produces` | where does this output come from? |
+| `configures` | what changes its behavior without a code change? |
+| `validates` | what checks or judges this? (tests, drift checks, scoring) |
+| `extends` / `implements` | what contract must this honor? |
+
+Select a node and its edges take on direction: **amber = what it depends on,
+teal = what depends on it**, with the verb written on each highlighted edge.
+Chips above the canvas filter by verb; tree-sitter-extracted edges draw solid
+while LLM-inferred ones draw dashed. The viewer live-reloads when `.context/`
+changes on disk. Older graphs with vague verbs (`influences`, `supports`) are
+normalized on load — no regeneration needed.
+
+---
+
+## Benchmark
+
+<!-- placeholder: fill from a committed bench/results/ run before launch -->
+
+The claim Graft has to earn is simple: an agent that reads the graph first is cheaper and faster without getting more answers wrong. The harness runs every task twice through the same agent with the same file tools. One run is **cold** (it explores from zero) and one is **graph** (it gets the `.context/` bundle up front). A separate model judges correctness, with a required-keyword floor so a fast-but-wrong answer cannot win.
+
+| Metric | Cold | Graph | Change |
+|---|---|---|---|
+| Tool calls | _TBD_ | _TBD_ | **−31%** |
+| Cost | _TBD_ | _TBD_ | **−23%** |
+| Latency | _TBD_ | _TBD_ | **−17%** |
+| Correctness | _TBD_ | _TBD_ | _at least as good as cold_ |
+
+_The numbers above are placeholders pending a committed run._ Reproduce it yourself:
+
+```bash
+npm run bench -- --smoke   # 1 corpus, 1 task, a quick plumbing check
+npm run bench              # full: all corpora, all tasks
+```
+
+See [`bench/README.md`](bench/README.md) for the method and how to add your own repo.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/NanoNets/context-graph-engine.git && cd context-graph-engine
+npm install
+npm run build
+npm test
+
+npm run cli -- init .      # run the CLI from source
+```
+
+---
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/ai/crux.d.ts

@@ -0,0 +1,31 @@
+import type { Kind } from "../graph/types.js";
+/** One definition we want described, located by its line span within the file. */
+export interface NodeRef {
+    id: string;
+    kind: Kind;
+    signature: string | null;
+    startLine: number;
+    endLine: number;
+}
+export interface FileCruxInput {
+    path: string;
+    source: string;
+    nodes: NodeRef[];
+}
+export interface NodeCrux {
+    id: string;
+    summary: string;
+    crux_start: number;
+    crux_end: number;
+}
+export interface CruxSummarizer {
+    describeFile(input: FileCruxInput): Promise<NodeCrux[]>;
+}
+/** Crux summarizer backed by OpenRouter's OpenAI-compatible chat API. */
+export declare class OpenRouterCruxSummarizer implements CruxSummarizer {
+    private client;
+    private model;
+    constructor(apiKey: string, model: string, baseUrl?: string);
+    describeFile(input: FileCruxInput): Promise<NodeCrux[]>;
+}
+//# sourceMappingURL=crux.d.ts.map

package/dist/ai/crux.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crux.d.ts","sourceRoot":"","sources":["../../src/ai/crux.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAE9C,kFAAkF;AAClF,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,IAAI,CAAC;IACX,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,OAAO,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;CACzD;AAwDD,yEAAyE;AACzE,qBAAa,wBAAyB,YAAW,cAAc;IAC7D,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAAS;gBAEV,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,SAAiC;IAS7E,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;CAa9D"}

package/dist/ai/crux.js

@@ -0,0 +1,91 @@
+/**
+ * Tier-2 "meaning" call for the code graph — batched one request per file.
+ *
+ * Given a source file (with 1-based line numbers) and the list of definitions in
+ * it, one call returns, for each definition:
+ *   1. `summary` — one plain-English sentence: what the symbol is *for*, at the
+ *      business-logic level, not a restatement of its signature.
+ *   2. `crux_start`/`crux_end` — the smallest contiguous range of FILE line
+ *      numbers (inside that symbol's own span) that a reviewer must read to see
+ *      the decision or rule the code encodes. `0/0` means there is no single
+ *      crux (a trivial getter, a plain data holder).
+ *
+ * Batching per file means N definitions cost one request, not N — and the model
+ * sees each symbol's neighbours, which sharpens the summaries. Line numbers are
+ * consumed once, at write time, to slice the crux text verbatim from source.
+ */
+import OpenAI from "openai";
+const SYSTEM_PROMPT = `You explain code definitions for a code graph that helps engineers navigate a codebase.
+
+You are given ONE source file with 1-based line numbers, and a list of TARGET definitions in it. For every target, return its purpose and the line range of its core logic.
+
+Return STRICT JSON, exactly:
+{ "symbols": [ { "id": string, "summary": string, "crux_start": number, "crux_end": number }, ... ] }
+
+Rules:
+- Emit exactly one entry per target id given, using that id verbatim.
+- summary: ONE sentence — what the symbol is FOR at the business-logic level. Say what problem it solves or rule it enforces, not what its signature already says.
+- crux_start / crux_end: FILE line numbers (as shown), inside that symbol's own line range. Pick the SINGLE most important contiguous span — the core branch, formula, guard, or state change. Keep it TIGHT: at most ~8 lines, and NEVER the whole function. If you can't narrow it below that, the symbol has no distinct crux — use 0/0.
+- Skip boilerplate, logging, and plumbing. If a symbol has no meaningful crux (trivial getter, data holder, one-line delegation, or logic spread evenly with no focal point), use "crux_start": 0 and "crux_end": 0.
+- Output ONLY the JSON object. No prose, no code fences.`;
+/** Cap the file text sent per request so one huge file can't blow the context. */
+const MAX_CODE_CHARS = 18_000;
+function numberLines(source) {
+    const clipped = source.length > MAX_CODE_CHARS ? `${source.slice(0, MAX_CODE_CHARS)}\n… (truncated)` : source;
+    return clipped
+        .split("\n")
+        .map((line, i) => `${i + 1}\t${line}`)
+        .join("\n");
+}
+function userContent(input) {
+    const targets = input.nodes
+        .map((n) => `- id=${n.id} | ${n.kind} | lines L${n.startLine}-L${n.endLine}` +
+        (n.signature ? ` | ${n.signature}` : ""))
+        .join("\n");
+    return `FILE: ${input.path}\n\n${numberLines(input.source)}\n\nTARGETS:\n${targets}`;
+}
+/** Best-effort parse of a model's JSON reply into a {@link NodeCrux} list. */
+function parseResults(raw) {
+    const text = raw.trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "");
+    const obj = JSON.parse(text);
+    if (!Array.isArray(obj.symbols))
+        return [];
+    const num = (v) => (typeof v === "number" && Number.isFinite(v) ? Math.trunc(v) : 0);
+    return obj.symbols
+        .map((s) => s)
+        .filter((s) => typeof s.id === "string")
+        .map((s) => ({
+        id: s.id,
+        summary: typeof s.summary === "string" ? s.summary.trim() : "",
+        crux_start: num(s.crux_start),
+        crux_end: num(s.crux_end),
+    }));
+}
+/** Crux summarizer backed by OpenRouter's OpenAI-compatible chat API. */
+export class OpenRouterCruxSummarizer {
+    client;
+    model;
+    constructor(apiKey, model, baseUrl = "https://openrouter.ai/api/v1") {
+        this.client = new OpenAI({
+            apiKey,
+            baseURL: baseUrl,
+            defaultHeaders: { "X-Title": "Context Graph Engine" },
+        });
+        this.model = model;
+    }
+    async describeFile(input) {
+        if (input.nodes.length === 0)
+            return [];
+        const response = await this.client.chat.completions.create({
+            model: this.model,
+            temperature: 0,
+            response_format: { type: "json_object" },
+            messages: [
+                { role: "system", content: SYSTEM_PROMPT },
+                { role: "user", content: userContent(input) },
+            ],
+        });
+        return parseResults(response.choices[0]?.message?.content ?? "");
+    }
+}
+//# sourceMappingURL=crux.js.map

package/dist/ai/crux.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crux.js","sourceRoot":"","sources":["../../src/ai/crux.ts"],"names":[],"mappings":"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"}

package/dist/ai/providers.d.ts

@@ -0,0 +1,37 @@
+import type { Summarizer } from "./summarize.js";
+import type { Synthesizer } from "./synthesize.js";
+/**
+ * User-facing configuration. Anything omitted falls back to environment
+ * variables and then to sensible defaults. The engine calls OpenRouter, so an
+ * API key is required for any LLM-backed operation.
+ */
+export interface EngineConfig {
+    /** Where the graph lives. Env: GRAFT_DIR. Default: `<repo>/.context`. */
+    contextDir?: string;
+    /** OpenRouter key for extraction + summarization. Env: OPENROUTER_API_KEY. */
+    openrouterApiKey?: string;
+    /** OpenRouter model id. Env: GRAFT_OPENROUTER_MODEL. Default: openai/gpt-4o-mini */
+    openrouterModel?: string;
+    /** OpenRouter API base URL. Env: OPENROUTER_BASE_URL. Default: https://openrouter.ai/api/v1 */
+    openrouterBaseUrl?: string;
+    /** Override the synthesizer (defaults to OpenRouter). */
+    synthesizer?: Synthesizer;
+    /** Override the code summarizer (defaults to OpenRouter). */
+    summarizer?: Summarizer;
+}
+/** Fully-resolved configuration with all defaults applied. */
+export interface ResolvedConfig {
+    contextDir?: string;
+    openrouterApiKey?: string;
+    openrouterModel: string;
+    openrouterBaseUrl: string;
+    synthesizer?: Synthesizer;
+    summarizer?: Summarizer;
+}
+export declare const DEFAULTS: {
+    readonly openrouterModel: "openai/gpt-4o-mini";
+    readonly openrouterBaseUrl: "https://openrouter.ai/api/v1";
+};
+/** Merge user config with environment variables and defaults. */
+export declare function resolveConfig(config?: EngineConfig): ResolvedConfig;
+//# sourceMappingURL=providers.d.ts.map

package/dist/ai/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../src/ai/providers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,8EAA8E;IAC9E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oFAAoF;IACpF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,+FAA+F;IAC/F,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAG3B,yDAAyD;IACzD,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,6DAA6D;IAC7D,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED,eAAO,MAAM,QAAQ;;;CAGX,CAAC;AAEX,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,MAAM,GAAE,YAAiB,GAAG,cAAc,CAYvE"}

package/dist/ai/providers.js

@@ -0,0 +1,17 @@
+export const DEFAULTS = {
+    openrouterModel: "openai/gpt-4o-mini",
+    openrouterBaseUrl: "https://openrouter.ai/api/v1",
+};
+/** Merge user config with environment variables and defaults. */
+export function resolveConfig(config = {}) {
+    const env = process.env;
+    return {
+        contextDir: config.contextDir ?? env.GRAFT_DIR,
+        openrouterApiKey: config.openrouterApiKey ?? env.OPENROUTER_API_KEY,
+        openrouterModel: config.openrouterModel ?? env.GRAFT_OPENROUTER_MODEL ?? DEFAULTS.openrouterModel,
+        openrouterBaseUrl: config.openrouterBaseUrl ?? env.OPENROUTER_BASE_URL ?? DEFAULTS.openrouterBaseUrl,
+        synthesizer: config.synthesizer,
+        summarizer: config.summarizer,
+    };
+}
+//# sourceMappingURL=providers.js.map

package/dist/ai/providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../../src/ai/providers.ts"],"names":[],"mappings":"AAoCA,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,eAAe,EAAE,oBAAoB;IACrC,iBAAiB,EAAE,8BAA8B;CACzC,CAAC;AAEX,iEAAiE;AACjE,MAAM,UAAU,aAAa,CAAC,SAAuB,EAAE;IACrD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IACxB,OAAO;QACL,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,GAAG,CAAC,SAAS;QAC9C,gBAAgB,EAAE,MAAM,CAAC,gBAAgB,IAAI,GAAG,CAAC,kBAAkB;QACnE,eAAe,EACb,MAAM,CAAC,eAAe,IAAI,GAAG,CAAC,sBAAsB,IAAI,QAAQ,CAAC,eAAe;QAClF,iBAAiB,EACf,MAAM,CAAC,iBAAiB,IAAI,GAAG,CAAC,mBAAmB,IAAI,QAAQ,CAAC,iBAAiB;QACnF,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,UAAU,EAAE,MAAM,CAAC,UAAU;KAC9B,CAAC;AACJ,CAAC"}

package/dist/ai/summarize.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Turns one source-code file into a short prose summary for the knowledge graph.
+ *
+ * Code repos are deliberately NOT fed through the per-chunk entity extractor:
+ * static structure is better served by grep/tree-sitter in the consuming agent,
+ * and LLM extraction over raw code produces noisy, duplicated entities. Instead
+ * the repo ingest path summarizes each file into plain English (purpose, key
+ * exports, dependencies, design decisions) and ingests those summaries — prose
+ * the existing extraction pipeline is actually good at.
+ */
+export interface Summarizer {
+    summarize(code: string, opts: {
+        path: string;
+    }): Promise<string>;
+}
+/** Summarizer backed by OpenRouter's OpenAI-compatible chat API. */
+export declare class OpenRouterSummarizer implements Summarizer {
+    private client;
+    private model;
+    constructor(apiKey: string, model: string, baseUrl?: string);
+    summarize(code: string, opts: {
+        path: string;
+    }): Promise<string>;
+}
+//# sourceMappingURL=summarize.d.ts.map

package/dist/ai/summarize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summarize.d.ts","sourceRoot":"","sources":["../../src/ai/summarize.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAClE;AAqBD,oEAAoE;AACpE,qBAAa,oBAAqB,YAAW,UAAU;IACrD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAAS;gBAEV,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,SAAiC;IAS7E,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;CAWvE"}

package/dist/ai/summarize.js

@@ -0,0 +1,41 @@
+import OpenAI from "openai";
+const SYSTEM_PROMPT = `You document source code for a team knowledge base. Given one source file, write a compact plain-English summary covering:
+1. The purpose of the file — what it exists to do.
+2. The key exported functions/classes/types and what each is for.
+3. Important dependencies: internal modules it builds on, external libraries or services it talks to.
+4. Notable design decisions, constraints, or gotchas evident in the code.
+
+Write 3-8 sentences of flowing prose. Name concrete identifiers (modules, classes, services) so they can become graph entities. No code blocks, no line-by-line narration, no filler.`;
+/** Cap the code sent per file so a single giant file can't blow the context. */
+const MAX_CODE_CHARS = 24_000;
+function userContent(code, path) {
+    const clipped = code.length > MAX_CODE_CHARS
+        ? `${code.slice(0, MAX_CODE_CHARS)}\n… (truncated at ${MAX_CODE_CHARS} characters)`
+        : code;
+    return `File: ${path}\n\n${clipped}`;
+}
+/** Summarizer backed by OpenRouter's OpenAI-compatible chat API. */
+export class OpenRouterSummarizer {
+    client;
+    model;
+    constructor(apiKey, model, baseUrl = "https://openrouter.ai/api/v1") {
+        this.client = new OpenAI({
+            apiKey,
+            baseURL: baseUrl,
+            defaultHeaders: { "X-Title": "Context Graph Engine" },
+        });
+        this.model = model;
+    }
+    async summarize(code, opts) {
+        const response = await this.client.chat.completions.create({
+            model: this.model,
+            temperature: 0,
+            messages: [
+                { role: "system", content: SYSTEM_PROMPT },
+                { role: "user", content: userContent(code, opts.path) },
+            ],
+        });
+        return response.choices[0]?.message?.content?.trim() ?? "";
+    }
+}
+//# sourceMappingURL=summarize.js.map

package/dist/ai/summarize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summarize.js","sourceRoot":"","sources":["../../src/ai/summarize.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAgB5B,MAAM,aAAa,GAAG;;;;;;sLAMgK,CAAC;AAEvL,gFAAgF;AAChF,MAAM,cAAc,GAAG,MAAM,CAAC;AAE9B,SAAS,WAAW,CAAC,IAAY,EAAE,IAAY;IAC7C,MAAM,OAAO,GACX,IAAI,CAAC,MAAM,GAAG,cAAc;QAC1B,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,qBAAqB,cAAc,cAAc;QACnF,CAAC,CAAC,IAAI,CAAC;IACX,OAAO,SAAS,IAAI,OAAO,OAAO,EAAE,CAAC;AACvC,CAAC;AAED,oEAAoE;AACpE,MAAM,OAAO,oBAAoB;IACvB,MAAM,CAAS;IACf,KAAK,CAAS;IAEtB,YAAY,MAAc,EAAE,KAAa,EAAE,OAAO,GAAG,8BAA8B;QACjF,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CAAC;YACvB,MAAM;YACN,OAAO,EAAE,OAAO;YAChB,cAAc,EAAE,EAAE,SAAS,EAAE,sBAAsB,EAAE;SACtD,CAAC,CAAC;QACH,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,IAAY,EAAE,IAAsB;QAClD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC;YACzD,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,WAAW,EAAE,CAAC;YACd,QAAQ,EAAE;gBACR,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,EAAE;gBAC1C,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE;aACxD;SACF,CAAC,CAAC;QACH,OAAO,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC7D,CAAC;CACF"}

package/dist/ai/synthesize.d.ts

@@ -0,0 +1,32 @@
+/** A directed edge to another node, by node name (resolved to a slug later). */
+export interface SynthLink {
+    to: string;
+    relation: string;
+    description?: string;
+}
+/** A node as proposed by the synthesizer, before it is written to disk. */
+export interface SynthNode {
+    name: string;
+    /** system | api | file | concept */
+    type: string;
+    summary: string;
+    /** Source file paths (from the provided set) this node is grounded in. */
+    sources: string[];
+    links: SynthLink[];
+}
+/** One labeled file summary fed into synthesis. */
+export interface FileSummary {
+    path: string;
+    summary: string;
+}
+export interface Synthesizer {
+    synthesize(files: FileSummary[]): Promise<SynthNode[]>;
+}
+/** Synthesizer backed by OpenRouter's OpenAI-compatible chat API (tool calling). */
+export declare class OpenRouterSynthesizer implements Synthesizer {
+    private client;
+    private model;
+    constructor(apiKey: string, model: string, baseUrl?: string);
+    synthesize(files: FileSummary[]): Promise<SynthNode[]>;
+}
+//# sourceMappingURL=synthesize.d.ts.map

package/dist/ai/synthesize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthesize.d.ts","sourceRoot":"","sources":["../../src/ai/synthesize.ts"],"names":[],"mappings":"AAUA,gFAAgF;AAChF,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,2EAA2E;AAC3E,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAED,mDAAmD;AACnD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;CACxD;AAgGD,oFAAoF;AACpF,qBAAa,qBAAsB,YAAW,WAAW;IACvD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAAS;gBAEV,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,SAAiC;IAK7E,UAAU,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;CAoB7D"}