feat(terraphim): add project-local .terraphim KG + thesaurus for terraphim-grep

Alex · Alex · commit 5d6908aae76f · 2026-06-29T09:11:23.000+01:00
KG-driven search configuration specific to pi_agent_rust so terraphim-grep
works offline (no server) with project-aware concept boosting.

- .terraphim/kg/: 13 project concepts (provider, session, extension, tool,
  sse, model-registry, acp, interactive-tui, conformance, hashline-edit,
  auth, asupersync, pi-terraphim-router), each with description + synonyms::
- .terraphim/thesaurus.json: 180 compiled entries (synonym -&gt; {id, nterm})
- .terraphim/config.json: Pi Agent Rust Engineer role -&gt; project KG + Ripgrep
  haystack

terraphim-grep loads the thesaurus (180 entries), fff-search scans the repo,
and matched concepts (e.g. 'extension','hostcall') boost relevant chunks
above the baseline score. Requires terraphim-grep built with the code-search
feature (fff-search); without it search_code is compiled out.
diff --git a/.terraphim/config.json b/.terraphim/config.json
@@ -0,0 +1,33 @@
+{
+  "name": "Pi Agent Rust Engineer",
+  "shortname": "piarust",
+  "relevance_function": "terraphim-graph",
+  "terraphim_it": true,
+  "theme": "united",
+  "kg": {
+    "automata_path": null,
+    "knowledge_graph_local": {
+      "input_type": "markdown",
+      "path": "/home/alex/projects/terraphim/pi_agent_rust/.terraphim/kg"
+    },
+    "public": false,
+    "publish": false
+  },
+  "haystacks": [
+    {
+      "location": "/home/alex/projects/terraphim/pi_agent_rust",
+      "service": "Ripgrep",
+      "read_only": true,
+      "fetch_content": false,
+      "atomic_server_secret": null,
+      "extra_parameters": {}
+    }
+  ],
+  "llm_enabled": false,
+  "llm_provider": "ollama",
+  "ollama_model": "llama3.2:3b",
+  "ollama_base_url": "http://127.0.0.1:11434",
+  "llm_router_enabled": false,
+  "llm_context_window": 32768,
+  "extra": {}
+}
diff --git a/.terraphim/kg/acp.md b/.terraphim/kg/acp.md
@@ -0,0 +1,9 @@
+# ACP
+
+Agent Client Protocol support. `pi --acp` runs pi as an ACP server (stdin JSON-RPC) so external clients drive it headlessly. Supports `session/set_model`, `session/set_config_option`, and `--session-dir` persistence. The runtime-parking fix (#107) stopped idle `--acp` from burning ~200% CPU. Distinct from the interactive TUI and the RPC/stdin bridge in `src/rpc.rs`.
+
+**Key files:** `src/main.rs`, `src/acp.rs`, `src/rpc.rs`
+
+Related: interactive-tui, session, rpc
+
+synonyms:: acp, agent client protocol, --acp, acp server, acp session, set_model, set_config_option, session-dir, json-rpc server, rpc mode, stdin mode, rpc
diff --git a/.terraphim/kg/asupersync.md b/.terraphim/kg/asupersync.md
@@ -0,0 +1,9 @@
+# asupersync
+
+Structured-concurrency async runtime from the sibling `../asupersync` crate. Powers HTTP client, TLS (webpki-roots), SQLite, cancellation, and explicit capability context (Cx). Enables deterministic testing via LabRuntime. pi pins `asupersync = "0.3.4"`. The runtime-parking fix (#107) relies on it to idle `--acp` without CPU spin.
+
+**Key files:** `Cargo.toml`, `src/http/client.rs`
+
+Related: provider, sse, session
+
+synonyms:: asupersync, async runtime, structured concurrency, runtime, labruntime, capability context, cx, http client, tls, webpki roots, cancellation, runtime parking
diff --git a/.terraphim/kg/auth.md b/.terraphim/kg/auth.md
@@ -0,0 +1,9 @@
+# Auth
+
+Credential storage and OAuth flows (`src/auth.rs`). `auth.json` (perms 600) at `~/.pi/agent/auth.json` holds OAuth tokens (openai-codex via localhost:1455 callback, anthropic, google gemini-cli via :8085, github copilot, kimi-for-coding) and API keys. `/login <provider>` runs the in-TUI OAuth flow; `pi doctor` reports token validity. Expired tokens must be re-logged-in.
+
+**Key files:** `src/auth.rs`, `~/.pi/agent/auth.json`
+
+Related: provider, interactive-tui
+
+synonyms:: auth, authentication, oauth, auth.json, login, /login, credentials, oauth token, token expired, api key, openai-codex login, kimi oauth, copilot login, auth storage, re-login
diff --git a/.terraphim/kg/conformance.md b/.terraphim/kg/conformance.md
@@ -0,0 +1,9 @@
+# Conformance
+
+Fixture-based conformance tests validating tool/provider/session behaviour against JSON fixtures (`tests/conformance.rs`, `tests/installer_regression.sh`). Fixture shape: `{version, tool, cases:[{name, setup, input, expected:{content_contains, content_regex, details_exact}}]}`. Run with `cargo test conformance`. Extension conformance lives under `tests/ext_conformance/`. Installer/skill integrity is gated by `scripts/skill-smoke.sh`.
+
+**Key files:** `tests/conformance.rs`, `tests/installer_regression.sh`, `scripts/skill-smoke.sh`
+
+Related: tool, extension, session
+
+synonyms:: conformance, conformance test, fixture, fixture test, conformance suite, installer regression, skill smoke, ext_conformance, test fixture, content_contains, details_exact
diff --git a/.terraphim/kg/extension.md b/.terraphim/kg/extension.md
@@ -0,0 +1,9 @@
+# Extension
+
+JavaScript extension runtime on QuickJS with a capability policy layer. Extensions provide extra tools/providers via hostcalls bridged through `src/extensions_js.rs`. The policy engine (`src/extensions.rs`) enforces allow/deny capability controls (filesystem, network, subprocess). Conformance fixtures under `tests/ext_conformance/` validate JS parity and taxonomy. The `wasm-host` feature gates a Wasmtime runtime alternative.
+
+**Key files:** `src/extensions.rs`, `src/extensions_js.rs`, `tests/ext_conformance/`
+
+Related: tool, provider, conformance
+
+synonyms:: extension, extensions, quickjs, quickjs runtime, javascript extension, capability policy, hostcall, hostcalls, extension runtime, wasm host, wasmtime, extension parity, extension taxonomy, extension oauth
diff --git a/.terraphim/kg/hashline-edit.md b/.terraphim/kg/hashline-edit.md
@@ -0,0 +1,9 @@
+# hashline_edit
+
+Precise-edit tool using `LINE#HASH` anchors emitted by `read`/`grep` with `hashline=true`. Avoids ambiguous string-match edits by pinning each edit to a line number + content hash, so concurrent drift can't silently mis-apply. One of the 8 built-in tools in `src/tools.rs`.
+
+**Key files:** `src/tools.rs`
+
+Related: tool
+
+synonyms:: hashline_edit, hashline, line hash, hash line, precise edit, line hash edit, hash anchor, LINE#HASH, hashline edit tool
diff --git a/.terraphim/kg/interactive-tui.md b/.terraphim/kg/interactive-tui.md
@@ -0,0 +1,9 @@
+# Interactive TUI
+
+Interactive terminal front-end (`src/interactive.rs`, `src/tui.rs`) built on the charmed_rust stack (bubbletea/lipgloss/bubbles/glamour) gated behind the default-on `tui` feature. 60fps differential rendering. Slash commands live in `src/interactive/commands.rs` (`/login`, `/model`, `/mcp`, `/help`). Mouse capture can be disabled with `PI_NO_MOUSE_CAPTURE=1` to let terminal-native copy/paste work during OAuth.
+
+**Key files:** `src/interactive.rs`, `src/interactive/commands.rs`, `src/tui.rs`, `Cargo.toml` (`tui` feature)
+
+Related: rpc, acp, model-registry
+
+synonyms:: interactive, tui, interactive tui, terminal ui, bubbletea, charmed_rust, lipgloss, glamour, slash command, /login, /model, /mcp, mouse capture, pi no mouse capture, frontend
diff --git a/.terraphim/kg/model-registry.md b/.terraphim/kg/model-registry.md
@@ -0,0 +1,9 @@
+# ModelRegistry
+
+Model resolution layer (`src/models.rs`, `src/app.rs`). Resolves `ModelEntry` records from built-in seeds, a legacy generated catalog, and a user `models.json` (with env/file value resolution). Upstream commit #117 made the data catalog authoritative for reasoning effort + thinking-control metadata. `PROVIDER_DEFAULT_MODELS` in `src/app.rs` lists newest-first default candidates per provider (e.g. kimi-for-coding -> kimi-k2.7, kimi-k2.6, ...). Autocomplete candidates drive the `/model` picker.
+
+**Key files:** `src/models.rs`, `src/app.rs`, `docs/provider-upstream-model-ids-snapshot.json`
+
+Related: provider, interactive-tui, auth
+
+synonyms:: model registry, modelregistry, model entry, modelentry, models.json, model catalog, built-in models, provider default models, model resolution, autocomplete, reasoning effort, thinking control, default model, model id, model fetch, kimi-k2.7, glm-5.2
diff --git a/.terraphim/kg/pi-terraphim-router.md b/.terraphim/kg/pi-terraphim-router.md
@@ -0,0 +1,9 @@
+# pi_terraphim_router
+
+Optional knowledge-graph model router (`src/pi_terraphim_router/`, ~1495 lines: mod/rpc_client/types/error). Feature-gated behind `terraphim-routing` (off by default). Uses a KgRouter with Aho-Corasick concept matching + readiness-aware fallback to pick a provider/model for a prompt. **Currently BLOCKED** on `task/terraphim-router-blocked`: its path deps (`terraphim_router/types/automata`) were extracted to the standalone terraphim-core repo (registry deps, Gitea #1910) and need migrating.
+
+**Key files:** `src/pi_terraphim_router/`, branch `task/terraphim-router-blocked`, `examples/terraphim_router.rs`
+
+Related: model-registry, provider, auth
+
+synonyms:: pi_terraphim_router, terraphim router, kg router, model routing, intelligent model selection, demoroute, demo-route, readiness-aware routing, terraphim-routing, terraphim-routing feature, aho-corasick router
diff --git a/.terraphim/kg/provider.md b/.terraphim/kg/provider.md
@@ -0,0 +1,9 @@
+# Provider
+
+Abstract LLM backend implementing the `Provider` trait (`src/provider.rs`). pi_agent_rust ships 10 native provider modules in `src/providers/`: Anthropic (streaming + extended thinking), OpenAI Chat Completions, OpenAI Responses/Codex Responses, Gemini, Cohere, Azure OpenAI, Bedrock, Vertex AI, GitHub Copilot, and GitLab Duo. Extension-provided providers bridge via stream-simple. Each provider maps a `ModelEntry` to an HTTP transport (`anthropic-messages`, `openai-completions`, `google-generative-ai`, `cohere-chat`, `bedrock-converse-stream`). Auth comes from `auth.json` (OAuth for codex/kimi/copilot; API keys otherwise).
+
+**Key files:** `src/provider.rs`, `src/providers/mod.rs`, `src/providers/{anthropic,openai,openai_responses,gemini,cohere,azure,bedrock,vertex,copilot,gitlab}.rs`
+
+Related: model-registry, sse, auth, tool
+
+synonyms:: provider, llm backend, llm provider, anthropic, openai, openai-codex, codex, gemini, google, cohere, azure, bedrock, vertex, github copilot, copilot, gitlab duo, gitlab, kimi, kimi-for-coding, deepseek, minimax, zai, provider trait, streaming provider
diff --git a/.terraphim/kg/session.md b/.terraphim/kg/session.md
@@ -0,0 +1,9 @@
+# Session
+
+JSONL session persistence (version 3 format) with a tree structure for branching. Entries are typed: Message, ModelChange, ThinkingLevel, Compaction, etc. Per-project session directories under `~/.pi/agent/sessions/` with a session-index metadata cache. SQLite backend is default-on via the `sqlite-sessions` feature (opt out with `--no-default-features`). Session replay/index correctness is covered by the `session` test module.
+
+**Key files:** `src/session.rs`, `src/session_index.rs`, `src/session_test.rs`
+
+Related: model-registry, interactive-tui, rpc
+
+synonyms:: session, sessions, jsonl session, session persistence, session tree, session branch, session index, session replay, sqlite session, sqlite-sessions, compaction, session entry, session migrate
diff --git a/.terraphim/kg/sse.md b/.terraphim/kg/sse.md
@@ -0,0 +1,9 @@
+# SSE
+
+Server-Sent Events parser for streaming LLM responses (`src/sse.rs`). Parses the chunked event stream from providers into deltas (text, tool-call, thinking). Drives streaming + tool-call parity across all providers; covered by the `sse` and `provider_streaming` test modules. Also underpins `src/providers/model_fetch.rs` dynamic model discovery.
+
+**Key files:** `src/sse.rs`, `src/providers/model_fetch.rs`, `tests/e2e_provider_streaming.rs`
+
+Related: provider, model-registry
+
+synonyms:: sse, server-sent events, sse parser, streaming, stream parser, event stream, delta, streaming response, provider streaming, provider_streaming, model fetch
diff --git a/.terraphim/kg/tool.md b/.terraphim/kg/tool.md
@@ -0,0 +1,9 @@
+# Tool
+
+Built-in agent tools (`src/tools.rs`) invoked by the agent loop (`src/agent.rs`): `read` (files with line numbers + image support), `write`, `edit` (string replacement), `bash` (shell with timeout), `grep` (content search with context), `find` (glob discovery), `ls`, and `hashline_edit` (precise `LINE#HASH` edits). Tool definitions carry JSON Schema; results are truncated for context safety. Extension tools are registered alongside built-ins.
+
+**Key files:** `src/tools.rs`, `src/agent.rs`
+
+Related: extension, hashline-edit, agent loop
+
+synonyms:: tool, tools, built-in tool, read tool, write tool, edit tool, bash tool, grep tool, find tool, ls tool, hashline_edit, agent tool, tool registry, tool call, tool definition
diff --git a/.terraphim/thesaurus.json b/.terraphim/thesaurus.json
