Metadata-Version: 2.4
Name: yoltra
Version: 0.1.0
Summary: Framework-agnostic, event-driven state container with fine-grained atomic reactive subscriptions.
License-Expression: MIT
License-File: LICENSE
Keywords: state,reactive,event-sourcing,store,atomic-subscriptions,agentic
Author: Manu Ramirez
Author-email: manu@erael.com.mx
Requires-Python: >=3.11
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Project-URL: Homepage, https://github.com/yoltra/pyYoltra
Project-URL: Issues, https://github.com/yoltra/pyYoltra/issues
Project-URL: Repository, https://github.com/yoltra/pyYoltra
Description-Content-Type: text/markdown

![Yoltra logo](https://raw.githubusercontent.com/yoltra/pyYoltra/main/assets/logo.png)

# Yoltra for Python

> [ 🇲🇽 Versión en Español](./README.es.md)&nbsp; | &nbsp; 👉 🇺🇸 English Version &nbsp;

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`](https://github.com/yoltra),
reimagined with idiomatic Python. See [`technical-design.md`](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](https://python-poetry.org/).

```bash
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](tools/apidoc/README.md) for how
the generator works, the TypeDoc-schema mapping, and the docstring conventions.

## License

[MIT](LICENSE) — Copyright (c) 2026 Manu Ramirez.

