Metadata-Version: 2.5
Name: s0ma-lang-core
Version: 0.22.0
Summary: A Python framework for software self-knowledge — where the self-model is load-bearing.
Project-URL: Homepage, https://github.com/kn0w-thyself/s0ma
Project-URL: Repository, https://github.com/kn0w-thyself/s0ma
Project-URL: Changelog, https://github.com/kn0w-thyself/s0ma/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/kn0w-thyself/s0ma/issues
Author-email: kn0wthyself <support@kn0wthyself.ai>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: architecture,introspection,self-knowledge,self-model
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Python: >=3.11
Provides-Extra: all
Requires-Dist: fastapi>=0.100.0; extra == 'all'
Requires-Dist: mcp<2,>=1.0.0; extra == 'all'
Requires-Dist: pydantic>=2.0; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.20.0; extra == 'all'
Provides-Extra: api
Requires-Dist: fastapi>=0.100.0; extra == 'api'
Requires-Dist: pydantic>=2.0; extra == 'api'
Requires-Dist: uvicorn[standard]>=0.20.0; extra == 'api'
Provides-Extra: dev
Requires-Dist: httpx>=0.24.0; extra == 'dev'
Requires-Dist: hypothesis>=6.0; extra == 'dev'
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.0.0; extra == 'mcp'
Description-Content-Type: text/markdown

# 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`](https://github.com/kn0w-thyself/s0ma/tree/main/packages/s0ma-mcp) · [`s0ma-lang-studi0`](https://github.com/kn0w-thyself/s0ma/tree/main/packages/s0ma-studi0) → [`s0ma-lang-dsl`](https://github.com/kn0w-thyself/s0ma/tree/main/packages/s0ma-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](https://github.com/kn0w-thyself/s0ma/blob/main/docs/reference/packages.md).

## Install

s0ma is on PyPI:

```bash
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](https://github.com/kn0w-thyself/s0ma/blob/main/README.md#install), and [getting started](https://github.com/kn0w-thyself/s0ma/blob/main/docs/getting-started.md#1-create-a-real-project) 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:

```python
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:

```python
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](https://github.com/kn0w-thyself/s0ma/blob/main/packages/s0ma-dsl/docs/self_prompting.md) has the measurements. Authored intent lines are quoted project data, never host instructions (see [ADR-002](https://github.com/kn0w-thyself/s0ma/blob/main/docs/adr/ADR-002-self-context-authored-data-boundary.md)).

## Documentation

[**The map of record**](https://github.com/kn0w-thyself/s0ma/blob/main/docs/README.md) lists every document this repository keeps, what it is for, and which check keeps it honest. The pages that describe this package:

- [Component index](https://github.com/kn0w-thyself/s0ma/blob/main/docs/architecture/component-index.md) — every component s0ma registers about itself, read out of the registry at build time.
- [What s0ma can do](https://github.com/kn0w-thyself/s0ma/blob/main/docs/reference/surfaces-index.md) — every capability on every channel, including core's `/self/*` REST routes and its Python interface.
- [The MCP servers](https://github.com/kn0w-thyself/s0ma/blob/main/docs/reference/mcp.md) — what the optional read-only introspection server serves, beside the authoring server it is often confused with.
- [Concepts index](https://github.com/kn0w-thyself/s0ma/blob/main/docs/reference/concepts-index.md) and the [glossary](https://github.com/kn0w-thyself/s0ma/blob/main/docs/learn/glossary.md) — the vocabulary the rest of the documentation leans on.
- [s0ma User Guide](https://github.com/kn0w-thyself/s0ma/blob/main/packages/s0ma-core/docs/s0ma_user_guide.md) — the long-form guide to using the toolchain.
- [Embodied survival card](https://github.com/kn0w-thyself/s0ma/blob/main/packages/s0ma-core/docs/embodied_survival_card.md) — for an agent operating a *running* s0ma system: a body, a service.
- [PRD](https://github.com/kn0w-thyself/s0ma/blob/main/references/s0ma-prd.md) — 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`](https://github.com/kn0w-thyself/s0ma/blob/main/CHANGELOG.md) is the single record of what each release contains, canonical from 0.5.0 onward; this package's own [`CHANGELOG.md`](https://github.com/kn0w-thyself/s0ma/blob/main/packages/s0ma-core/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](https://github.com/kn0w-thyself/s0ma/blob/main/packages/s0ma-core/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*
