Soma

Soma (σῶμα — body) is a computational graph runtime for research pipelines, agent orchestration, and data virtualization. Written in Rust with Python bindings.

Part of the Nous-Soma-Chronos ecosystem:

  • Nous: Understands, reasons — research IDE, agent graphs, automation
  • Soma (this project): Executes, materializes — graphs, optimization, distributed workers
  • ChronosVector: Remembers — temporal vector database

Key Concepts

Concept Description
Filter Data transformation with fit() (learn state) and forward() (transform). Independently cacheable.
Graph Computational DAG of filters. Build with .node()/.connect() or >> / | operators.
Graph.somatize() "You think it. Soma somatizes it." — Materialize a chain/fork topology into an executable graph.
TrainingStrategy Graph-level attribute: Local, DataParallel, ModelParallel, Federated, PopulationBased.
Study Hyperparameter optimization: Grid, Random, or Bayesian (TPE) search with median/percentile pruning.
PBT Population-Based Training: evolutionary train→evaluate→exploit/explore cycles.
Agentic layer soma.Agent, soma.Judge and Python steps (any object with poll(ctx)) are nodes like any filter; a pipeline is a tool an agent can run (soma.agentic.RunGraph) and an agent is a node in a pipeline. Patterns (react, refine, board, …) live in soma.agentic and return ordinary graphs — searchable, cached, tracked.
ExecutionPlan Compiled from graph. Variants: Sequence, Parallel, Execute, Step, Loop, Branch, Remote, Composite, Stream, Empty.
DataStore Abstraction for data movement: Local, S3, Zarr (chunked tensors), Cached, Stream.
Worker Remote execution daemon. Auto-detects hardware, Slurm-style resource limits, token auth.
Coordinator Lightweight gateway: worker registration, routing, health monitoring.

Workspace (10 crates)

soma-macros     → proc macro (#[derive(SomaFilter)])
soma-core       → types + traits: Filter, Value, Graph, TrainingStrategy, Schema, Event
                  DataStore (Local/S3/Zarr), VirtualValue, StreamCache
soma-compiler   → Graph → ExecutionPlan (caching, parallelism, distribution)
                  Scheduler, plan visualization (Mermaid/Graphviz)
soma-runtime    → GraphSession, executor, NodeCatalog (filters AND steps), caches,
                  samplers, pruners, EffectDriver + journal, StudyRunner, PbtRunner,
                  stream executor
soma-memory     → KnowledgeBase trait + MemoryKB + ChronosKB
soma-worker     → Worker, Coordinator, Protocol, EnvManager, token auth
                  Auto-detect capabilities, resource limits, CLI binary
soma-agent      → Research agent loop (observe → hypothesize → experiment → conclude)
soma-mcp        → MCP server (13 tools for code, execution, knowledge)
soma-python     → PyO3 bindings: Graph, Filter, Study, Lab, Chain/Fork operators

Quick Start

# Run all tests (355 Rust + 29 Python)
cargo test --workspace
cd soma-python && maturin develop && pytest tests/ -v

# With S3/Zarr DataStore
cargo test -p soma-core --features s3
cargo test -p soma-core --features zarr

# With ChronosVector
cargo test -p soma-memory --features chronos

# MCP server
cargo run -p soma-mcp -- /path/to/project

Python Usage

from soma import Filter, Graph, Study, search

class Scaler(Filter):
    _differentiable = True

    def fit(self, x, y=None):
        return {"mean": sum(x) / len(x)}

    def forward(self, x, state):
        return [v - state["mean"] for v in x]

class Model(Filter):
    lr: float = search(0.001, 1.0, scale="log")

    def fit(self, x, y=None):
        return {"weights": [0.5] * len(x)}

    def forward(self, x, state):
        return [v * w for v, w in zip(x, state["weights"])]

# Build with >> (chain) and | (fork)
g = Graph.somatize(Scaler() >> Model())
g.fit(train_data)
result = g.forward(test_data)

# Visualize
print(g.to_mermaid())
print(g.to_text())

# Complex topologies
g = Graph.somatize(
    (LoadA() >> NormA() | LoadB() >> NormB())
    >> Aggregate()
    >> Backbone()
    >> (HeadA() | HeadB())
)

# Events
g.on_event(lambda e: print(e["event_type"], e.get("node_id", "")))

# Distributed training
g.set_strategy(DataParallel(num_replicas=4))
g.set_coordinator("http://coord:9090", token="sk-xxx")

Workers

# Start a worker with auto-detected capabilities
soma-worker --port 8080 --tags gpu,training --token sk-xxx

# With resource limits (Slurm-style)
soma-worker --cpus 4 --memory 8G --gpus 1 --max-concurrent 2

# With coordinator auto-registration
soma-worker --coordinator http://coord:9090 --token sk-xxx --tags gpu

Workers auto-detect CPU cores, RAM, GPUs (nvidia-smi), and Python environments. Each worker creates isolated venv/conda environments per job with incremental dependency updates.

Feature Flags

  • soma-core/s3 — S3-compatible DataStore (AWS, Backblaze B2, MinIO)
  • soma-core/zarr — Zarr v3 chunked tensor storage with compression
  • soma-memory/chronos — ChronosVector-backed KnowledgeBase

License

Elastic License 2.0

Project links

Data verified by PyPI on Aug 6, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.0.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for manu.couto1k from gravatar.com manu.couto1k

GitHub Statistics

Data verified by PyPI on Aug 6, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

Elastic-2.0

Requires

Python >=3.9

Provides Extra

dev viz

Tags

graph ml optimization caching agents distributed

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

somatize-0.5.1.tar.gz (829.9 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

somatize-0.5.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (8.4 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64

somatize-0.5.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (8.4 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

File details

Details for the file somatize-0.5.1.tar.gz.

File metadata

  • Download URL: somatize-0.5.1.tar.gz
  • Upload date:
  • Size: 829.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for somatize-0.5.1.tar.gz
Algorithm Hash digest
SHA256 6326620d11ff8ee2939c037f138891e0b9fae4473b91a7f40e9d6842887de4dd
MD5 69b309dc272cb105ca5601e2edbea0ee
BLAKE2b-256 eb1f1a33606aa4dc1d3daf14c0cf4698ee6f994e68ca0d50eb474b4483e0aace

See more details on using hashes here.

Provenance

The following attestation bundles were made for somatize-0.5.1.tar.gz:

Publisher: release.yml on manucouto1/soma

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file somatize-0.5.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for somatize-0.5.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 880b91898272732069ca00b2ba4a1bd3e11645e1f6a29de66401967f5230b7c5
MD5 5b1d09ce00cc97146cc15f2166c37bb0
BLAKE2b-256 a62bdc40b911e5bce41c337242244e73c203500d9af95934b2ec495deccb8824

See more details on using hashes here.

Provenance

The following attestation bundles were made for somatize-0.5.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on manucouto1/soma

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file somatize-0.5.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for somatize-0.5.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 534f94f50bab522079abb7b84a3412c9db577ee86b620bd930135dcea32f234d
MD5 f94a1edfebbde1836f258d17001119fc
BLAKE2b-256 5f5228a2040a3e3067fe730b5fa1a1d71b1e0d0f754c25803c9d5b753f7fb9b4

See more details on using hashes here.

Provenance

The following attestation bundles were made for somatize-0.5.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on manucouto1/soma

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

1.0.1

2 files

1.0.0

2 files

This release

0.5.1 This release

3 files

0.5.0

3 files

0.3.1

3 files

0.2.46

3 files

0.2.45

3 files

0.2.44

3 files

0.2.43

3 files

0.2.41

5 files

0.2.40

5 files

0.2.39

5 files

0.2.38

5 files

0.2.37

5 files

0.2.35

5 files

0.2.34

5 files

0.2.33

5 files

0.2.32

5 files

0.2.31

5 files

0.2.30

5 files

0.2.29

5 files

0.2.28

5 files

0.2.27

5 files

0.2.26

5 files

0.2.25

5 files

0.2.24

5 files

0.2.22

5 files

0.2.21

5 files

0.2.20

5 files

0.2.19

5 files

0.2.18

5 files

0.2.17

5 files

0.2.16

5 files

0.2.15

5 files

0.2.14

5 files

0.2.13

5 files

0.2.12

5 files

0.2.11

5 files

0.2.9

5 files

0.2.5

7 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page