@polycode-projects/seonix 0.7.1 → 0.8.0

package/README.md

@@ -7,45 +7,25 @@ bounded **edit digest** you inject once at session start. Your agent edits from
 turn 1 without fishing through the repo.
 
 > **Headline.** Measured as **mean** input tokens per both-solved task (paired
-> arms, identical model pin). Under the shipped score-gap default (R1b), B017
-> re-tested across three models on a held-out TypeScript corpus and the existing
-> suites: two cells clear the ≥50% decision bar, both on exploration-bound
-> complex tasks — a TypeScript middleware task on **Haiku 4.5 at 59.6%** and a C#
-> service task on **Sonnet 4.6 at 53.5%** — with several more in the 35 to 48%
-> range. Across all measured cells the token cut tracks the turn cut
-> (Pearson 0.91): seonix saves tokens by removing exploration turns, so tasks
-> whose edit site is obvious change little. Indexing costs **$0**. The win is
-> task- and model-conditional; full method, numbers and the measurement contract
-> are in `BENCHMARK_017.md`.
+> arms, identical model pin). Under the shipped score-gap default, two cells clear
+> the ≥50% bar, both on exploration-bound complex tasks (a TypeScript middleware
+> task on **Haiku 4.5** and a C# service task on **Sonnet 4.6**), with several more
+> in the 35 to 48% range. The token cut tracks the turn cut: seonix saves tokens by
+> removing exploration turns, so tasks whose edit site is obvious change little.
+> Indexing costs **$0**. The win is task- and model-conditional. Full method,
+> numbers, and the measurement contract are in
+> [`BENCHMARKS.md`](https://gitlab.com/polycode-projects/seonix/-/blob/main/BENCHMARKS.md).
 
 - **Website / live demo:** https://seonix.polycode.co.uk
 - **Source + benchmarks:** https://gitlab.com/polycode-projects/seonix
 - **Licence:** AGPL-3.0-only
 
-## Cross-model comparison
-
-seonix on the cheaper **Sonnet 4.6** vs the flagship **Opus 4.8** out of the box,
-mean input tokens per solved run (N=3; N=5 where an otb cell reuses the B015
-baseline). `+` means seonix on Sonnet used fewer tokens.
-
-| full task name | otb / Opus 4.8 | solved | seonix / Sonnet 4.6 | solved | token change |
-| --- | --- | --- | --- | --- | --- |
-| ts-hono-utils-helper (simple) | 135k | 3/3 | 117k | 3/3 | +13% |
-| ts-hono-response-time-middleware | 345k | 3/3 | 555k | 3/3 | −61% |
-| ts-hono-json-envelope | 1,102k | 3/3 | 864k | 3/3 | +22% |
-| py-django-truncatelines-filter | 610k | 5/5 | 524k | 5/5 | +14% |
-| cs-eshoponweb-order-service-total | 318k | 5/5 | 154k | 3/3 | +51% |
-| cs-eshoponweb-basket-service-total | 353k | 5/5 | 255k | 3/3 | +28% |
-| js-express-request-id | 330k | 5/5 | 267k | 3/3 | +19% |
-| js-express-json-envelope | 174k | 5/5 | 185k | 3/3 | −7% |
-
-seonix on Sonnet used fewer input tokens than otb on Opus on six of these eight
-tasks, at equal correctness. This crosses model and arm together, so
-it is an illustration of practical value, not the paired within-model measurement
-the ≥50% decision rule uses. Across all 13 measured seonix cells the drop in input
-tokens is 0.91-correlated (Pearson) with the drop in turns (slope about 0.71):
-seonix saves tokens by letting the agent skip exploration turns, so where it
-removes no turns there is little to save.
+## A cheaper model, matched
+
+seonix on the cheaper **Sonnet 4.6** used fewer input tokens than out-of-the-box
+**Opus 4.8** on six of eight tasks, at equal correctness. The full cross-model
+table and the turns correlation (Pearson 0.91) are in
+[`BENCHMARKS.md`](https://gitlab.com/polycode-projects/seonix/-/blob/main/BENCHMARKS.md).
 
 ## Install
 
@@ -102,7 +82,10 @@ filesystem root). In the merged graph every module id and label is prefixed with
 the repo's directory basename (`mod:<repoName>/<relpath>`); when two repos share a
 basename the first in path sort order keeps the bare name and later ones get `-2`,
 `-3`, … appended. Each repo's git history and `.seonixignore` are handled per repo,
-exactly as in single mode. Cross-repo call edges only arise where a symbol name
+exactly as in single mode — a `.seonixignore` at the `multi_root` **parent** is NOT read
+(each sub-repo loads only its own). For an **estate-wide exclude**, put it in a `seonix.toml`
+at the directory you index from (`[index].exclude` / `secret_exclude`); that propagates to
+every sub-repo. Cross-repo call edges only arise where a symbol name
 resolves uniquely across the whole merged graph; ambiguous names are dropped, as
 within one repo. Query a merged graph by passing the merge root as `repo_path`
 (e.g. `seonix cli seonix_search '{"repo_path":"/abs/estate","query":"…"}'`).
@@ -301,9 +284,8 @@ Flags: `--focus <sym>` (default: highest-degree module), `--depth N` (default 2)
 f.html` (default `seon-graph.html`), `--data-out f.json` (split viewer + sidecar
 data file instead of embedding), `--graph <path>` (override the graph.json
 location), `--repo-url <url> --ref <branch>` (source links), `--site-nav`
-(add the site's absolute home entry), `--nlp` (include the optional wink-nlp
-lemma tier in the chat panel), `--force-inline` (embed the full graph inline even
-past the size gate that would otherwise split it out with a message).
+(add the site's absolute home entry), `--force-inline` (embed the full graph inline
+even past the size gate that would otherwise split it out with a message).
 
 By default `viz` also writes a `code-browser.html` (Chronograph) and a
 `timeline.html` next to `--out` with a working header nav; override their paths
@@ -319,15 +301,15 @@ N of M" header note when truncated).
 `/timeline.html`; live re-annotates on HEAD change via `/code-browser-version`) —
 port 0 (default) picks a free port.
 
-### `chat` — interactive client over the mechanical ask engine
+### `chat` — interactive tmct chat over the graph
 
 ```bash
-seonix chat [--repo /abs/path] [--with-claude|--with-copilot]
+seonix chat [--repo /abs/path]
 ```
 
-See [Chat](#chat) below for the full behaviour (slash-commands, focus tracking,
-conversational manners, session logging, the opt-in `--with-claude`/
-`--with-copilot` LLM fallback).
+Opens tmct's natural-language client over seonix's graph (see [Chat](#chat) below).
+The conversation layer is tmct (`@polycode-projects/the-mechanical-code-talker`);
+seonix supplies the graph through tmct's provider seam.
 
 ### `SEONIX_STORE` / `SEONIX_GRAPH_FORMAT`
 
@@ -405,114 +387,25 @@ for just the single self-contained graph file.
 ## Chat
 
 ```bash
-seonix chat [--repo /abs/path] [--with-claude | --with-copilot]
-```
-
-An interactive client over the typed code-graph (deterministic, no model calls).
-With no `--repo` the target defaults to the **git root** (`git rev-parse
---show-toplevel`), so running it from a nested package dir still indexes the whole
-repo; pass `--repo <path>` to override. Any **bare line** is a plain-English
-question dispatched through the mechanical `seonix_ask` engine — e.g. `which
-modules import walk.mjs` — and the graph answers. Aggregate questions are answered
-straight off the graph header: `how many classes are there` → `20 classes.`
-(`how many <classes|functions|modules|methods|commits>`, `count the …`, `number of
-…`). A near-miss structural question still gets the precise rephrase hint.
-
-**Conversational manners** (deterministic, zero-model, recognised *before* any graph
-dispatch). A small closed set of everyday expressions gets a templated reply rather
-than a grammar hint:
-
-| you say | you get |
-| --- | --- |
-| `hi` / `hello` / `hey` / `yo` / `g'day` / `good morning` (and `hello there`, with a small nod) | a short greeting + a nudge to ask or `/help` |
-| `thanks` / `ta` / `cheers` / `ty` | an "any time" acknowledgement |
-| `help` / `what can you do` / `who are you` / `?` | the orientation (the friendly help text; see also `/help`, `/stats`) |
-| `bye` / `goodbye` / `quit` / `see ya` | a farewell **and a clean end of session** (flushes the log, closes — the `/exit` path) |
-| `why` / `how` / `explain` / `say more` / `go on` / `elaborate` | **re-renders the last answer verbosely** — repeats it with the ask engine's traversal receipt and the full matched-entity list the terse render trims (no previous answer → it says so plainly) |
-
-These turns resolve no code entity, so — like `/help` — they are recorded as plain
-turns and never add `mgx:asksAbout` edges to the session graph.
-
-**Slash-commands** reach every other query tool in one line each: `/find <query>`
-(or `/search`) for a lexical search; `/context <symbol>` for the sized edit bundle
-(start here to change code) and `/snippet <symbol>` for exact source; `/describe`,
-`/signature`, `/members <class>`, `/subclasses <class>`, `/impact <module>`,
-`/callers`, `/callees`, `/tests <symbol>`, `/untested`, `/history <symbol>`,
-`/exports <module>` and `/arch [package]`, plus `/stats` for a one-screen overview
-(entity counts, relationship counts, package totals). An unknown `/command` just
-nudges you to `/help`; a bad symbol prints the tool's own clean error, never a stack.
-
-The client tracks a **focus** entity for multi-turn context. A command or an answer
-that resolves a primary entity remembers it (the prompt shows it, `seon(walk.mjs)>`);
-a bare `it`/`this`/`that` in a question then binds to it, and a no-argument entity
-command (`/context`, `/impact`, …) reuses it — so `what calls it` works straight
-after `/describe walk.mjs`. Set it explicitly with `/focus <symbol>`. With no focus
-set the client stays single-shot. `/help` lists the commands and the question
-shapes; `/exit` (or Ctrl+C/Ctrl+D) leaves.
-
-Each session is appended per turn to `<repo>/.seonix/session-<uuidv7>.log`, and
-becomes first-class graph data like a commit — **slash-command turns included**: a
-structured sidecar (`.seonix/sessions/*.jsonl`) records each turn's query, the
-command used, and the entities it resolved/answered; the session enters `graph.json`
-as a `Session` individual with `mgx:asksAbout` edges wherever a turn resolved an
-entity (re-attached on every re-index), and it appears on the `seonix viz` timeline.
-
-### Opt-in LLM fallback (`--with-claude` / `--with-copilot`)
-
-**Default OFF. Chat-only. Never in the benchmark, digest, or MCP path.** With a flag
-set, and *only* when the mechanical engine returns a genuine **miss** on a bare
-question (after the conversational layer and slash-commands have had their turn),
-chat consults an external LLM CLI — spawned in the target repo as cwd, with a
-timeout. To keep answers **graph-grounded** it asks the model to *compile one seonix
-command* (given the tool surface), then runs that command mechanically and shows the
-grounded result, **labelled `[LLM-assisted via …]`**. If the model can't produce a
-valid command, its raw text is shown instead, clearly marked `[answer from external
-model … — NOT the deterministic seonix engine]`; the two are never silently blended.
-
-- `--with-claude` → `claude -p "<compile-prompt>" --model haiku` (cheapest model).
-- `--with-copilot` → `gh copilot -- -p "<compile-prompt>" --allow-all-tools --no-color`.
-  **Limitation, honestly:** the GitHub Copilot CLI is an *agentic shell assistant*
-  (its native verbs are running commands and editing files), not a graph Q&A tool —
-  it has no knowledge of the seonix query surface beyond what the prompt hands it, so
-  it's a poorer fit than `claude -p` and is wired best-effort. Prefer `--with-claude`.
-
-Any failure — tool binary absent, non-zero exit, unparseable output, or timeout —
-degrades to the normal honest-miss hint; the flag never crashes or hangs the chat. If
-the flag is set but the binary is missing, chat says so **once at startup** and
-continues mechanical-only. No LLM call is ever made unless the flag is set **and** the
-mechanical engine missed — the hot path (and every benchmark run) stays zero-model.
-
-A real transcript against this repository's own index (verified answers):
-
-```text
-seon> where is buildContextBundle defined
-function buildContextBundle() is defined in packages/seonix/src/server.mjs at lines 138-260.
-
-seon> what uses codegraph.mjs
-bench/arms.mjs and bench/run.mjs and packages/seonix/src/ask.mjs and
-packages/seonix/src/chat.mjs and packages/seonix/src/extract.mjs and
-packages/seonix/src/server.mjs and packages/seonix/src/viz.mjs and scripts/rank-gate.mjs.
-
-seon> when did walk.mjs change
-packages/seonix/src/walk.mjs was last touched by commit a73ac1ba8bfb on 2026-07-01
-("feat(seonix): .seonixignore excludes […]"); 1 earlier commit recorded.
-
-seon> which changes touch commit 85073031
-commit 85073031ff05 touched modules packages/seonix/src/viz.mjs and
-packages/seonix/test/viz.test.mjs; functions buildViewerData() and cytoscapeSource().
-
-seon> which functions call bulidContextBundle
-assuming you meant buildContextBundle: in packages/seonix/src/server.mjs
-there is function dispatchTool().
+seonix chat [--repo /abs/path]
 ```
 
-Question shapes: `which <functions|classes|modules> <import|call|use|test|touch> <name>`,
-`what does <module> <import|export>`, `what uses <name>`, `where is <name> defined`,
-`where is <name> mentioned`, `when did <name> change`, `which changes touch commit <sha>`,
-`what does <term> mean`. Misspellings are corrected from a curated table, close
-near-misses resolve through a bounded edit-distance pass and are announced
-("assuming you meant"), and anything the graph cannot answer is a stated miss with
-a rephrase hint, never a guess.
+`seonix chat` opens an interactive natural-language client over the code graph. The
+conversation engine is **tmct** (`@polycode-projects/the-mechanical-code-talker`), a
+deterministic, no-LLM chatbot that seonix runs over its own graph through tmct's
+provider seam. Every answer is grounded in the graph or an honest miss. With no
+`--repo` the target defaults to the git root, so running it from a nested package dir
+still covers the whole repo.
+
+Ask structural questions in plain English — "which modules import walk.mjs", "where
+is buildContextBundle defined", "when did walk.mjs change" — and route slash-commands
+(`/context`, `/impact`, `/callers`, `/arch`, …) to the graph tools. On top of the
+query layer, tmct adds conversational memory, provenance and trust scoring,
+teach-and-recall, and multi-strategy interpretation. See the tmct docs for the full
+command set.
+
+seonix supplies the graph; tmct owns the conversation. The old opt-in
+`--with-claude`/`--with-copilot` fallback is gone — tmct is no-LLM by contract.
 
 ## Languages
 

package/bin/cli.mjs

@@ -33,7 +33,7 @@
 //   seonix viz [--focus <sym>] [--depth N] [--out f.html] [--data-out f.json] [--repo-url <gitlab url> --ref main] [--site-nav] → render a focused sub-graph to HTML (one shared viewer; data embedded, or split out with --data-out). By default also writes code-browser.html + timeline.html next to --out with a working header nav; --graph-only suppresses the siblings
 //   seonix viz --browser-out f.html [--browser-data-out f.json] [--timeline-out f.html] [--scope product|<prefixes>] → override the sibling artifact paths (Chronograph code browser: temporal scrub + two-cursor diff + narration + ghost-branch merges + keyboard nav; archive/PLAN_CODE_BROWSER.md)
 //   seonix viz --serve [--port N] [--focus <sym>]        → serve the same viewer against THIS repo's index (the local equivalent of the site's #viz; code browser at /code-browser.html, live-reannotating on HEAD change via /code-browser-version)
-//   seonix chat [--repo <abs>] [--with-claude|--with-copilot] → interactive prompt over the mechanical seonix_ask engine; /exit to leave; session log → <repo>/.seonix/session-<uuidv7>.log. The optional --with-* flags add an opt-in LLM fallback used ONLY when the mechanical engine misses a bare question (chat-only, never in the benchmark path)
+//   seonix chat [--repo <abs>] → interactive tmct chat over the graph (@polycode-projects/the-mechanical-code-talker, a deterministic no-LLM chatbot run through tmct's provider seam); /exit to leave
 //
 // The index step is offline and model-free (Python ast + git). It writes the
 // graph artifact to <repo_path>/.seonix/graph.json; the server (started with
@@ -643,15 +643,12 @@ async function main() {
   }
 
   if (mode === "chat") {
-    const { runChat } = await import("../src/chat.mjs");
+    // The chat surface is tmct's now (PLAN_CHAT_EXTRACTION.md — the inversion): run tmct's chat
+    // over seonix's native graph via tmct's provider seam. The old --with-claude/--with-copilot
+    // LLM fallback does not port (tmct is no-LLM by contract).
+    const { runSeonixChat } = await import("../src/chat-shim.mjs");
     const i = process.argv.indexOf("--repo");
-    // Opt-in LLM fallback (chat-only, default OFF, miss-gated — never in the benchmark
-    // path): --with-claude shells `claude -p`, --with-copilot shells `gh copilot -- -p`.
-    await runChat({
-      repoPath: i !== -1 ? process.argv[i + 1] : undefined,
-      withClaude: process.argv.includes("--with-claude"),
-      withCopilot: process.argv.includes("--with-copilot"),
-    });
+    await runSeonixChat({ repoPath: i !== -1 ? process.argv[i + 1] : undefined });
     return;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/seonix",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "private": false,
   "type": "module",
   "description": "SEONIX — a deterministic, offline, $0 code-graph tool that makes a cheap coding agent edit like an expensive one. Indexes a repo with Python ast + git (zero model calls) and renders a bounded edit-digest.",
@@ -44,14 +44,13 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@polycode-projects/the-mechanical-code-talker": "^0.6.0",
     "cytoscape": "^3.30.0",
     "smol-toml": "^1.7.0",
     "tree-sitter": "^0.21.1",
     "tree-sitter-c-sharp": "^0.21.3",
     "tree-sitter-java": "^0.21.0",
-    "typescript": "~5.6.2",
-    "wink-eng-lite-web-model": "^1.8.1",
-    "wink-nlp": "^2.4.0"
+    "typescript": "~5.6.2"
   },
   "scripts": {
     "test": "node --test \"test/**/*.test.mjs\"",

package/src/ask-browser-entry.mjs

@@ -0,0 +1,43 @@
+// ask-browser-entry.mjs — the esbuild entry for the website "Ask the graph" panel.
+//
+// PLAN_CHAT_EXTRACTION.md, the inversion: the panel's mechanical NL engine is now tmct's
+// (@polycode-projects/the-mechanical-code-talker), bundled for the browser. It runs adapter-less
+// (no wink model in the browser — tmct's ask degrades to its curated + fuzzy tiers), so the ~4 MB
+// wink bundle is dropped from the site.
+//
+// This entry is bundled by scripts/build-ask-bundle.mjs into src/ask-browser.bundle.js (an IIFE),
+// which viz.mjs inlines into the viewer page. It exposes two globals the panel's inline JS uses:
+//   parseEntities(payload) → the graph object tmct's ask consumes
+//   ask(graph, query, opts) → { content, seonix_ask }  (tmct's tmct_ask, renamed for the panel)
+import { ask as tmctAsk } from "@polycode-projects/the-mechanical-code-talker/ask";
+
+// A self-contained parseEntities, byte-identical in output to seonix's and tmct's (the seonix-ask
+// data file is already expanded by source.fetchEntities, so there is no v2 interning to undo here).
+// Kept inline so the browser bundle pulls in nothing from seonix's Node-side codegraph stack.
+function parseEntities(payload) {
+  const individuals = Array.isArray(payload?.individuals) ? payload.individuals : [];
+  const byId = new Map();
+  for (const ind of individuals) if (ind && ind.id) byId.set(ind.id, ind);
+  const relations = (Array.isArray(payload?.objectProperties) ? payload.objectProperties : []).map((g) => {
+    const edges = (Array.isArray(g?.examples) ? g.examples : []).filter((e) => e && e.subject && e.object);
+    return { predicate: String(g?.predicate || ""), prop: g?.prop ?? null, count: Number(g?.count) || edges.length, edges };
+  });
+  return {
+    individuals,
+    byId,
+    relations,
+    truncated: Boolean(payload?.truncated),
+    generatedAt: payload?.generated_at || "",
+    proseIndex: payload?.proseIndex || {},
+  };
+}
+
+// Panel-compatible wrapper: tmct's ask returns { content, tmct_ask }; the panel's inline JS reads
+// `seonix_ask.matches` / `.miss`, so rename the envelope. The match/miss shape is shared.
+function ask(graph, query, opts) {
+  const r = tmctAsk(graph, query, opts);
+  return { content: r.content, seonix_ask: r.tmct_ask };
+}
+
+globalThis.parseEntities = parseEntities;
+globalThis.ask = ask;