markov-protocols 0.1.0__tar.gz

markov_protocols-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gera
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

markov_protocols-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: markov-protocols
+Version: 0.1.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.
+
+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+.

markov_protocols-0.1.0/README.md

@@ -0,0 +1,51 @@
+# 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.
+
+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+.

markov_protocols-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+name = "markov-protocols"
+version = "0.1.0"
+description = "A deterministic finite state machine for modeling workflows that guide AI agents."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "geralm" }
+]
+keywords = [
+    "finite-state-machine",
+    "fsm",
+    "workflow",
+    "state-machine",
+    "ai-agent",
+    "llm",
+    "deterministic",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.13.4",
+]
+
+[project.optional-dependencies]
+yaml = ["pyyaml>=6.0"]
+
+[project.urls]
+Homepage = "https://github.com/geralm/markov-protocols"
+Repository = "https://github.com/geralm/markov-protocols"
+Issues = "https://github.com/geralm/markov-protocols/issues"
+
+[build-system]
+requires = ["uv_build>=0.11.26,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "pyyaml>=6.0",
+    "types-pyyaml>=6.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+strict = true
+files = ["src"]

markov_protocols-0.1.0/src/markov_protocols/__init__.py

@@ -0,0 +1,109 @@
+"""markov-protocols: a deterministic finite state machine for modeling
+workflows that guide AI agents.
+
+Author with ``Workflow`` + the concrete state types, express logic with
+``Condition`` + ``Ref``, and handle outcomes with ``Result``. The runtime
+(``Session``) arrives in a later slice.
+"""
+
+from .conditions import (
+    All,
+    Any,
+    Condition,
+    Eq,
+    Exists,
+    Gt,
+    Gte,
+    In,
+    Lt,
+    Lte,
+    Ne,
+    Not,
+    Regex,
+    condition_fields,
+    evaluate,
+)
+from .definition.metadata import StateMetadata, TransitionMetadata
+from .definition.registry import state_registry
+from .definition.state import Directive, Requirement, State, Status
+from .definition.states import ActionExecuteState, DataCollectionState, HumanHandoffState
+from .definition.transition import Transition
+from .definition.workflow import Workflow
+from .references import Ref, referenced_fields, resolve
+from .result import ErrorType, Result
+from .runtime.blackboard import Blackboard
+from .runtime.events import (
+    ActionExecuted,
+    Event,
+    StateCompleted,
+    StateReopened,
+    TransitionTaken,
+    ValueChanged,
+    ValueSet,
+)
+from .runtime.session import Session, UpdateResult
+from .serialization import (
+    export_to_dict,
+    export_to_file,
+    from_json,
+    from_yaml,
+    import_from_dict,
+    import_from_file,
+    to_json,
+    to_yaml,
+)
+from .slug import slugify
+
+__all__ = [
+    "ActionExecuteState",
+    "ActionExecuted",
+    "All",
+    "Any",
+    "Blackboard",
+    "Condition",
+    "DataCollectionState",
+    "Directive",
+    "Eq",
+    "ErrorType",
+    "Event",
+    "Exists",
+    "Gt",
+    "Gte",
+    "HumanHandoffState",
+    "In",
+    "Lt",
+    "Lte",
+    "Ne",
+    "Not",
+    "Ref",
+    "Regex",
+    "Requirement",
+    "Result",
+    "Session",
+    "State",
+    "StateCompleted",
+    "StateMetadata",
+    "StateReopened",
+    "Status",
+    "Transition",
+    "TransitionMetadata",
+    "TransitionTaken",
+    "UpdateResult",
+    "ValueChanged",
+    "ValueSet",
+    "Workflow",
+    "condition_fields",
+    "evaluate",
+    "export_to_dict",
+    "export_to_file",
+    "from_json",
+    "from_yaml",
+    "import_from_dict",
+    "import_from_file",
+    "referenced_fields",
+    "resolve",
+    "slugify",
+    "state_registry",
+    "to_json",
+    "to_yaml",
+]

markov_protocols-0.1.0/src/markov_protocols/base.py

@@ -0,0 +1,23 @@
+"""Shared Pydantic bases used across every layer.
+
+``StrictModel`` is the default: it rejects unknown fields and revalidates on
+assignment, so a malformed definition can never silently exist. ``StrictOpenModel``
+relaxes only the "unknown fields" rule — used for metadata, where we validate the
+*shape* we rely on but let business policy attach anything else.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class StrictModel(BaseModel):
+    """Reject unknown fields; validate on every assignment."""
+
+    model_config = ConfigDict(extra="forbid", validate_assignment=True)
+
+
+class StrictOpenModel(BaseModel):
+    """Validate declared fields, but allow extra ones (extensible metadata)."""
+
+    model_config = ConfigDict(extra="allow", validate_assignment=True)

markov_protocols-0.1.0/src/markov_protocols/conditions/__init__.py

@@ -0,0 +1,44 @@
+"""Conditions: a small, closed, typed boolean vocabulary over the Blackboard.
+
+A ``Condition`` reads collected data and returns a ``bool`` — the only way the
+machine asks a yes/no question. The vocabulary is deliberately closed (not an open
+expression language): it validates at authoring time, serializes to JSON, and is
+safe to evaluate with no ``eval``.
+"""
+
+from __future__ import annotations
+
+from .evaluate import condition_fields, evaluate
+from .models import (
+    All,
+    Any,
+    Condition,
+    Eq,
+    Exists,
+    Gt,
+    Gte,
+    In,
+    Lt,
+    Lte,
+    Ne,
+    Not,
+    Regex,
+)
+
+__all__ = [
+    "All",
+    "Any",
+    "Condition",
+    "Eq",
+    "Exists",
+    "Gt",
+    "Gte",
+    "In",
+    "Lt",
+    "Lte",
+    "Ne",
+    "Not",
+    "Regex",
+    "condition_fields",
+    "evaluate",
+]

markov_protocols-0.1.0/src/markov_protocols/conditions/evaluate.py

@@ -0,0 +1,129 @@
+"""Pure evaluation of a ``Condition`` against collected data.
+
+The evaluator is a dispatch table: ``op`` → a tiny pure function. Two invariants
+hold for every leaf:
+
+* A condition over a **missing** field is ``False`` — never an error. Absent data
+  can never assert anything, so a workflow can't be steered by data it doesn't have.
+* Evaluation **never raises** on type mismatches (e.g. comparing a string to a
+  number) — it returns ``False``. Determinism must not depend on data being clean.
+
+Only ``Not`` inverts, so ``Not(Exists("x"))`` is ``True`` when ``x`` is absent — the
+one intentional way to assert on absence.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Mapping
+from typing import Any
+
+from .models import (
+    All,
+    Condition,
+    Eq,
+    Exists,
+    Gt,
+    Gte,
+    In,
+    Lt,
+    Lte,
+    Ne,
+    Not,
+    Regex,
+)
+from .models import (
+    Any as AnyCond,
+)
+
+_MISSING = object()
+
+
+def evaluate(condition: Condition, data: Mapping[str, Any]) -> bool:
+    """Return whether ``condition`` holds for ``data``."""
+    return _DISPATCH[type(condition)](condition, data)
+
+
+def condition_fields(condition: Condition) -> set[str]:
+    """Every Blackboard field name a condition tree references.
+
+    Used to report which data a state is still waiting on: the absent members of
+    this set are its missing fields.
+    """
+    if isinstance(condition, All | AnyCond):
+        if not condition.of:
+            return set()
+        return set().union(*(condition_fields(sub) for sub in condition.of))
+    if isinstance(condition, Not):
+        return condition_fields(condition.of)
+    return {condition.field}
+
+
+def _get(data: Mapping[str, Any], field: str) -> Any:
+    return data.get(field, _MISSING)
+
+
+def _exists(c: Exists, data: Mapping[str, Any]) -> bool:
+    value = _get(data, c.field)
+    return value is not _MISSING and value is not None
+
+
+def _eq(c: Eq, data: Mapping[str, Any]) -> bool:
+    value = _get(data, c.field)
+    return value is not _MISSING and value == c.value
+
+
+def _ne(c: Ne, data: Mapping[str, Any]) -> bool:
+    value = _get(data, c.field)
+    return value is not _MISSING and value != c.value
+
+
+def _in(c: In, data: Mapping[str, Any]) -> bool:
+    value = _get(data, c.field)
+    return value is not _MISSING and value in c.value
+
+
+def _regex(c: Regex, data: Mapping[str, Any]) -> bool:
+    value = _get(data, c.field)
+    return isinstance(value, str) and re.search(c.value, value) is not None
+
+
+def _compare(op: Callable[[Any, Any], bool]) -> Callable[[Any, Mapping[str, Any]], bool]:
+    def run(c: Any, data: Mapping[str, Any]) -> bool:
+        value = _get(data, c.field)
+        if value is _MISSING:
+            return False
+        try:
+            return op(value, c.value)
+        except TypeError:
+            return False
+
+    return run
+
+
+def _all(c: All, data: Mapping[str, Any]) -> bool:
+    return all(evaluate(sub, data) for sub in c.of)
+
+
+def _any(c: AnyCond, data: Mapping[str, Any]) -> bool:
+    return any(evaluate(sub, data) for sub in c.of)
+
+
+def _not(c: Not, data: Mapping[str, Any]) -> bool:
+    return not evaluate(c.of, data)
+
+
+_DISPATCH: dict[type, Callable[[Any, Mapping[str, Any]], bool]] = {
+    Exists: _exists,
+    Eq: _eq,
+    Ne: _ne,
+    In: _in,
+    Regex: _regex,
+    Gt: _compare(lambda a, b: a > b),
+    Gte: _compare(lambda a, b: a >= b),
+    Lt: _compare(lambda a, b: a < b),
+    Lte: _compare(lambda a, b: a <= b),
+    All: _all,
+    AnyCond: _any,
+    Not: _not,
+}

markov_protocols-0.1.0/src/markov_protocols/conditions/models.py

@@ -0,0 +1,111 @@
+"""The ``Condition`` discriminated union.
+
+Each condition is a small immutable value object tagged by ``op``. Leaf conditions
+test one field; combinators (``all``/``any``/``not``) nest other conditions. The
+union is discriminated on ``op`` so it round-trips cleanly through JSON.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+from typing import Any as AnyType
+
+from pydantic import Field
+
+from ..base import StrictModel
+
+
+class Exists(StrictModel):
+    """True when ``field`` is present and not null."""
+
+    op: Literal["exists"] = "exists"
+    field: str
+
+
+class Eq(StrictModel):
+    """True when ``field`` exists and equals ``value``."""
+
+    op: Literal["eq"] = "eq"
+    field: str
+    value: AnyType
+
+
+class Ne(StrictModel):
+    """True when ``field`` exists and does not equal ``value`` (missing → False)."""
+
+    op: Literal["ne"] = "ne"
+    field: str
+    value: AnyType
+
+
+class In(StrictModel):
+    """True when ``field`` exists and its value is one of ``value``."""
+
+    op: Literal["in"] = "in"
+    field: str
+    value: list[AnyType]
+
+
+class Regex(StrictModel):
+    """True when ``field`` is a string that ``value`` (a regex) finds a match in."""
+
+    op: Literal["regex"] = "regex"
+    field: str
+    value: str
+
+
+class Gt(StrictModel):
+    op: Literal["gt"] = "gt"
+    field: str
+    value: AnyType
+
+
+class Gte(StrictModel):
+    op: Literal["gte"] = "gte"
+    field: str
+    value: AnyType
+
+
+class Lt(StrictModel):
+    op: Literal["lt"] = "lt"
+    field: str
+    value: AnyType
+
+
+class Lte(StrictModel):
+    op: Literal["lte"] = "lte"
+    field: str
+    value: AnyType
+
+
+class All(StrictModel):
+    """True when every nested condition is true (vacuously true when empty)."""
+
+    op: Literal["all"] = "all"
+    of: list[Condition]
+
+
+class Any(StrictModel):
+    """True when at least one nested condition is true (false when empty)."""
+
+    op: Literal["any"] = "any"
+    of: list[Condition]
+
+
+class Not(StrictModel):
+    """The negation of a nested condition."""
+
+    op: Literal["not"] = "not"
+    of: Condition
+
+
+Condition = Annotated[
+    Exists | Eq | Ne | In | Regex | Gt | Gte | Lt | Lte | All | Any | Not,
+    Field(discriminator="op"),
+]
+"""Any boolean rule over the Blackboard."""
+
+# Resolve the forward references inside the recursive combinators.
+All.model_rebuild()
+Any.model_rebuild()
+Not.model_rebuild()

markov_protocols-0.1.0/src/markov_protocols/definition/__init__.py

@@ -0,0 +1 @@
+"""The definition layer: the immutable, serializable models a user authors."""

markov_protocols-0.1.0/src/markov_protocols/definition/metadata.py

@@ -0,0 +1,30 @@
+"""State and transition metadata: typed-but-open policy carriers.
+
+The reserved sections are the shape the machine relies on being *present*; their
+contents are opaque business policy the machine never interprets. ``extra="allow"``
+(via ``StrictOpenModel``) lets authors attach anything beyond the reserved keys.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import Field
+
+from ..base import StrictOpenModel
+
+
+class StateMetadata(StrictOpenModel):
+    """Policy attached to a state. Contents are opaque to the machine."""
+
+    tools: dict[str, Any] = Field(default_factory=dict)
+    prompts: dict[str, Any] = Field(default_factory=dict)
+    guardrails: dict[str, Any] = Field(default_factory=dict)
+
+
+class TransitionMetadata(StrictOpenModel):
+    """Policy attached to a transition. Contents are opaque to the machine."""
+
+    events: dict[str, Any] = Field(default_factory=dict)
+    resources: dict[str, Any] = Field(default_factory=dict)
+    reward: float = Field(default=1.0, ge=0.0, description="Transition reward (experimental)")