Skip to main content

s0ma-lang-dsl

The transpiler toolchain for the s0ma DSL — a domain-specific language whose grammar enforces, at parse time, what the s0ma framework enforces at runtime: every component is declared, described, dependency-resolved, and registered in the self-model. It also ships the s0ma command line, which is how a person drives the whole toolchain.

.s0ma source files become plain Python decorated with the framework's @component annotations, plus a normalised .s0ma.json IR for tooling and agents and a .s0ma.map source map for debugging. Authored documentation is part of the same surface — doc-ref, doc-guide, and example declarations make documentation a registered, validated, drift-checked artifact rather than a parallel hand-written one.

Where it sits

Four distributions ship together at one version, and dependencies only ever point down the stack (PRD INV-6):

s0ma-lang-mcp · s0ma-lang-studi0 → s0ma-lang-dsl → s0ma-lang-core

The two packages above are optional companions: s0ma-lang-mcp is the authoring server coding agents drive, and s0ma-lang-studi0 is the local viewer s0ma studi0 <project> opens on a built project's graph. This CLI defers importing each and prints an install hint when it is absent, so neither is required to use the DSL. Below it, s0ma-lang-core and lark are the only external runtime dependencies.

s0ma-lang-dsl is Apache-2.0, and so are s0ma-lang-core, s0ma-lang-mcp and s0ma-lang-studi0. What each distribution contains, and the license each one declares, is in the distributions s0ma ships.

Install

s0ma is on PyPI:

pip install s0ma-lang-dsl

That brings s0ma-lang-core with it and installs the s0ma command. In a uv project, uv add s0ma-lang-core s0ma-lang-dsl names both in the project's dependencies. The package is named s0ma-lang-dsl and imported as s0ma_dsl. The other ways in, working inside a checkout or building the wheels yourself, are in the root README's "Install" section, and getting started is the journey to walk once the s0ma command runs.

Then give your project a [tool.s0ma] table in its pyproject.toml — or start fresh with s0ma new project <dir>, which writes it for you. Without the table the CLI runs in legacy mode with a one-line warning per invocation.

What it feels like

s0ma new project my-app   # writes [tool.s0ma], scaffolds a module, runs the first build
s0ma check --mode release # validate without emitting; `--mode` selects authoring strictness
s0ma build .              # emit Python, IR, source maps, docs, and the build manifest
s0ma inspect --all        # one row per module, straight out of the self-model
s0ma doctor               # environment and project health; diagnoses, does not gate

Release evidence is a pair, and neither half alone is a release claim: s0ma score --gate-mode release --gate is the caller-pinned static gate, and s0ma verify-host --gate-mode release --python .venv/bin/python proves the imports in the application's own Python. Host verification imports trusted application code without a sandbox, so it is a separate, explicit step.

Every command the CLI serves, with what each one touches, is in the s0ma command line. Every [tool.s0ma] setting is in project settings, and every diagnostic the toolchain can report is in reports s0ma can make — all three generated from the code that serves them.

The language

The language spec is versioned separately from the distributions; the current one is docs/s0ma-dsl-spec-v0.17.0.md, and it is the authority on what a .s0ma file may say. Everything below is a way in, not a second authority:

Doc Audience Purpose
Language specification Implementers, reviewers Normative language authority
Survival card Coding agents Under 4 KB: the bootstrap loop, the body rules, one minimal valid module — read first
Quick reference Coding agents, people Every kind of declaration and every line each may carry, generated from the language itself — look topics up rather than reading it whole
Agent system prompt LLMs Copy-paste prompt for .s0ma authoring
Patterns guide Authors SERVICE / EXCEPTION / ADAPTER idioms for real applications
Migration guide Adopters Convert existing Python to .s0ma; migrate hand-written docs into the subsystem
Documentation subsystem Doc authors doc-ref / doc-guide / example reference
Coding agent handbook Transpiler contributors Architecture and conventions of this package
Spec traceability All Rule-to-implementation matrix
ADRs All The decisions this package holds itself to

Documentation

The map of record lists every document this repository keeps, what it is for, and which check keeps it honest. Good places to start:

In a terminal, s0ma docs opens the same map and s0ma docs show <topic> answers one question from it.

Releases

The root CHANGELOG.md names the current release and is canonical for all four packages; this package's own CHANGELOG.md holds the pre-monorepo history (last standalone DSL release: v0.16.0, 11 May 2026). All four packages are versioned in lockstep.

License

Apache License 2.0 — see LICENSE for details. The rest of the toolchain shares it: s0ma-lang-core, s0ma-lang-mcp and s0ma-lang-studi0 are Apache-2.0 too, each with its own LICENSE.

Metadata

Release files for s0ma-lang-dsl 0.22.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for s0ma-lang-dsl 0.22.0
File Size Uploaded Provenance Actions
s0ma_lang_dsl-0.22.0.tar.gz 3.1 MB Without provenance Details for s0ma_lang_dsl-0.22.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for s0ma-lang-dsl 0.22.0
File Interpreter ABI Platform Actions
s0ma_lang_dsl-0.22.0-py3-none-any.whl Python 3 none any Details for s0ma_lang_dsl-0.22.0-py3-none-any.whl

Total release size: 4.4 MB

Release files / s0ma_lang_dsl-0.22.0.tar.gz

Download URL s0ma_lang_dsl-0.22.0.tar.gz
Size 3.1 MB
Tags Source
SHA-256 checksum
How to use checksums
6efee75ebdf493ba5143043ea1c376df522584016cb805cb658ebb87f3f86c1b
BLAKE2b-256 checksum
How to use checksums
ce8f5891e99529c29535b0b24f21959daacef8261d7b2310f4db48c5686feaeb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.9.21 {"installer":{"name":"uv","version":"0.9.21","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / s0ma_lang_dsl-0.22.0-py3-none-any.whl

Download URL s0ma_lang_dsl-0.22.0-py3-none-any.whl
Size 1.4 MB
Tags Python 3
SHA-256 checksum
How to use checksums
fe79d9cf9686c21c9054841c9003fa2c79dc79181dc3b54f1d2ed9acc0b184dd
BLAKE2b-256 checksum
How to use checksums
2198aa403c0b1c4fb0f121722c02fcf6038e73aafe76a173d9b7731a89b3e719
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.9.21 {"installer":{"name":"uv","version":"0.9.21","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for s0ma-lang-dsl 0.22.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.22.0 This release

2 release files No provenance

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