graph/walk: gather context by walking the graph with a decision model

[Evanfeenstra]

What

A graph/walk lib step that gathers context for a goal by walking the knowledge graph. At each hop a decision model judges the options; there's no generative agent loop.

• The walk is code. It seeds from start ref_ids or a query search. Each hop fetches one node's neighbors (the graph/graph-neighbors call: importance-sorted, capped at 50, same excluded types) and makes ONE decider call asking three independent questions:

  • relevant_c<i> (boolean): one per new neighbor.
  • next (choice): this hop's candidates, the frontier's best, or none.
  • sufficient (boolean).

  Kept nodes are ordered by relevance. The walk stops on sufficient, maxNodes, none, maxHops, or an empty frontier.

• Output is a context bundle for an llm/agent step: { goal, nodes: [{ref_id, node_type, name, relevance, hop, via, properties}], hops, stopped, usage }, provenance-marked with the expanded and kept nodes. Every hop emits a nested run event (<path>/NNN-hop), so a walk shows up in the events panel like an agent's tool calls.

• The decider is experimental_evaluate (ai@7). src/evaluate.ts exposes modelEvaluate(model), one evaluate call behind an injectable Evaluate type, so tests script it. resolveEvaluationModel (in src/llm.ts) picks the model:

  • model: jev (or jev-<ver> / typesafe/<id>): TypeSafe's evaluation model via @ai-sdk/typesafe-ai, keyed by TYPESAFE_AI_API_KEY from the secret store, then env. It's non-generative, runs in 70–500 ms, bills $0.042/MTok for input with output free, and returns calibrated probabilities. next_probabilities is filled in from its choice probabilities.
  • No model given: jev when that key is configured, else STRUT_LLM_MODEL / STRUT_LLM_PROVIDER.
  • Any other name: resolved as in the llm step, then wrapped in the SDK's EvaluationLanguageModel (the same wrapper as anthropic.evaluationModel), so every aieo provider works as a fallback.

• Dependencies: adds @ai-sdk/typesafe-ai and @ai-sdk/provider-utils, and bumps ai to 7.0.106 and @ai-sdk/anthropic to 4.0.57 so provider-utils dedupes.

• deriveNodeName moves from three graph steps into _shared.ts, since the walker is a fourth user.

• plans/graph-walk.md records the design.

Verification

• tsc --noEmit is clean.
• npm test: 832 pass. New tests:
  • src/evaluate.test.ts runs the real experimental_evaluate over a fake jev-shaped evaluation model and over a wrapped fake language model, and covers the resolver's routing.
  • src/steps/lib/graph/walk.test.ts walks an in-memory graph with a scripted decider.
• test:graph includes a live case that walks a seeded Neo4j graph through the real reader with a scripted decider.
• One live experimental_evaluate call through the fallback path (haiku) returned sensible relevance and next choices in about 1.4 s.

Not in this PR

• jev hasn't been called live yet (no TYPESAFE_AI_API_KEY in the build env), and no full walk has run against a real model. The three question instructions will want tuning on a first real walk.

Example:

- id: gather
  type: graph/walk
  config:
    goal: "Why did the nightly deliver workflow start failing?"
    query: "nightly deliver"
    model: jev
- id: answer
  type: llm
  config:
    prompt: "Context:\n{{ gather.nodes }}\n\nQuestion: {{ gather.goal }}"