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:
- Your first s0ma project — an empty directory to a built, inspectable project.
- Your first module — the anatomy of a
.s0mafile, one declaration at a time. - When s0ma refuses, and how to get back to green — what each refusal means and what to do about it.
- Concepts index and the glossary — every term the documentation uses.
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.