Metadata-Version: 2.4
Name: markov-protocols
Version: 0.2.0
Summary: A deterministic finite state machine for modeling workflows that guide AI agents.
Keywords: finite-state-machine,fsm,workflow,state-machine,ai-agent,llm,deterministic
Author: geralm
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Dist: pydantic>=2.13.4
Requires-Dist: pyyaml>=6.0 ; extra == 'yaml'
Requires-Python: >=3.13
Project-URL: Homepage, https://github.com/geralm/markov-protocols
Project-URL: Repository, https://github.com/geralm/markov-protocols
Project-URL: Issues, https://github.com/geralm/markov-protocols/issues
Provides-Extra: yaml
Description-Content-Type: text/markdown

# markov-protocols

A Finite State Machine capable of modeling workflows to provide guidance to an AI agent with determinism.

A standalone Python module providing the state-machine mechanism, meant to be reused across other Python projects.

## Status

Slices 1–3 complete — the engine is functionally whole:

- **Definition** — conditions, references, metadata, the `State` interface with three concrete state
  types, transitions, the registry, and `Workflow.compile()`.
- **Runtime** — `Blackboard`, the `Event` history, `Directive` materialization, and
  `Session.start/update` with the write + fast-forward passes.
- **Integrity** — a correction (`ValueChanged`) reopens the states that depend on it, strict-rewinds
  to the earliest one, clears reopened actions' outputs so they re-run, and flags `had_executed`
  for host compensation. All derived from `history` — no parallel bookkeeping.
- **Blockers & rendering** — every state explains *why* it hasn't advanced via `blockers`
  (`MISSING` / `INVALID` / `AWAITING_*`); requirements take `description` + `options` (enum with
  per-value descriptions); components render to safe, factual prompt text via `Renderable`.
- **Serialization** — import/export workflows as JSON or YAML (`to_json`/`from_json`/…), validated
  through `compile()`.

See [`docs/DESIGN.md`](docs/DESIGN.md) for the full architecture and build plan.

## Development

Managed with [uv](https://docs.astral.sh/uv/).

```bash
uv sync            # create the environment and install dev tools
uv run pytest      # run the test suite
uv run ruff check  # lint
uv run mypy        # type-check
```

## Layout

```
src/markov_protocols/
    __init__.py        # curated public API
    result.py          # Result[T, E] / ErrorType — the error-handling pattern
    base.py            # StrictModel / StrictOpenModel
    slug.py            # deterministic title -> id
    conditions/        # the typed boolean vocabulary + pure evaluator
    references.py      # Ref + resolve + referenced_fields
    definition/        # metadata, State interface + concrete states, Transition,
                       #   registry, Workflow.compile()
    runtime/           # Blackboard, Event history, Session + update() pipeline
tests/                 # one property-focused module per unit
```

## Conventions

- Operations return a `Result[T, E]` instead of raising exceptions.
- Target Python 3.13+.
