Struct NodeCatalog 

pub struct NodeCatalog { /* private fields */ }

Every node a graph can execute, plus the states its filters have learned.

let mut lib = NodeCatalog::new();
lib.register("scaler", Box::new(MyScaler { scale: 2.0 }));
lib.register_step("researcher", Box::new(ReactStep::new("claude-opus-5")));

// Use as compiler registry
let result = somatize_compiler::compile(&graph, &lib, mode, cache)?;

// Use directly with executor — no conversion needed
executor::execute(&plan, &mut ctx, &lib, &cache)?;

Cloning shares both the nodes and the state store, so a clone sees whatever the original has fitted. That is what lets one catalog serve many graph runs — an agent running pipelines back to back, for instance.

Implementations

impl NodeCatalog

pub fn new() -> Self

Create a new catalog with an in-memory state store.

pub fn with_state_store(states: Arc<dyn StateStore>) -> Self

Create a catalog with a custom [StateStore] backend.

pub fn register(&mut self, node_id: impl Into<String>, filter: Box<dyn Filter>)

Register a filter for a given node ID.

pub fn register_step(&mut self, node_id: impl Into<String>, step: Box<dyn Step>)

Register a step for a given node ID.

pub fn register_step_arc( &mut self, node_id: impl Into<String>, step: Arc<dyn Step>, )

Register an already-shared step, for callers that built one elsewhere (the Python bindings do).

pub fn len(&self) -> usize

Number of registered nodes, of either kind.

pub fn is_empty(&self) -> bool

Whether the catalog is empty.

pub fn node(&self, node_id: &str) -> Option<&NodeImpl>

What sits behind a node id.

pub fn node_meta(&self, node_id: &str) -> Option<NodeMeta>

A node’s contract, whichever kind it is.

pub fn get(&self, node_id: &str) -> Option<Arc<dyn Filter>>

Get a filter by node ID. None if the id is a step, or unknown.

pub fn step(&self, node_id: &str) -> Option<Arc<dyn Step>>

Get a step by node ID. None if the id is a filter, or unknown.

pub fn has_steps(&self) -> bool

Does the catalog hold any effectful node at all?

The question a caller asks before building an effect driver, which costs a provider catalog read and a journal directory.

pub fn merge_from(&mut self, other: &NodeCatalog) -> Result<()>

Copy every node of other into this catalog.

Registering the same id twice with the same configuration is a no-op; the same id behind a different configuration is an error, because whichever one lost would silently answer for the other’s cache entries. States are not merged — they follow this catalog’s store.

pub fn node_ids(&self) -> Vec<&str>

Registered node ids, sorted, so listings are stable.

pub fn try_set_state( &self, node_id: impl Into<String>, state: Value, ) -> Result<()>

Store a trained state for a node.

Errors bubble up from the underlying [StateStore] (e.g. I/O on a disk-backed backend). The in-memory default never fails.

pub fn get_state(&self, node_id: &str) -> Option<Arc<Value>>

Retrieve the trained state for a node. The returned Arc<Value> can be dereferenced (&*arc) for the forward hot path without cloning the underlying value.

pub fn clear_states(&self)

Drop all stored states (but keep the nodes).

pub fn state_store(&self) -> &Arc<dyn StateStore>

Access the underlying [StateStore] (e.g. to share it across sessions or inspect its contents).

Trait Implementations

impl Clone for NodeCatalog

fn clone(&self) -> NodeCatalog

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for NodeCatalog

fn default() -> Self

Returns the “default value” for a type.

impl NodeRegistry for NodeCatalog

Implements [NodeRegistry] so the compiler can read metadata directly from the registered implementations — filters and steps.

This is what closed the hole where a caller passing the filter half alone got the graph compiled with every step edge unchecked.

fn node_meta(&self, node_id: &str) -> Option<NodeMeta>

A node’s contract — schemas, cacheability, effectfulness — whichever kind it is. None means the graph names a node nobody registered, which the compiler reports rather than guesses around.

fn config_hash(&self, node_id: &str) -> Option<CacheKey>

The node’s configuration identity, folded into cache keys. Required rather than derived because only the registry knows how a node’s configuration is canonicalized (Rust: canonical CBOR of fields; Python: qualname + config + source hash).

fn meta(&self, node_id: &str) -> Option<FilterMeta>

The computational view, for the phases that only make sense for a filter: gradient flow, differentiable collapsing.