feat: graph context injection — the session's prior knowledge, steered in at session start (vision-context-injection.md)
One shot per chat, fired at the first turn's onFinish: the session's topic (its only typed message) is embedded as an EmbeddingGemma retrieval query; the semantically closest graph propositions are selected under the session's token budget (pure budget, no similarity threshold — the decided doctrine) and delivered as a marker-only steer through the wake pipeline, queuing behind pending questions like every sub-agent result. - contracts: ChatSettings.graphContextTokens (default 1024, max 4096, step 128, 0 = off); GraphContextData + graphContextText; the graph-context JobKind + buildGraphContextSteer (id steer_ctx_<chatId>) - core/graph-context.ts: brute-force cosine top-K, greedy chars/4 fill under budget, most-recent UnderstandingLevel fold, count cap 64, parse-don't-cast at the marker seam - server: embedQuery (role-asymmetric query format, same warm singleton — vector-space parity by construction); the runner (startGraphContext- Injection one-shot gates; runGraphContextJob validates ledger parity); wake branches (chatIdOf/jobIdOf, finalizeJob done, recoverStaleJobs re-deliver or contextRespawn); abortJob kills context jobs SILENTLY (nothing was promised in the lesson); turn-service trigger seam - adapter: data-graph-context flattens to the canonical block (malformed parts have no model face) - UI: the budget slider (home dock + /chat/new draft, the session-data strip); the quiet SystemLine "~537 · 10 propositions"; dock kind "Knowledge context"; model-picker PUT now spreads settings (a model pick can no longer clear the sibling override) Live-smoked end to end on the real embedder + real GLM: seeded ledger (10 propositions), session on "modal logic: possible worlds and the necessity box" — job in the dock, queued behind the prober's question, delivered on the answer, SystemLine in the transcript, wake turn reads the block and continues the probe. Gates: tsc, lint, 459/459, build.
This commit is contained in:
amosblomqvist
@@ -10,7 +10,7 @@ import type { UIMessage } from "ai";
|
||||
import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
|
||||
import type { Phase3 } from "../phases.ts";
|
||||
import type { PlanNodeStatus, PlanTree } from "./plan.ts";
|
||||
import type { EmissionStats } from "./graph.ts";
|
||||
import type { EmissionStats, UnderstandingLevel } from "./graph.ts";
|
||||
|
||||
// ─── Chat records (the session store's on-disk format) ───────────────────────
|
||||
|
||||
@@ -58,8 +58,23 @@ export interface ChatSettings {
|
||||
/** pi thinking level — must be in the chosen model's supported list
|
||||
* (getSupportedThinkingLevels; enforced by the settings route). */
|
||||
thinkingLevel?: ThinkingLevel;
|
||||
/** Graph context injection (vision-context-injection.md): the session's
|
||||
* token budget for the prior-knowledge block — the top semantically
|
||||
* closest propositions from the knowledge graph, injected once, at
|
||||
* session start, as a steer. Absent = the default (on); 0 = off. The
|
||||
* settings route enforces the range; the trigger (turn-service →
|
||||
* subagents/graph-context.ts) is one-shot, so a mid-session change
|
||||
* affects only sessions that haven't injected yet. */
|
||||
graphContextTokens?: number;
|
||||
}
|
||||
|
||||
/** The injection budget's decided knobs (2026-09-14): default 1024 (a
|
||||
* meaningful, modest slice of prior knowledge), hard max 4096, slider
|
||||
* step 128, 0 = off. */
|
||||
export const GRAPH_CONTEXT_TOKENS_DEFAULT = 1024;
|
||||
export const GRAPH_CONTEXT_TOKENS_MAX = 4096;
|
||||
export const GRAPH_CONTEXT_TOKENS_STEP = 128;
|
||||
|
||||
// ─── Background-extraction usage (the money channel, extraction side) ────────
|
||||
|
||||
/** One pipeline stage's model usage — the stage's model + every step it
|
||||
@@ -176,6 +191,54 @@ export const HANDOFF_TEXT =
|
||||
"The probe is concluded — the learner assessment is recorded. " +
|
||||
"Author the session's plan map now (call plan_init) and present it, then begin teaching.";
|
||||
|
||||
// ─── Graph context injection (vision-context-injection.md, 2026-09-14) ────────
|
||||
|
||||
/** One selected prior-knowledge proposition: similarity-ranked, annotated
|
||||
* with the learner's CURRENT understanding level — the fold is MOST
|
||||
* RECENT extraction instance (levels are per-instance, tied to moments in
|
||||
* time; the latest evidence is the best estimate of current understanding).
|
||||
* null = the node has no observation event at all. */
|
||||
export interface GraphContextProposition {
|
||||
id: string;
|
||||
statement: string;
|
||||
level: UnderstandingLevel | null;
|
||||
}
|
||||
|
||||
/** The data-graph-context part payload: what the UI renders (the counts)
|
||||
* AND the audit trail (the full block content — the transcript shows
|
||||
* exactly what was injected, and when). The model-facing text is derived
|
||||
* from this by graphContextText below — the adapter flattens the marker
|
||||
* part to it (the custom-message scheme: no authored human speech). */
|
||||
export interface GraphContextData {
|
||||
chatId: string;
|
||||
/** The session's budget at injection time (for the card's readout). */
|
||||
budget: number;
|
||||
/** Estimated tokens of the injected block — chars/4 heuristic. */
|
||||
tokens: number;
|
||||
/** The selected propositions, similarity-descending. */
|
||||
propositions: GraphContextProposition[];
|
||||
}
|
||||
|
||||
/** The model-facing block text — single-sourced (the adapter, the tests,
|
||||
* and reality can't drift). The level word travels with each line: the
|
||||
* closing gloss tells the agent what to do with each. */
|
||||
export function graphContextText(data: GraphContextData): string {
|
||||
const n = data.propositions.length;
|
||||
if (n === 0) return "";
|
||||
const lines = data.propositions.map(
|
||||
(p) => `- ${p.level ? `[${p.level}] ` : ""}${p.statement}`,
|
||||
);
|
||||
return [
|
||||
`Prior-knowledge context — what this learner already knows (from their knowledge graph, ` +
|
||||
`${n} proposition${n === 1 ? "" : "s"}, ~${data.tokens} tokens):`,
|
||||
"",
|
||||
...lines,
|
||||
"",
|
||||
"Treat this as reliable prior knowledge: build on what is solid, firm up what is shaky, " +
|
||||
"and teach around anything resisted. Do not re-teach solid ground.",
|
||||
].join("\n");
|
||||
}
|
||||
|
||||
export interface PlanBlockData {
|
||||
/** Only "full" survives (the 2026-09-11 pivot): the plan renders IN
|
||||
* FLOW once, at authoring. The neighborhood fragments are retired —
|
||||
|
||||
@@ -7,11 +7,11 @@
|
||||
* of "ai" (safe everywhere: server, client, tests). See docs/vision.md.
|
||||
*/
|
||||
import type { UIMessage } from "ai";
|
||||
import type { CallUsage } from "./chat.ts";
|
||||
import type { CallUsage, GraphContextData } from "./chat.ts";
|
||||
|
||||
// ─── Async sub-agent jobs (vision §2.5; plan.md Wave 0 protocol) ────────────
|
||||
|
||||
export type JobKind = "research" | "demo" | "visual";
|
||||
export type JobKind = "research" | "demo" | "visual" | "graph-context";
|
||||
export type JobStatus = "running" | "done" | "error";
|
||||
|
||||
export interface JobRecord {
|
||||
@@ -263,7 +263,11 @@ export interface AbortSteerMessage extends UIMessage {
|
||||
}
|
||||
|
||||
/** Anything the wake pipeline may queue and deliver. */
|
||||
export type SteerMessage = SubagentSteerMessage | AbortSteerMessage | ProbeHandoffSteerMessage;
|
||||
export type SteerMessage =
|
||||
| SubagentSteerMessage
|
||||
| AbortSteerMessage
|
||||
| ProbeHandoffSteerMessage
|
||||
| GraphContextSteerMessage;
|
||||
|
||||
/** Whether a result is the failure shape (html/svg empty, failure brief). */
|
||||
export function isSubagentFailure(kind: JobKind, result: ResearchResult | DemoResult | VisualResult): boolean {
|
||||
@@ -380,6 +384,34 @@ export function buildProbeHandoffSteer(chatId: string): ProbeHandoffSteerMessage
|
||||
};
|
||||
}
|
||||
|
||||
// ─── the graph-context steer (vision-context-injection.md) ───────────────────
|
||||
//
|
||||
// The injection's delivery: same wake pipeline, same gates — it queues
|
||||
// behind a pending quiz and rides the turn after the learner's answer, or
|
||||
// fires in the pump's idle window. Marker-only (the custom-message scheme):
|
||||
// no text part; the adapter flattens data-graph-context to graphContextText
|
||||
// (core/contracts/chat.ts owns the wording). One per chat, ever — the id is
|
||||
// deterministic per chat, so re-delivery is idempotent.
|
||||
|
||||
export interface GraphContextSteerMessage extends UIMessage {
|
||||
id: `steer_ctx_${string}`;
|
||||
role: "user";
|
||||
metadata: { graphContext: { chatId: string; jobId: string } };
|
||||
parts: [{ type: "data-graph-context"; data: GraphContextData }];
|
||||
}
|
||||
|
||||
export function buildGraphContextSteer(
|
||||
meta: { chatId: string; jobId: string },
|
||||
data: GraphContextData,
|
||||
): GraphContextSteerMessage {
|
||||
return {
|
||||
id: `steer_ctx_${meta.chatId}`,
|
||||
role: "user",
|
||||
metadata: { graphContext: meta },
|
||||
parts: [{ type: "data-graph-context", data }],
|
||||
};
|
||||
}
|
||||
|
||||
/** True when the transcript already carries this steer — idempotent
|
||||
* delivery for ANY steer kind: every steer id is deterministic per its
|
||||
* event (steer_<jobId> for jobs, steer_probe_<chatId> for the handoff). */
|
||||
|
||||
@@ -0,0 +1,184 @@
|
||||
/**
|
||||
* Graph context injection — the pure selection core
|
||||
* (docs/vision-context-injection.md, settled 2026-09-14).
|
||||
*
|
||||
* The heavy lifting is deliberately tiny: embedding the topic is the only
|
||||
* slow step (the embedder singleton), and SEARCH IS BRUTE-FORCE COSINE —
|
||||
* ~1M multiply-adds at 2k propositions, exact top-K from the in-memory
|
||||
* ledger, no ANN index until ~10⁶ scale (far away).
|
||||
*
|
||||
* Selection doctrine (owner-decided): the token budget is the ONLY control
|
||||
* on amount — there is NO similarity threshold. Similarity decides ORDER
|
||||
* (which propositions fill the budget first); irrelevant-but-cheap content
|
||||
* rides along harmlessly. Levels fold MOST RECENT: UnderstandingLevel lives
|
||||
* per extraction instance (tied to moments in time), and the latest evidence
|
||||
* is the best estimate of current understanding — an optimistic fold risks
|
||||
* stale claims, a pessimistic fold wastes covered ground.
|
||||
*/
|
||||
|
||||
|
||||
import {
|
||||
GRAPH_CONTEXT_TOKENS_MAX,
|
||||
type GraphContextData,
|
||||
type GraphContextProposition,
|
||||
graphContextText,
|
||||
} from "./contracts/chat.ts";
|
||||
import type { UnderstandingLevel } from "./contracts/graph.ts";
|
||||
import type { GraphNode, LedgerEvent } from "./contracts/graph.ts";
|
||||
|
||||
/** Belt-and-braces count cap — the budget is the primary control; a huge
|
||||
* budget still can't pour hundreds of lines into the block. */
|
||||
export const GRAPH_CONTEXT_MAX_PROPOSITIONS = 64;
|
||||
|
||||
/** The block's framing (header + gloss) in estimated tokens — reserved so
|
||||
* the composed block, not just the proposition lines, stays under budget. */
|
||||
const FRAMING_TOKENS = 55;
|
||||
|
||||
const LEVELS: ReadonlySet<string> = new Set([
|
||||
"solid",
|
||||
"shaky",
|
||||
"accepted",
|
||||
"resisted",
|
||||
"not yet engaged",
|
||||
]);
|
||||
|
||||
export function isUnderstandingLevel(word: unknown): word is UnderstandingLevel {
|
||||
return typeof word === "string" && LEVELS.has(word);
|
||||
}
|
||||
|
||||
/**
|
||||
* Fold each node's CURRENT understanding level: the level word of its most
|
||||
* recent observation event (latest `at`; ledger order breaks ties — the
|
||||
* same rule the snapshot's nodeObservations uses, but across ALL sessions,
|
||||
* not per chat). Malformed notes (not on the scale) never count.
|
||||
*/
|
||||
export function currentUnderstanding(events: LedgerEvent[]): Map<string, UnderstandingLevel> {
|
||||
const latest = new Map<string, { at: string; level: UnderstandingLevel; index: number }>();
|
||||
events.forEach((event, index) => {
|
||||
if (event.kind !== "observation" || event.nodeId === null) return;
|
||||
if (!isUnderstandingLevel(event.note)) return;
|
||||
const current = latest.get(event.nodeId);
|
||||
if (!current || event.at > current.at || (event.at === current.at && index > current.index)) {
|
||||
latest.set(event.nodeId, { at: event.at, level: event.note, index });
|
||||
}
|
||||
});
|
||||
const levels = new Map<string, UnderstandingLevel>();
|
||||
for (const [nodeId, { level }] of latest) levels.set(nodeId, level);
|
||||
return levels;
|
||||
}
|
||||
|
||||
/** Estimated tokens for one proposition line: chars/4 (the agreed
|
||||
* heuristic — no server-side tokenizer) + one for the level tag. */
|
||||
function lineTokens(p: GraphContextProposition): number {
|
||||
return Math.ceil(p.statement.length / 4) + (p.level ? 1 : 0);
|
||||
}
|
||||
|
||||
export interface SelectGraphContextInput {
|
||||
chatId: string;
|
||||
/** The topic's query embedding (same model + dim as the ledger — the
|
||||
* caller asserts parity; dimension-mismatched vectors are skipped). */
|
||||
query: number[];
|
||||
/** The embeddings ledger's vectors: nodeId → truncated, L2-normalized
|
||||
* (cosine = dot product). */
|
||||
vectors: Record<string, number[]>;
|
||||
/** Raw node lines (append order; first line per id defines — the
|
||||
* ledger merge rule, mirrored from core/graph.ts). */
|
||||
nodes: GraphNode[];
|
||||
/** The event ledger — for the most-recent level fold. */
|
||||
events: LedgerEvent[];
|
||||
/** The session's token budget (estimated tokens, chars/4). */
|
||||
budget: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Select the prior-knowledge block: similarity-descending greedy fill under
|
||||
* the token budget, capped by count, each line annotated with its folded
|
||||
* current level. Pure — server composes it with the embedder; tests drive
|
||||
* it with hand-made vectors.
|
||||
*/
|
||||
export function selectGraphContext(input: SelectGraphContextInput): GraphContextData {
|
||||
const { chatId, query, vectors, nodes, events, budget } = input;
|
||||
const levels = currentUnderstanding(events);
|
||||
|
||||
// Score every embedded node: dot product (vectors are normalized). A
|
||||
// dimension mismatch (a stale ledger, a foreign query) never scores.
|
||||
const scored: Array<{ id: string; statement: string; score: number }> = [];
|
||||
const seen = new Set<string>();
|
||||
for (const node of nodes) {
|
||||
if (seen.has(node.id)) continue; // first line defines (merge rule)
|
||||
seen.add(node.id);
|
||||
const vec = vectors[node.id];
|
||||
if (!vec || vec.length !== query.length) continue;
|
||||
let dot = 0;
|
||||
for (let i = 0; i < query.length; i++) dot += query[i]! * vec[i]!;
|
||||
scored.push({ id: node.id, statement: node.statement, score: dot });
|
||||
}
|
||||
scored.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
|
||||
|
||||
// Greedy fill: similarity order decides WHICH propositions enter; the
|
||||
// budget decides WHEN to stop. No similarity threshold, by design.
|
||||
const propositions: GraphContextProposition[] = [];
|
||||
let used = FRAMING_TOKENS;
|
||||
for (const { id, statement } of scored) {
|
||||
if (propositions.length >= GRAPH_CONTEXT_MAX_PROPOSITIONS) break;
|
||||
const p: GraphContextProposition = {
|
||||
id,
|
||||
statement,
|
||||
level: levels.get(id) ?? null,
|
||||
};
|
||||
const cost = lineTokens(p);
|
||||
if (used + cost > budget) continue; // too big for the budget — a later, smaller one may still fit
|
||||
used += cost;
|
||||
propositions.push(p);
|
||||
}
|
||||
return { chatId, budget, tokens: used, propositions };
|
||||
}
|
||||
|
||||
/** True when the selection would inject anything (guards the runner: an
|
||||
* empty block is never delivered — no steer, the job errors instead). */
|
||||
export function hasContext(data: GraphContextData): boolean {
|
||||
return data.propositions.length > 0 && graphContextText(data).length > 0;
|
||||
}
|
||||
|
||||
// ─── The marker-part parser (parse-don't-cast — tool-parts doctrine) ──────────
|
||||
|
||||
function parseProposition(raw: unknown): GraphContextProposition | null {
|
||||
if (typeof raw !== "object" || raw === null) return null;
|
||||
const { id, statement, level } = raw as Record<string, unknown>;
|
||||
if (typeof id !== "string" || typeof statement !== "string") return null;
|
||||
if (level !== null && level !== undefined && !isUnderstandingLevel(level)) return null;
|
||||
return { id, statement, level: (level as UnderstandingLevel | null | undefined) ?? null };
|
||||
}
|
||||
|
||||
function parseGraphContextData(raw: unknown): GraphContextData | null {
|
||||
if (typeof raw !== "object" || raw === null) return null;
|
||||
const { chatId, budget, tokens, propositions } = raw as Record<string, unknown>;
|
||||
if (typeof chatId !== "string") return null;
|
||||
if (typeof budget !== "number" || budget < 0 || budget > GRAPH_CONTEXT_TOKENS_MAX) return null;
|
||||
if (typeof tokens !== "number" || tokens < 0) return null;
|
||||
if (!Array.isArray(propositions)) return null;
|
||||
const parsed: GraphContextProposition[] = [];
|
||||
for (const item of propositions) {
|
||||
const p = parseProposition(item);
|
||||
if (!p) return null; // malformed content: the whole part is untrusted
|
||||
parsed.push(p);
|
||||
}
|
||||
return { chatId, budget, tokens, propositions: parsed };
|
||||
}
|
||||
|
||||
/**
|
||||
* The data-graph-context part of a message, validated — or null when the
|
||||
* part is absent or malformed. The seam the adapter and the chat view read
|
||||
* the marker through (never a raw cast: the part's data crossed a
|
||||
* serialization boundary).
|
||||
*/
|
||||
export function graphContextOfMessage(
|
||||
message: { parts: ReadonlyArray<{ type: string; data?: unknown }> },
|
||||
): GraphContextData | null {
|
||||
for (const part of message.parts) {
|
||||
if (part.type === "data-graph-context") {
|
||||
return parseGraphContextData((part as { data?: unknown }).data);
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
@@ -34,3 +34,4 @@ export * from "./ui-message.ts";
|
||||
export * from "./tool-parts.ts";
|
||||
export * from "./prices.ts";
|
||||
export * from "./fuzzy.ts";
|
||||
export * from "./graph-context.ts";
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
import type { UIMessage } from "ai";
|
||||
import type {
|
||||
DemoToolInput,
|
||||
GraphContextData,
|
||||
PlanVerdictData,
|
||||
PlanBlockData,
|
||||
ProbeDoneInput,
|
||||
@@ -46,6 +47,10 @@ export type TeacherUIDataParts = {
|
||||
/** The probe→teach handoff wake: the wake pipeline's steer message,
|
||||
* carrying ONLY this part (the model-facing text lives in the adapter). */
|
||||
"probe-handoff": { chatId: string };
|
||||
/** The prior-knowledge injection's delivery (vision-context-injection.md):
|
||||
* the marker-only steer — the counts for the UI, the full block content
|
||||
* for the audit trail; the adapter flattens it to graphContextText. */
|
||||
"graph-context": GraphContextData;
|
||||
/** The abort steer's message-type marker (the abort badge renders off it). */
|
||||
"subagent-aborted": SubagentResultMeta & { aborted: true };
|
||||
};
|
||||
|
||||
Reference in New Issue
Block a user