Crate somatize_runtime 

Execution engine for Soma computational graphs.

Two decisions shape this crate. NodeCatalog is THE registry — every node, filter or step, plus the trained states; the compiler and the executor read the same value, which is what keeps “what compiles” and “what runs” from drifting apart. And run_node (in executor) is the one execution site: input resolution, the output cache, panic containment and the start/complete/fail events happen once, for both kinds — whether a node is cacheable is data on its NodeMeta, not a branch on its kind.

The pieces:

• runner — trait-based execution: LocalRunner, StudyRunner, PbtRunner
• executor — walks ExecutionPlan trees (sequence, parallel, step, loop, remote)
• GraphSession — the primary orchestrator: Graph + catalog → compile → execute; give it an EffectDriver via with_driver and it drives steps too
• effects — EffectDriver performs what steps ask for; EffectJournal records once and replays on resume; GraphHandler runs a pipeline on an agent’s behalf
• cache — LRU memory cache, local disk cache, tiered cache
• sampler — hyperparameter samplers (Grid, Random, Bayesian/TPE)
• pruner — early stopping strategies (Median, Percentile)
• tracking — local run directories: JSONL event sink, LocalTracker

Re-exports

pub use cache::LocalCache;

pub use cache::MemoryCache;

pub use cache::TieredCache;

pub use effects::EffectDriver;

pub use effects::EffectJournal;

pub use effects::EffectSite;

pub use event_bus::EventBus;

pub use executor::Context;

pub use executor::GraphInfo;

pub use executor::execute;

pub use executors::FnPbtExecutor;

pub use executors::FnTrialExecutor;

pub use executors::PbtConfig;

pub use executors::PbtExecutor;

pub use executors::PbtRunner;

pub use executors::PopulationMember;

pub use executors::StreamOutput;

pub use executors::StreamRun;

pub use executors::StudyRunner;

pub use executors::TrialContext;

pub use executors::TrialExecutor;

pub use executors::TrialOutcome;

pub use forward::Batched;

pub use forward::ForwardStrategy;

pub use forward::Standard;

pub use forward::Stream;

pub use graph_session::GraphSession;

pub use graph_session::graph_fit;

pub use graph_session::graph_predict;

pub use graph_session::graph_run;

pub use node_catalog::NodeCatalog;

pub use node_catalog::NodeImpl;

pub use pruner::MedianPruner;

pub use pruner::PercentilePruner;

pub use pruner::Pruner;

pub use runner::LocalRunner;

pub use runner::RemoteRunner;

pub use runner::Runner;

pub use runner::Transport;

pub use sampler::BayesianSampler;

pub use sampler::GridSampler;

pub use sampler::RandomSampler;

pub use sampler::Sampler;

pub use study_io::StudyIo;

pub use tracking::JsonlEventSink;

pub use tracking::LocalTracker;

pub use tracking::RunInfo;

pub use tracking::RunReader;

pub use tracking::collect_git_info;

pub use tracking::list_runs;

pub use tracking::load_manifest;

pub use tracking::load_status;

Modules

cache

Cache implementations for the Soma runtime.

effects

Running effectful steps.

event_bus

Broadcast event bus for runtime observability.

executor

Plan executor — walks [ExecutionPlan] trees and runs filter nodes.

executors

Executors — high-level execution loops that USE a Runner.

forward

Forward execution strategies for crate::GraphSession.

graph_session

Graph session — the primary orchestrator for Graph → Compile → Execute.

node_catalog

One registry for every node in a graph — implementations, metadata, and trained states.

pruner

Early stopping strategies for optimization studies.

runner

Runner module — trait-based execution contracts.

sampler

Hyperparameter samplers for optimization studies.

strategy

Running a [TrainingStrategy].

study_io

Reading and writing a [Study] to disk.

tracking

File-based tracking backend: run directories under .soma/runs/.

Enums

NodeOutcome

How a node finished.

Traits

EffectHandler

Performs one kind of effect.