Skip to content

README.md

Latest commit

 

History

History
151 lines (131 loc) · 6.95 KB

README.md

File metadata and controls

151 lines (131 loc) · 6.95 KB
Raw

Graph Module Specification

The graph module is TinyAgents' workflow runtime. It owns topology, state transition semantics, routing, execution history, checkpointing, interrupts, streaming, parallel execution, subgraph invocation, sub-agent nodes, recursive calls, and graph-level observability.

The graph module must be usable without the expressive language. The expressive language compiles into graph structures; the graph runtime must not know or care where a graph came from.

The current implementation in src/graph.rs is a milestone-1 scaffold: closure-backed nodes, whole-state node outputs, direct and conditional edges, sequential execution, and a recursion limit. The feature specifications below describe the target contract that the scaffold should grow into.

Source Inspiration

Primary references:

Useful upstream code references:

  • libs/langgraph/langgraph/graph/state.py: StateGraph, channels, conditional edges, compile-time validation, node defaults, and subgraph attachment.
  • libs/langgraph/langgraph/pregel/main.py: executable graph runtime, superstep loop, streaming, state update APIs, durability, recursion errors, and subgraph stream propagation.
  • libs/langgraph/langgraph/types.py: Command, Send, Interrupt, StateSnapshot, stream part types, retry/cache/timeout policy, and durability modes.
  • libs/langgraph/langgraph/channels/: reducer/channel implementations such as last-value, binary operator aggregate, topic, ephemeral, named barrier, and delta channels.
  • libs/checkpoint/langgraph/checkpoint/base/__init__.py: checkpoint tuple, pending writes, thread operations, copy/prune semantics, and delta-channel history.

Rust-specific precedent:

  • rust-langgraph is useful as a small Rust-native reference for stateful LLM workflows with nodes, conditional edges, checkpoints, streaming, optional model adapters, and ReAct/tool helpers.
  • OpenHuman PR #4261 is useful as a product reference for keeping a generic graph engine independent from the agent harness while exposing checkpoints, HITL, observability events, blueprints, and RPC run control.
  • TinyAgents should preserve the ergonomic Rust builder surface from these precedents, but the target graph runtime must also be rich enough to be generated from .rag, inspected by UIs, driven from .ragsh, and tested with deterministic state/channel snapshots.

Design Stance

The graph module is the stable execution contract below all graph authoring surfaces. A graph may be built by Rust code, loaded from a .rag blueprint, compiled from a REPL cell, generated by an agent, or restored from a registry record. Once compiled, those origins must converge on the same immutable CompiledGraph behavior:

  • topology is validated before execution
  • node capabilities are resolved through registries
  • state writes pass through channel reducers
  • commands and Send packets are explicit runtime values
  • checkpoints and pending writes are owned by the graph runtime
  • nested graph, sub-agent, and REPL calls preserve run hierarchy
  • events contain enough source/origin metadata to explain generated graphs

Agent-authored graph definitions are allowed only as source for the expressive language compiler. The graph runtime must not accept unchecked model-generated topology or executable code.

Responsibilities

  • Build named node graphs with direct, conditional, barrier, and command-based routing.
  • Validate topology before execution and freeze it into an immutable compiled graph.
  • Execute async nodes under graph and node policies.
  • Apply partial state updates through typed channel/reducer policies.
  • Execute multiple active nodes in a superstep.
  • Support dynamic fanout through Send-style packets.
  • Enforce recursion, step, timeout, concurrency, retry, and cache policy.
  • Persist checkpoints, pending writes, task outcomes, and interrupt state at execution boundaries.
  • Support human-in-the-loop interrupts and resumable commands.
  • Support manual state inspection, state history, state update, forks, and time travel when checkpointing is enabled.
  • Support targeted steering of parent orchestrator runs, child sub-agent runs, graph tasks, and pending interrupts through policy-checked commands.
  • Emit typed graph, task, checkpoint, interrupt, and streamed-output events.
  • Represent subgraphs as executable nodes with namespaced checkpoints and nested streams.
  • Represent harness sub-agents as graph nodes with child run identity.
  • Export graph structure for visualization, tests, and generated docs.

Non-Responsibilities

  • It does not own chat model provider logic.
  • It does not own tool schema validation or tool dispatch.
  • It does not implement prompt templating.
  • It does not manage long-term application memory.
  • It does not own model/tool usage accounting, though it must forward and roll up child events from harness nodes.
  • It does not parse the expressive language.

Feature Specifications