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 5, 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 5, 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.0.tar.gz (826.4 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.0-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.0-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.0.tar.gz.

File metadata

  • Download URL: somatize-0.5.0.tar.gz
  • Upload date:
  • Size: 826.4 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.0.tar.gz
Algorithm Hash digest
SHA256 b06dcd8fa8b70ce9be474abee22d8ffb127d5f07e1cbe4dcaaa5626dc2a9324b
MD5 eddebe8199a98ecbd2d08d76d62bdaab
BLAKE2b-256 c8b8c0dbb082dd509a6635bfcb5383f314924d035e885274a4da10f4e65d633b

See more details on using hashes here.

Provenance

The following attestation bundles were made for somatize-0.5.0.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.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for somatize-0.5.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 391e982b90c86b18b1af937b3d103f637f530949ffc058367d98818e84aac031
MD5 ef3b384862e08b2161143caa78d760b9
BLAKE2b-256 ec7857cbb8708bf866243762ff822ddfd4191b8ccb1d59b7ed3d4fad04e95a44

See more details on using hashes here.

Provenance

The following attestation bundles were made for somatize-0.5.0-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.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for somatize-0.5.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 0bba0e0957196056f4bd5d0b05bec879ef138de637fd68e05d46692e73a0b7a1
MD5 01ca29dac45141c69f41ab818a82d71a
BLAKE2b-256 5c173625f3f1d92161b0939adb6d1881dbee25fbd69c9ca764b193adf07de66b

See more details on using hashes here.

Provenance

The following attestation bundles were made for somatize-0.5.0-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

0.5.1

3 files

This release

0.5.0 This release

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