# Structure Decoder for the Geometric Graph Transformer
## Current state
The `corpus_native_graph_*` examples already implement the four phases of a
non-classical transformer:
| **Encode** | `corpus_native_graph_wsd.rs` | Input tokens → sense-node selection via context centroid. |
| **Process** | `corpus_native_graph_walk.rs` | Geometric walk using spatial proximity, velocity, sequential bias, edge weights, A* planning. |
| **Decode** | `corpus_native_graph_walk.rs` | Node IDs → token IDs (`id / 1000`) → words via `vocab.json`. |
| **Learn / Goal** | `corpus_native_graph_goal.rs` | GOAL region drives traversal; Hebbian reinforcement + edge decay. |
This proves the graph topology itself can act as the model. The next step is to
turn the flat-token decoder into a **structure decoder** that can emit typed
outputs, starting with tool calls.
---
## Architecture: from flat tokens to structured output
### 1. Tool schema subgraphs
A tool is not a string; it is a small subgraph inside the larger geometric graph.
- **Anchor node**: a sense-node whose base token is the tool name (e.g.
`get_exchange_rate`). The anchor is placed in the `tool` domain region during
graph construction.
- **Argument branch nodes**: sense-nodes for argument names (`base_currency`,
`target_currency`) linked to the anchor with high PMI edges.
- **Type / constraint edges**: optional edges that encode value type, required
vs optional, or valid enum choices.
The schemas can be bootstrapped from tool-use datasets such as
`glaiveai/glaive-function-calling-v2`. The `system` column already contains JSON
function schemas; we parse them and inject subgraph anchors/edges during or
after graph construction.
### 2. Region detection
During inference the walker continuously scores whether it has entered a tool
region:
```text
region_score = proximity_to_tool_anchor + domain_label("tool") + sequential_bias
```
When `region_score` exceeds a threshold and stays high for several steps, the
walker switches from **text generation mode** to **tool call generation mode**.
### 3. Structured emission
Inside a tool region the walker is constrained to visit only nodes that belong
to that tool's subgraph:
1. Emit tool `name` from the anchor node.
2. Visit required argument nodes in order.
3. For each argument, decode the value from the most recent input context or
from generated tokens.
4. Assemble `{"name": "...", "arguments": {"...": "..."}}`.
The decoder returns a structured result enum:
```rust
enum DecoderOutput {
Text(String),
ToolCall { name: String, arguments: serde_json::Value },
}
```
### 4. Validation and learning
- Validate emitted JSON against the original tool schema.
- Success: reinforce all traversed edges.
- Failure / hallucinated argument: weaken the offending edges.
- This replaces backprop with a graph-rewiring reward signal, consistent with
the existing `corpus_native_graph_goal.rs` learner.
---
## Immediate improvement: a reusable Rust walker (option 3)
Before building tool subgraphs, the base walker should become a reusable,
testable library component instead of example-only code.
### Goals
1. Move walker logic from `examples/corpus_native_graph_walk.rs` into
`src/corpus/inference.rs`.
2. Add **beam search / top-k decoding**: keep `K` concurrent trajectories and
pick the highest-scoring final sequence.
3. Improve **context encoding**: maintain a sliding-window context centroid
over recent selected sense-nodes, not just the immediate position.
4. Make scoring pluggable: spatial proximity, velocity alignment, sequential
bias, edge weight, repetition penalty, plan bonus.
5. Provide a clean API:
```rust
pub struct GeometricWalker {
candidates: usize,
temperature: f32,
momentum: f32,
step_size: f32,
repetition_penalty: f32,
recent_window: usize,
}
impl GeometricWalker {
pub fn new(config: WalkerConfig) -> Self;
pub fn walk(&mut self, graph: &[GraphNode4D], start: usize, steps: usize) -> Vec<u64>;
pub fn walk_beam(&self, graph: &[GraphNode4D], start: usize, steps: usize, beam_width: usize) -> Vec<Vec<u64>>;
}
```
### Acceptance criteria
- `cargo check --all-targets` clean.
- Unit tests for scoring, beam search, and context centroid.
- Pre-commit scan clean.
- Example `corpus_native_graph_walk.rs` rewritten to use the library walker.
---
## Phased plan
| 1 | Document architecture (this page) + kanban tasks | Wiki page, atheneum tasks |
| 2 | Extract reusable walker to `src/corpus/inference.rs` | Library module + unit tests |
| 3 | Add beam search / top-k | `walk_beam`, tests, example update |
| 4 | Improve context encoding | Sliding centroid, better start-node encoding |
| 5 | Tool subgraph construction | Parse Glaive schemas, inject anchors/edges |
| 6 | Structure decoder | `DecoderOutput` enum, region detection, JSON emission, validation |
| 7 | End-to-end tool-calling demo | CLI that takes a prompt + tool schemas and emits a call |
---
## Relation to prior work
- `corpus_native_graph_goal.rs` proved goal-directed walking and Hebbian
learning work on small graphs.
- The multi-domain graph (`code`, `math`, `tool`) now gives the walker access to
a real tool region.
- The structure decoder is the natural next layer: it turns the walker from a
text generator into a reasoning engine that can choose when to call tools.