reactifact 0.6.0__py3-none-any.whl

reactifact/__init__.py

@@ -0,0 +1,96 @@
+"""reactifact's core public API.
+
+Deliberately small: the primitives from the README's "Core primitives"
+section, plus the everyday building blocks (tool calling, sessions, the LLM
+provider protocol) most agents need regardless of what else they use.
+
+Everything else — eval, tracing, checkpoint/branch backends beyond the
+in-memory default, the chat/web layer, the adaptive scheduler, replay,
+structured-LLM helpers, viz, prompts — is one level down, in its own
+submodule (`reactifact.eval`, `reactifact.tracing`, `reactifact.chat`, ...). Import it
+from there:
+
+    from reactifact.structured import structured_llm
+    from reactifact.tracing import TraceStore
+    from reactifact.chat import ChatAssistant
+
+This keeps `dir(reactifact)` / editor autocomplete to what you need to build a
+first agent, and keeps optional-dependency features (Postgres, FastAPI) out
+of the names you see by default even though they were always cheap to import
+(the driver itself is still lazily imported inside the class, see
+`reactifact._extras`).
+"""
+
+from .agents import Agent, create_agent
+from .artifacts import Artifact
+from .branching import MergeConflict
+from .budget import Budget, RunOutcome, RunStats
+from .consume import Consume, consume
+from .context import Context, View
+from .effects import Effects, Handle
+from .events import Event, EventType
+from .interrupt import PendingQuestion
+from .patches import Create, Delete, Link, Patch, Relation, Unlink, Update
+from .produce import Produce, produce
+from .providers import (
+    EmbeddingProvider,
+    FakeEmbedder,
+    FakeLLM,
+    LLMProvider,
+    LLMRequest,
+    LLMResponse,
+    LLMResponseChunk,
+    Message,
+)
+from .resources import RuntimeResources
+from .runtime import Runtime
+from .session import Session, SessionStore
+from .tools import FunctionTool, Tool, ToolOutput, tool
+from .triggers import Trigger
+
+__version__ = "0.6.0"
+
+__all__ = [
+    "Agent",
+    "Artifact",
+    "Budget",
+    "Consume",
+    "Context",
+    "Create",
+    "Delete",
+    "EmbeddingProvider",
+    "Effects",
+    "Event",
+    "EventType",
+    "FakeEmbedder",
+    "FakeLLM",
+    "FunctionTool",
+    "Handle",
+    "Link",
+    "Message",
+    "MergeConflict",
+    "Patch",
+    "PendingQuestion",
+    "Produce",
+    "Relation",
+    "RunOutcome",
+    "RunStats",
+    "Runtime",
+    "RuntimeResources",
+    "LLMProvider",
+    "LLMRequest",
+    "LLMResponse",
+    "LLMResponseChunk",
+    "Session",
+    "SessionStore",
+    "Tool",
+    "ToolOutput",
+    "Trigger",
+    "Unlink",
+    "Update",
+    "View",
+    "consume",
+    "create_agent",
+    "produce",
+    "tool",
+]

reactifact/__main__.py

@@ -0,0 +1,10 @@
+"""Console-script / `python -m reactifact` entry point — see `reactifact.cli`."""
+
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

reactifact/_extras.py

@@ -0,0 +1,36 @@
+"""reactifact._extras — readable errors for optional dependencies.
+
+Core must stay dependency-free; extra-gated features lazily import their
+driver. Instead of a bare `ModuleNotFoundError`, `require_extra` explains what
+it needs and how to install it:
+
+    from reactifact._extras import require_extra
+    psycopg = require_extra("PostgreSQLKVBackend", "psycopg", "pg")
+
+    # -> ImportError:
+    # reactifact.PostgreSQLKVBackend requires the 'pg' extra (psycopg).
+    # Install it with `pip install "reactifact[pg]"` or `uv sync --extra pg`.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+
+def require_extra(feature: str, module: str, extra: str) -> Any:
+    """Imports `module`, or raises a readable error with the install hint."""
+    try:
+        return importlib.import_module(module)
+    except ModuleNotFoundError as exc:
+        missing = exc.name or module
+        if not (missing == module or missing.startswith(module + ".")):
+            raise  # not our dependency — re-raise the original error
+        raise ImportError(
+            f"reactifact.{feature} requires the {extra!r} extra ({module}). "
+            f'Install it with `pip install "reactifact[{extra}]"` '
+            f"or `uv sync --extra {extra}`."
+        ) from None
+
+
+__all__ = ["require_extra"]

reactifact/agents.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+from abc import ABC
+from collections.abc import Sequence
+from typing import Any
+
+from .artifacts import Artifact
+from .consume import Consume
+from .context import Context
+from .events import Event
+from .patches import Patch
+from .produce import Produce
+from .triggers import Trigger
+
+
+class Agent(ABC):  # noqa: B024 — interface without abstract methods, run() has a default
+    """Base container: consumes some artifacts and produces others.
+
+    If `run` is not overridden, automatically collects inputs according to
+    consumes and calls produce on every produce, merging the patches.
+    """
+
+    name: str = ""
+    consumes: Sequence[Consume] | None = None
+    produces: Sequence[Produce[Any]] | None = None
+    #: Declarative capability labels (§25), consumed by the adaptive policy.
+    capabilities: tuple[str, ...] = ()
+    triggers: list[Trigger] = []
+    # Run priority within a single generation: lower value runs earlier.
+    # Useful for "finishers"/evaluators that logically run last (§24).
+    priority: int = 0
+    # Max parallel executions of this agent within a generation. Leave None for
+    # the runtime default (max_concurrency). Use it to throttle LLM-bound
+    # producers (rate limits) independently of cheap I/O (file reads).
+    concurrency_limit: int | None = None
+
+    def __init__(
+        self,
+        name: str | None = None,
+        triggers: list[Trigger] | None = None,
+        priority: int | None = None,
+    ):
+        self.name = name or self.name or self.__class__.__name__
+
+        self.priority = (
+            priority if priority is not None else getattr(self.__class__, "priority", 0)
+        )
+
+        if triggers is not None:
+            self.triggers = list(triggers)
+        elif self.triggers:
+            self.triggers = list(self.triggers)
+        elif self.consumes is not None:
+            self.triggers = self._generate_triggers_from_consumes()
+        else:
+            self.triggers = []
+
+        self._validate_contracts()
+
+    def _generate_triggers_from_consumes(self) -> list[Trigger]:
+        result = []
+        for c in self.consumes or []:
+            result.extend(c.to_triggers())
+        return result
+
+    def _validate_contracts(self) -> None:
+        if self.consumes is not None:
+            for c in self.consumes:
+                if not isinstance(c, Consume):
+                    raise TypeError(
+                        f"Agent {self.name!r}: consumes must contain Consume "
+                        f"instances, got {type(c)}"
+                    )
+        if self.produces is not None:
+            for p in self.produces:
+                if not isinstance(p, Produce):
+                    raise TypeError(
+                        f"Agent {self.name!r}: produces must contain Produce "
+                        f"instances, got {type(p)}"
+                    )
+
+    def matches(self, event: Event, context: Context | None = None) -> bool:
+        return any(trigger.matches(event, context) for trigger in self.triggers)
+
+    def collect_inputs(self, context: Context) -> list[Artifact[Any]]:
+        """Public access to the consumed artifacts.
+
+        Used by the runtime to record the reads linkage (provenance) on run.
+        """
+        return self._collect_inputs(context)
+
+    def _collect_inputs(self, context: Context) -> list[Artifact[Any]]:
+        """Collects all artifacts matching consumes and conditions."""
+        if not self.consumes:
+            return []
+        inputs: list[Artifact[Any]] = []
+        for c in self.consumes:
+            artifacts = context.list_artifacts(c.artifact_type)
+            if c.condition:
+                artifacts = [a for a in artifacts if c.condition(a)]
+            inputs.extend(artifacts)
+        return inputs
+
+    async def run(self, event: Event, context: Context) -> Patch | None:
+        """Default: runs `self.produces` via `execute()` (the effects-first
+        path — write a `Produce` subclass or `@produce` function instead of
+        overriding this).
+
+        Overriding `run()` to return a `Patch` by hand is a low-level,
+        internal escape hatch for cases `effects` genuinely can't express —
+        not a third everyday produce style (see `reactifact.produce`'s module
+        docstring for the two you should reach for first). No example in
+        this repo overrides it; only this repo's own tests do.
+        """
+        await self.execute(context, event)
+        return None
+
+    async def execute(self, context: Context, event: Event | None = None) -> None:
+        """Runs the agent's produces (usually on an event).
+
+        Effects-first (§24): produces write `self.effects.*` and return None;
+        the *runtime* compiles the effect slot into one atomic patch. This method
+        only *runs* the produces — it does not build a patch. (`run` remains the
+        agent-level escape hatch for custom Agent subclasses that assemble a
+        change-set by hand; the runtime merges its result after the effects.)
+        """
+        if not self.produces:
+            return None
+        inputs = self._collect_inputs(context)
+        for p in self.produces:
+            await p.produce(context, inputs, event)
+        return None
+
+
+def create_agent(
+    name: str,
+    *,
+    consumes: Sequence[Consume] | None = None,
+    produces: Sequence[Produce[Any]] | None = None,
+    capabilities: tuple[str, ...] = (),
+    priority: int = 0,
+    concurrency_limit: int | None = None,
+    triggers: list[Trigger] | None = None,
+) -> Agent:
+    """Builds an Agent instance without subclassing.
+
+    `Agent` is a container — nothing needs overriding in the common case — so a
+    subclass is only ceremony. This constructor-style builder covers all of the
+    declarative knobs:
+
+    ```
+    echo = create_agent(
+        name="echo",
+        consumes=[Consume(Question)],
+        produces=[echo_produce],          # a Produce or @produce(...) function
+    )
+    ```
+
+    Falls back to `name` defaults the same way as `Agent.__init__`.
+    """
+    agent = Agent(
+        name=name, triggers=triggers if triggers is not None else [], priority=priority
+    )
+    if consumes is not None:
+        agent.consumes = consumes
+        if triggers is None:
+            agent.triggers = agent._generate_triggers_from_consumes()
+    if produces is not None:
+        agent.produces = produces
+    agent.capabilities = capabilities
+    agent.concurrency_limit = concurrency_limit
+    agent._validate_contracts()
+    return agent

reactifact/artifacts.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import importlib
+import uuid
+from datetime import UTC, datetime
+from typing import Any, Generic, TypeVar
+
+from pydantic import BaseModel
+
+TData = TypeVar("TData", bound=BaseModel)
+ArtifactType = type[BaseModel]
+
+
+def compute_dict_diff(old: dict[str, Any], new: dict[str, Any]) -> dict[str, Any]:
+    """Simple dictionary comparison: returns changed, added and removed keys."""
+    diff: dict[str, Any] = {"changed": {}, "added": {}, "removed": {}}
+    all_keys = set(old.keys()) | set(new.keys())
+    for key in all_keys:
+        if key not in old:
+            diff["added"][key] = new[key]
+        elif key not in new:
+            diff["removed"][key] = old[key]
+        elif old[key] != new[key]:
+            # If both values are dictionaries, compare them recursively
+            if isinstance(old[key], dict) and isinstance(new[key], dict):
+                nested = compute_dict_diff(old[key], new[key])
+                if any(nested.values()):
+                    diff["changed"][key] = nested
+            else:
+                diff["changed"][key] = {"old": old[key], "new": new[key]}
+    return diff
+
+
+def _import_class(full_name: str) -> Any:
+    module_name, class_name = full_name.rsplit(".", 1)
+    module = importlib.import_module(module_name)
+    return getattr(module, class_name)
+
+
+class Artifact(Generic[TData]):
+    """Wrapper around a Pydantic model with versioning."""
+
+    def __init__(
+        self,
+        data: TData,
+        id: str | None = None,
+        created_by_commit: str | None = None,
+    ):
+        self.id = id or str(uuid.uuid4())
+        self.data = data
+        self.data_type = f"{type(data).__module__}.{type(data).__qualname__}"
+        self.created_at = datetime.now(UTC)
+        self.updated_at = self.created_at
+        self.created_by_commit = created_by_commit
+        self._history: list[
+            TData
+        ] = []  # previous data versions (excluding the current one)
+        # Memoized to_dict(), keyed by version: re-derived on every save()
+        # otherwise (session persistence saves after every commit, §reactifact.session)
+        # even though most artifacts in a large context are unchanged since the
+        # last save — see reactifact/session.py for the calling context.
+        self._dict_cache: tuple[int, dict[str, Any]] | None = None
+
+    def update(self, new_data: TData) -> None:
+        """Saves the current version to history and replaces the data."""
+        self._history.append(self.data)
+        self.data = new_data
+        self.updated_at = datetime.now(UTC)
+
+    @property
+    def history(self) -> list[TData]:
+        """Returns a copy of the list of previous versions (excluding the current one)."""
+        return list(self._history)
+
+    @property
+    def version(self) -> int:
+        """Current version (0 – original, 1 – after the first update, etc.)"""
+        return len(self._history)
+
+    def get_all_versions(self) -> list[TData]:
+        """Returns all data versions, including the current one, from oldest to newest."""
+        return self._history + [self.data]
+
+    def diff(self, old_version: int, new_version: int) -> dict[str, Any]:
+        """Returns a diff between two versions by their numbers (0 – the oldest)."""
+        versions = self.get_all_versions()
+        if old_version < 0 or new_version >= len(versions) or old_version > new_version:
+            raise ValueError(
+                f"Invalid version indices: old={old_version}, new={new_version}"
+            )
+        old_data = versions[old_version].model_dump()
+        new_data = versions[new_version].model_dump()
+        return compute_dict_diff(old_data, new_data)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serializes the artifact, including its full version history.
+
+        Memoized per `version` (bumped by `update()`): an unchanged artifact
+        returns the same dict instance on a later call instead of re-walking
+        `model_dump()` over its entire history again — the history only grows
+        monotonically, so a cache keyed by version can never go stale.
+        """
+        if self._dict_cache is not None and self._dict_cache[0] == self.version:
+            return self._dict_cache[1]
+        d = {
+            "id": self.id,
+            "data_type": self.data_type,
+            "data": self.data.model_dump(mode="json"),
+            "created_at": self.created_at.isoformat(),
+            "updated_at": self.updated_at.isoformat(),
+            "history": [v.model_dump(mode="json") for v in self._history],
+            "created_by_commit": self.created_by_commit,
+        }
+        self._dict_cache = (self.version, d)
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Artifact[Any]:
+        model_class = _import_class(d["data_type"])
+        data = model_class.model_validate(d["data"])
+        artifact = cls(
+            data=data, id=d["id"], created_by_commit=d.get("created_by_commit")
+        )
+        artifact.created_at = datetime.fromisoformat(d["created_at"])
+        artifact.updated_at = datetime.fromisoformat(d["updated_at"])
+        artifact._history = [model_class.model_validate(h) for h in d["history"]]
+        return artifact
+
+    def __repr__(self) -> str:
+        return f"<Artifact id={self.id!r} type={self.data.__class__.__name__} v{self.version}>"