markov-protocols 0.1.0__py3-none-any.whl

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/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/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/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/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/definition/__init__.py

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

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)")

markov_protocols/definition/registry.py

@@ -0,0 +1,54 @@
+"""The state-type registry — how the definition layer stays open for extension.
+
+Concrete state types register their ``type`` tag here. That lets a workflow (with
+any mix of built-in or third-party states) round-trip through JSON: on load, each
+state dict is dispatched to the class its ``type`` names. The engine itself never
+consults this — it only ever talks to the ``State`` interface.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .state import State
+from .states import ActionExecuteState, DataCollectionState, HumanHandoffState
+
+
+class StateRegistry:
+    """Maps a state ``type`` tag to the class that implements it."""
+
+    def __init__(self) -> None:
+        self._by_type: dict[str, type[State]] = {}
+
+    def register(self, state_type: type[State]) -> None:
+        """Register a concrete state class. Rejects duplicate ``type`` tags."""
+        tag = _type_tag(state_type)
+        existing = self._by_type.get(tag)
+        if existing is not None and existing is not state_type:
+            raise ValueError(f"state type {tag!r} is already registered to {existing.__name__}")
+        self._by_type[tag] = state_type
+
+    def parse(self, value: Any) -> State:
+        """Build a concrete ``State`` from an instance or its serialized dict form."""
+        if isinstance(value, State):
+            return value
+        if not isinstance(value, dict) or "type" not in value:
+            raise ValueError("cannot parse state: expected a State or a dict with a 'type' key")
+        tag = value["type"]
+        cls = self._by_type.get(tag)
+        if cls is None:
+            raise ValueError(f"unknown state type: {tag!r}")
+        return cls.model_validate(value)
+
+
+def _type_tag(state_type: type[State]) -> str:
+    field = state_type.model_fields.get("type")
+    if field is None or field.default is None:
+        raise ValueError(f"{state_type.__name__} must declare a literal 'type' field")
+    return str(field.default)
+
+
+state_registry = StateRegistry()
+state_registry.register(DataCollectionState)
+state_registry.register(ActionExecuteState)
+state_registry.register(HumanHandoffState)

markov_protocols/definition/state.py

@@ -0,0 +1,113 @@
+"""The ``State`` interface — the extension seam of the whole engine.
+
+Every step in a workflow is a ``State``. The engine never branches on a state's
+concrete type; it only ever asks two questions through this interface:
+
+* ``completion_condition()`` — the ``Condition`` that, when true over the
+  Blackboard, means this step is done.
+* ``depends_on()`` — the Blackboard fields whose change should reopen this step.
+
+Adding a new kind of state (here or in a downstream project) means implementing
+these two methods and registering the type — with zero changes to the engine.
+
+Note the two levels: a ``Requirement`` is an authoring input (a needed field with
+an optional extra rule); ``completion_condition()`` compiles those into the single
+evaluable ``Condition`` the engine checks.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Mapping
+from enum import StrEnum
+from typing import Any
+
+from pydantic import Field
+
+from ..base import StrictModel
+from ..conditions.models import All, Condition, Exists
+from ..slug import slugify
+from .metadata import StateMetadata
+
+
+class Status(StrEnum):
+    """A state's lifecycle within one running session."""
+
+    PENDING = "PENDING"  # not yet reached
+    ACTIVE = "ACTIVE"  # the current step
+    COMPLETED = "COMPLETED"  # its completion condition held
+    REOPENED = "REOPENED"  # was completed, then data it depends on changed
+
+
+class Directive(StrictModel):
+    """The host-actionable instruction a state surfaces while it is active.
+
+    The machine never acts; it hands the host a fully-resolved ``payload`` to
+    execute. ``ready`` is false when a referenced field is still missing, and
+    ``missing`` names those fields — so a side effect can't fire half-blank.
+    """
+
+    kind: str
+    ready: bool
+    payload: dict[str, Any] = Field(default_factory=dict)
+    missing: list[str] = Field(default_factory=list)
+
+
+class Requirement(StrictModel):
+    """A field a data-collection state needs, with an optional extra condition."""
+
+    field: str
+    condition: Condition | None = None
+
+
+class State(StrictModel, ABC):
+    """A single step. ``id`` is derived from ``title`` and is never stored."""
+
+    title: str
+    metadata: StateMetadata = StateMetadata()
+
+    @property
+    def id(self) -> str:
+        """The deterministic identifier: the slug of the title."""
+        return slugify(self.title)
+
+    @abstractmethod
+    def completion_condition(self) -> Condition:
+        """The condition that, when true over the Blackboard, marks this state done."""
+
+    @abstractmethod
+    def depends_on(self) -> set[str]:
+        """Blackboard fields whose change should reopen this state."""
+
+    def produces(self) -> set[str]:
+        """Blackboard fields this state *outputs* when it completes.
+
+        Empty by default (data-collection states produce nothing — the user
+        supplies the data). Action/handoff states return their result field.
+        When a state is reopened these fields are cleared, so an action that had
+        already run is forced to run again with the corrected inputs.
+        """
+        return set()
+
+    def directive(self, data: Mapping[str, Any]) -> Directive | None:
+        """The side effect the host must run while this state is active.
+
+        Defaults to ``None`` — states that only wait on the user (e.g. data
+        collection) surface no host action. Action/handoff states override this.
+        """
+        return None
+
+
+def all_of(conditions: list[Condition]) -> Condition:
+    """Combine conditions with AND. A lone condition is returned unwrapped."""
+    if len(conditions) == 1:
+        return conditions[0]
+    return All(of=conditions)
+
+
+def requirement_condition(requirement: Requirement) -> Condition:
+    """A requirement holds when its field exists and its condition (if any) holds."""
+    exists: Condition = Exists(field=requirement.field)
+    if requirement.condition is None:
+        return exists
+    return All(of=[exists, requirement.condition])

markov_protocols/definition/states/__init__.py

@@ -0,0 +1,9 @@
+"""Concrete state types — one building piece per file."""
+
+from __future__ import annotations
+
+from .action_execute import ActionExecuteState
+from .data_collection import DataCollectionState
+from .human_handoff import HumanHandoffState
+
+__all__ = ["ActionExecuteState", "DataCollectionState", "HumanHandoffState"]

markov_protocols/definition/states/action_execute.py

@@ -0,0 +1,48 @@
+"""A state that represents the host running an action and reporting its result."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, Literal, cast
+
+from pydantic import Field, field_validator
+
+from ...conditions.models import Condition, Exists
+from ...references import normalize_refs, referenced_fields, resolve
+from ..state import Directive, State
+
+
+class ActionExecuteState(State):
+    """Completes when the host writes the action's outcome to ``result_field``.
+
+    The machine never runs the action. It surfaces the ``payload`` (with any
+    ``Ref`` resolved) for the host to execute, then waits for the result to land.
+    Because the payload *consumes* the fields it references, changing any of them
+    later reopens this state.
+    """
+
+    type: Literal["ACTION_EXECUTE"] = "ACTION_EXECUTE"
+    payload: dict[str, Any] = Field(default_factory=dict)
+    result_field: str
+
+    @field_validator("payload", mode="after")
+    @classmethod
+    def _normalize_payload(cls, value: dict[str, Any]) -> dict[str, Any]:
+        return normalize_refs(value)
+
+    def completion_condition(self) -> Condition:
+        return Exists(field=self.result_field)
+
+    def depends_on(self) -> set[str]:
+        return referenced_fields(self.payload)
+
+    def produces(self) -> set[str]:
+        return {self.result_field}
+
+    def directive(self, data: Mapping[str, Any]) -> Directive:
+        resolved = resolve(self.payload, data)
+        if resolved.is_success:
+            # Resolving a dict payload always yields a dict on success.
+            payload = cast(dict[str, Any], resolved.value)
+            return Directive(kind="action", ready=True, payload=payload)
+        return Directive(kind="action", ready=False, missing=resolved.error_details or [])