soma

Why agents should use Soma

What agents struggle with today

An agent building a web app in Express needs to coordinate: a JS file, a package.json, npm install, a database connection string, SQL migrations, route configuration, JSON parsing middleware, and error handling. That's 7 files, 3 languages, and 4 tools — any of which can be inconsistent.

In Soma, the agent writes one file. Memory properties declare the database. Signal handlers are the routes. The compiler verifies consistency. soma serve runs it.

Install

macOS

curl -fsSL https://soma-lang.dev/install.sh | sh
# or
brew install soma

Linux

curl -fsSL https://soma-lang.dev/install.sh | sh

From source

git clone https://github.com/soma-dev-lang/soma
cd soma/compiler
cargo build --release
cp target/release/soma /usr/local/bin/

Verify

soma --version
soma 0.1.0

Syntax reference

Soma has one structure: the cell. Every cell has a face (contract), memory (state), and signal handlers (behavior).

Cell

cell Counter {
    face {
        signal increment(amount: Int)
        signal get() -> Int
        promise value >= 0
    }

    memory {
        value: Int [persistent, consistent]
    }

    on increment(amount: Int) {
        let current = value.get("count") ?? 0
        value.set("count", current + amount)
        return current + amount
    }

    on get() {
        return value.get("count") ?? 0
    }
}

Types

Variables

let x = 42
x = x + 1                      // reassignment
let name = "world"
let greeting = "hello {name}"   // string interpolation
let user = map("name", "Alice", "age", 30)
let info = "{user.name} is {user.age}"  // field interpolation

Control flow

if x > 10 {
    return "big"
} else {
    return "small"
}

while i < n {
    sum += i
    i = i + 1
}

for item in items {
    print(item)
}

Operators

Memory properties

memory {
    data:     Map<String, String> [persistent, consistent]     // → SQLite
    cache:    Map<String, String> [ephemeral, local]          // → in-memory HashMap
    secrets:  Map<String, String> [persistent, encrypted]     // → encrypted at rest
    logs:     Log<String>         [persistent, immutable]     // → append-only
    sessions: Map<String, String> [ephemeral, ttl(30min)]    // → auto-expire
}

The compiler verifies: [persistent, ephemeral] → error (contradiction). [immutable] → implies consistent. [retain(7years), ttl(30d)] → error (ttl < retain).

Imports

use lib::helpers            // local: lib/helpers.cell
use math                    // package: .soma_env/packages/math/
use std::builtins           // stdlib

State machines

state status {
    initial: draft

    draft -> submitted
    submitted -> approved
    approved -> shipped
    shipped -> delivered
    * -> cancelled              // from any state
}

// Runtime enforces valid transitions
transition(order_id, "submitted")   // ✓ draft → submitted
transition(order_id, "shipped")     // ✗ error: draft → shipped not allowed

Tests

cell test MathTests {
    rules {
        assert square(5) == 25
        assert factorial(10) == 3628800
    }
}

// $ soma test tests.cell
//   ✓ assert square(5) == 25
//   ✓ assert factorial(10) == 3628800
// 2 tests: 2 passed, 0 failed

Typed records

Named maps with compile-time type tags. No more stringly-typed Map<String, String>.

// Create a typed record
let user = User { name: "Alice", age: 30, email: "[email protected]" }

// Field access
user.name              // → "Alice"
user._type             // → "User"

// Type checking at runtime
is_type(user, "User")  // → true
is_type(user, "Order") // → false

// Records compose with pipes and with()
let updated = user |> with("age", 31)
let clean = user |> without("email")

// Use in collections
let users = list(
    User { name: "Alice", role: "admin" },
    User { name: "Bob", role: "user" }
)
let admins = users |> filter_by("role", "=", "admin")

Error handling

try { } catches runtime errors and returns them as values. No exceptions, no panics — errors are data.

// try wraps errors into a map with value/error fields
let result = try { stock(ticker) }

if result.error != () {
    // Error occurred — handle it
    return response(404, map("error", result.error))
}

// Success — use the value
let data = result.value

// Works with any expression
let safe_divide = try { a / b }
let answer = safe_divide.value ?? 0  // default to 0 on error

HTML templates

Separate HTML from logic. Load external files with variable substitution.

// templates/page.html:
// <h1>{title}</h1>
// <ul>{items}</ul>
// <p>By {author}</p>

// Load and render with variables
let page = load_template("templates/page.html",
    "title", "Dashboard",
    "items", rows,
    "author", "Soma"
)
return html(page)

Data pipelines

Soma replaces PySpark for in-memory data processing. Same operations, fraction of the code.

Filter → Sort → Top

let portfolio = stocks
    |> filter_by("market_cap", ">", 20000)
    |> filter_by("momentum", ">", -10)
    |> sort_by("composite", "desc")
    |> top(10)

Join → Aggregate (GROUP BY)

let by_sector = trades
    |> join(prices, "ticker")
    |> filter_by("volume", ">", 1000)
    |> agg("sector", "volume:sum", "price:avg")
    |> sort_by("volume_sum", "desc")

All pipeline operations

Web applications

Signal handlers become HTTP routes automatically. soma serve gives you a threaded HTTP server with SQLite, CORS, HTMX, static files, and hot reload.

JSON API

cell API {
    memory { items: Map<String, String> [persistent, consistent] }

    on create(data: Map<String, String>) {
        let id = next_id()
        items.set(to_string(id), to_json(data))
        return data |> with("id", id)
    }

    on get(id: String) {
        let raw = items.get(id)
        if raw == () { return response(404, map("error", "not found")) }
        return from_json(raw)
    }

    on list() {
        let items = list()
        for key in items.keys() { items = list(items, from_json(items.get(key))) }
        return items
    }
}

// $ soma serve api.cell
// POST /create  →  create({"name":"Alice"})
// GET  /get/1   →  get("1")
// GET  /list    →  list()

HTML + HTMX

on page() {
    return html("<div hx-get='/items' hx-trigger='load'></div>")
}

on items() {
    let rows = ""
    for item in data.keys() {
        let name = data.get(item)
        rows += "<li>{name}</li>"
    }
    return html("<ul>{rows}</ul>")
}

Response control

response(404, map("error", "not found"))    // status code
html("<h1>Hello</h1>")                          // text/html
redirect("/")                                    // 302 redirect

Serve options

soma serve app.cell                # HTTP server on :8080
soma serve app.cell -p 3000       # custom port
soma serve app.cell --watch        # hot reload on file change

CLI reference

All builtins

Meta-cells (self-growing)

// Define a custom property
cell property geo_replicated {
    face { promise "data replicated across regions" }
    rules {
        implies [persistent, consistent]
        contradicts [ephemeral, local]
    }
}

// Define a custom checker
cell checker auth_required {
    face { promise "every cell with signals must have auth" }
    rules { check { require has_auth else MissingAuth } }
}

// Define a custom backend
cell backend redis {
    rules {
        matches [ephemeral, ttl]
        native "redis"
    }
}

Architecture

Source (.cell)
    │
    ├──→ Lexer → Parser → AST
    │         │
    │         ├──→ Checker (properties, signals, promises)
    │         │
    │         ├──→ Tree-walking Interpreter (soma run)
    │         │
    │         ├──→ Bytecode Compiler → VM (soma run --jit, 2.7x faster)
    │         │
    │         └──→ Rust Codegen (soma build)
    │
    ├──→ Registry (loads stdlib/*.cell — properties, backends, builtins)
    │
    └──→ Runtime
           ├── SQLite backend ([persistent])
           ├── Memory backend ([ephemeral])
           ├── HTTP server (soma serve)
           └── Bytecode cache (.soma_cache/)