somatize_core/
lib.rs

1// The crate is fully documented and clippy runs with -D warnings in CI,
2// so this makes "public API without docs" a build error from here on.
3#![warn(missing_docs)]
4
5//! Core types and traits for the Soma computational graph runtime.
6//!
7//! A graph holds two kinds of node, and this crate defines both sides of
8//! that split. A [`Filter`] *computes* — deterministic, content-cacheable,
9//! `fit`/`forward`. A [`Step`] *decides* — it polls, asks the
10//! runtime to perform [`Effect`]s (a model, a tool, another
11//! graph), and returns a [`Transition`]. One
12//! [`NodeMeta`](node::NodeMeta) describes either kind; one
13//! [`NodeOutcome`](node::NodeOutcome) says how either kind finished.
14//! Everything downstream reads the metadata, never the kind.
15//!
16//! The contracts every other crate depends on:
17//! - [`Filter`] — the computation unit (fit/forward)
18//! - [`Step`] / [`Effect`] — the decision unit
19//!   and what it asks for; effects are journaled, filters are cached
20//! - [`Value`] — typed data flowing between nodes (Tensor, JSON, Bytes)
21//! - [`Graph`] — DAG of nodes and edges, computational and effectful alike
22//! - [`CacheKey`] / [`CacheStore`] — content-addressable caching
23//! - [`DataStore`] — abstraction for moving data between workers
24//! - [`Schema`] — dtype + shape for compile-time validation, on every edge
25//! - [`Event`] — runtime lifecycle events
26
27pub mod action;
28pub mod any;
29pub mod cache;
30pub mod canon;
31pub mod codec;
32pub mod control;
33pub mod effect;
34pub mod error;
35pub mod event;
36pub mod filter;
37pub mod fingerprint;
38pub mod graph;
39pub mod keys;
40pub mod message;
41pub mod node;
42pub mod schema;
43pub mod search;
44pub mod state;
45pub mod step;
46pub mod store;
47pub mod strategy;
48pub mod study;
49pub mod summary;
50pub mod svg;
51pub mod tool;
52pub mod tracking;
53pub mod util;
54pub mod value;
55pub mod virtual_value;
56pub mod viz;
57
58// Re-export core types for convenience.
59pub use cache::{CacheKey, CacheStore, CacheTier, EntryMeta, Origin};
60pub use control::{LoopCondition, LoopSignal, read_arm_selector, read_loop_signal};
61pub use effect::{
62    Effect, EffectResult, GraphEffectMode, JoinPolicy, LlmRequest, LlmResponse, NodeSpec,
63    StopReason, SuspendReason, ToolSpec, Usage,
64};
65pub use error::{Result, SomaError};
66pub use event::{Event, MetricRecord, PlanSummary, RunId, StudyId, TrialId};
67pub use filter::{Distribution, Filter, FilterKind, FilterMeta, RemoteTarget, StreamMode};
68pub use fingerprint::{ArchitectureFingerprint, EdgeRef, pipeline_summary, structural_similarity};
69pub use graph::{Edge, EdgeKind, Graph, Node, NodeId};
70pub use message::{ContentBlock, Message, Messages, Role};
71pub use schema::{DataType, Dimension, Schema};
72pub use search::{Scale, SearchDimension, SearchSpace, Searchable};
73pub use state::{MemoryStateStore, StateStore};
74pub use step::{Step, StepCtx, StepMeta, Transition};
75pub use store::{
76    DataRef, DataStore, LocalDataStore, StorageConfig, StoreMeta, StreamFormat, slice_tensor_rows,
77};
78pub use strategy::{
79    ClientSelection, CommunicationProtocol, ExploitStrategy, ExploreStrategy, FederatedAggregation,
80    GradientAggregation, Partition, TrainingStrategy,
81};
82pub use study::{
83    CompositeObjective, Direction, Objective, PruningStrategy, Scalarizer, SearchStrategy, Study,
84    Trial, TrialState,
85};
86pub use summary::{
87    FlagCount, NodeCost, RunConclusion, RunOutcome, RunSummary, TrialSummary, human_duration,
88};
89pub use tracking::{
90    EventEnvelope, EventSink, GitInfo, GraphSummaryInfo, RUN_SCHEMA_VERSION, RunKind, RunManifest,
91    RunState, RunStatus, Tracker,
92};
93pub use value::Value;
94pub use virtual_value::{ValueStatus, VirtualValue};
95pub use viz::{GraphOverlay, NodeOverlay, NodeStatus};
96
97// Re-export derive macro
98pub use somatize_macros::{SomaFilter, SomaStep};
somatize_core/lib.rs

somatize_core/
lib.rs
