yoltra 0.1.0

Framework-agnostic, event-driven state container with fine-grained atomic reactive subscriptions.

Yoltra for Python

🇲🇽 Versión en Español  |   👉 🇺🇸 English Version  

A framework-agnostic, event-driven state container with fine-grained ("atomic") reactive subscriptions — the reactive-blackboard primitive for agentic and plugin systems.

Yoltra is a single source of truth. Writes are events; reducers fold events into slice state; a structural diff of each changed slice yields dotted leaf paths; subscribers registered on those paths (connect) fire with Change(old_value, new_value, path). Effects run asynchronously after each committed event. There is no reactivity magic — no proxies, no descriptors, no dependency graph — just diff(prev, next) → paths → subscribers.

This package is a semantic port of the TypeScript @yoltra/core, reimagined with idiomatic Python. See technical-design.md for the full specification.

Status: early development. The public API is being built milestone by milestone; see the design document for scope.

Requirements

• CPython ≥ 3.11
• Zero runtime dependencies in the core.

Development

This project uses Poetry.

poetry install               # create the environment and install dev tooling
poetry run pytest            # run the test suite
poetry run mypy yoltra       # type-check the public surface
poetry run python -m tools.apidoc          # regenerate docs/api/ (Markdown) + .typedoc/ (JSON)
poetry run python -m tools.apidoc --check  # CI: fail if the docs are stale

API docs are generated by the stdlib-only tools/apidoc generator, which introspects the public package and emits both a by-kind Markdown tree under docs/api/ (for GitHub) and a TypeDoc-schema .typedoc/pyoltra-en.json (consumed by the Yoltra website's API-reference pipeline). Hand-written prose guides live under docs/{lang}/. See tools/apidoc/README.md for how the generator works, the TypeDoc-schema mapping, and the docstring conventions.

License

MIT — Copyright (c) 2026 Manu Ramirez.