s0ma-lang-core
Software that cannot exist without understanding itself.
s0ma is a Python framework for software self-knowledge — the ability of a software system to maintain an accurate, queryable model of itself: its structure, its runtime state, and the reasoning over that model. Self-knowledge spans three faculties — proprioception (structure), interoception (runtime state), and metacognition (reasoning over the model). Unlike conventional documentation, the self-model is load-bearing: remove it and the system fails to start. Every component must register itself as a condition of existing.
s0ma-lang-core is the runtime foundation the rest of the toolchain stands on: the registry every component registers into, the verification engine that compares that model against the real code, and the surfaces that answer questions from it — Python, an optional REST API, and an optional MCP server an application can offer about itself. It needs none of the other three packages.
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
Core sits at the bottom with no hard runtime dependency on any of them, and it is open: s0ma-lang-core is Apache-2.0, as are s0ma-lang-dsl, 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-core
The package is named s0ma-lang-core and imported as s0ma. Its optional extras are [api] for the REST application, [mcp] for the introspection MCP server, and [all] for both: pip install "s0ma-lang-core[api]". 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 with the s0ma command, which s0ma-lang-dsl adds.
What it feels like
Every component says what it is as a condition of being registered, and the framework can then be asked what exists and whether it is still true:
from s0ma import initialize, verify
from s0ma.decorators import component, internal
from s0ma.types import ComponentKind, Layer
registry = initialize(project_root="./my_project")
@component(
name="TaskService",
kind=ComponentKind.SERVICE,
layer=Layer.APPLICATION,
intent="Manages task lifecycle: creation, assignment, and completion",
dependencies=["StorageAdapter"],
)
class TaskService:
def create_task(self, title: str) -> dict:
return {"title": title, "status": "pending"}
@internal # a private helper, deliberately unregistered
def _validate_title(title: str) -> bool:
return len(title) > 0
print(registry.snapshot().describe()) # what the system says it is
report = verify(registry) # does that match the code?
assert report.passed, report.describe()
verify runs four verifiers and reports structural drift between declarations and source, how much of each declared contract is executable, runtime metrics against declared resource profiles, and dead code. report.explain_for_llm() renders the same findings with fix suggestions.
An application can also carry its own self-knowledge at runtime. After a build, core verifies and loads the emitted self-context without needing the DSL package:
import json
from s0ma.runtime import self_context, self_inspect_adapter
context = self_context("build/build.s0ma.json") # context["card"] is bounded prompt text
adapter = self_inspect_adapter("build/build.s0ma.json")
agent_host.register_tool(
adapter.tool_spec,
lambda query: json.dumps(adapter.handle(query), separators=(",", ":"), sort_keys=True),
)
The adapter answers describe (counts and module names), components <layer or module>, component <name>, dependencies <name>, dependents <name>, impact <name> and source_ir; a name may be a component id, a bare name, or an operation the component provides. Render its answers as compact JSON with sorted keys, as above; the self-prompting guide has the measurements. Authored intent lines are quoted project data, never host instructions (see ADR-002).
Documentation
The map of record lists every document this repository keeps, what it is for, and which check keeps it honest. The pages that describe this package:
- Component index — every component s0ma registers about itself, read out of the registry at build time.
- What s0ma can do — every capability on every channel, including core's
/self/*REST routes and its Python interface. - The MCP servers — what the optional read-only introspection server serves, beside the authoring server it is often confused with.
- Concepts index and the glossary — the vocabulary the rest of the documentation leans on.
- s0ma User Guide — the long-form guide to using the toolchain.
- Embodied survival card — for an agent operating a running s0ma system: a body, a service.
- PRD — purpose, principles, and binding invariants. Read it before changing what s0ma is.
In a terminal, s0ma docs opens the same map and s0ma docs show <topic> answers one question from it.
Releases
The root CHANGELOG.md is the single record of what each release contains, canonical from 0.5.0 onward; this package's own CHANGELOG.md holds the pre-monorepo history through 0.4.0. 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-dsl, s0ma-lang-mcp and s0ma-lang-studi0 are Apache-2.0 too, each with its own LICENSE.
Project s0ma — Know Thyself (kn0wthyself) Software Self-Knowledge Research Program
Metadata
Release files for s0ma-lang-core 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_core-0.22.0.tar.gz | 585.8 kB | Without provenance | Details for s0ma_lang_core-0.22.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| s0ma_lang_core-0.22.0-py3-none-any.whl | Python 3 | none | any | Details for s0ma_lang_core-0.22.0-py3-none-any.whl |
Total release size: 863.6 kB
Release files / s0ma_lang_core-0.22.0.tar.gz
| Download URL | s0ma_lang_core-0.22.0.tar.gz |
|---|---|
| Size | 585.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8070d3acdd4f5f7bd1fafd1fff89e2099d1493b11a7c124c6f184505ccbafd08
|
|
BLAKE2b-256 checksum How to use checksums |
872664f824c9c98fee571a65769548f7ac41a4929566f1bc87d9d5303dbb09ee
|
| 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_core-0.22.0-py3-none-any.whl
| Download URL | s0ma_lang_core-0.22.0-py3-none-any.whl |
|---|---|
| Size | 277.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8a9d89b26d305225e332465918957980888d8e6e9768b89c5b981ec0fe68b544
|
|
BLAKE2b-256 checksum How to use checksums |
ae5e4b8bf8cbc3aaa33fbdd74ca6fcc800b57f95b15d12e5694c9a827ffac77b
|
| 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-core 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.