somatize-runtime 0.5.0

Execution engine for the Soma computational graph runtime
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

// The crate is fully documented and clippy runs with -D warnings in CI,
// so this makes "public API without docs" a build error from here on.
#![warn(missing_docs)]

//! 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`](somatize_core::node::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`](effects::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

pub mod cache;
pub mod effects;
pub mod event_bus;
pub mod executor;
pub mod executors;
pub mod forward;
pub mod graph_session;
pub mod node_catalog;
pub mod pruner;
pub mod runner;
pub mod sampler;
pub mod strategy;
pub mod study_io;
pub mod tracking;

pub use cache::{LocalCache, MemoryCache, TieredCache};
pub use effects::{EffectDriver, EffectHandler, EffectJournal, EffectSite, NodeOutcome};
pub use event_bus::EventBus;
pub use executor::{Context, GraphInfo, execute};
pub use executors::{
    FnPbtExecutor, FnTrialExecutor, PbtConfig, PbtExecutor, PbtRunner, PopulationMember,
    StreamOutput, StreamRun, StudyRunner, TrialContext, TrialExecutor, TrialOutcome,
};
pub use forward::{Batched, ForwardStrategy, Standard, Stream};
pub use graph_session::{GraphSession, graph_fit, graph_predict, graph_run};
pub use node_catalog::{NodeCatalog, NodeImpl};
pub use pruner::{MedianPruner, PercentilePruner, Pruner};
pub use runner::{LocalRunner, RemoteRunner, Runner, Transport};
pub use sampler::{BayesianSampler, GridSampler, RandomSampler, Sampler};
pub use study_io::StudyIo;
pub use tracking::{
    JsonlEventSink, LocalTracker, RunInfo, RunReader, collect_git_info, list_runs, load_manifest,
    load_status,
};