reactifact 0.6.0__py3-none-any.whl

reactifact/branching.py

@@ -0,0 +1,255 @@
+"""reactifact.branching — fork/merge semantics and their durable persistence
+(§39-§40).
+
+`clone_context`/`fork_context`/`merge_context_from`/`merge_contexts` are the
+git-like state operations `Context.clone()`/`.branch()`/`.merge_from()`/
+`.merge()` delegate to — moved here so the git-like algorithm lives next to
+the concept it implements, not folded into `Context`'s general CRUD/relations/
+HITL surface. `BranchStore` only *persists* named forks so they survive a
+restart:
+
+    store = BranchStore(SQLiteKVBackend("sessions.sqlite3"))
+    await store.save_branch(ctx_branch, session_id="demo", name="hypothesis-a")
+    restored = await store.load_branch("demo", "hypothesis-a")
+
+Each branch key holds the full self-contained context (`to_dict`, which now also
+carries the fork base snapshot), so a merged restart keeps `merge()` conflict
+detection working. Naming follows `branch:<session>:<name>`; the KV backend stays
+the only storage primitive — branches are a convention on top of it, not a new
+backend (matching the constitution: semantics live in Context operations).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+from .artifacts import Artifact
+from .checkpoints import KVBackend
+from .commit import Commit
+from .context import Context
+from .patches import Create, Delete, Link, Operation, Update
+
+
+class MergeConflict(Exception):
+    """Two branches changed the same artifact differently since their fork (§40).
+
+    The framework never chooses silently; a verifier or merge policy resolves.
+    """
+
+    def __init__(self, message: str, conflicts: list[str] | None = None):
+        super().__init__(message)
+        self.conflicts = conflicts or []
+
+
+def clone_context(source: Context) -> Context:
+    """Deep copy of `source`'s live state (artifacts, log, relations)."""
+    new_ws = Context()
+    for artifact in source._artifacts.values():
+        new_artifact = Artifact(
+            data=artifact.data.model_copy(deep=True),
+            id=artifact.id,  # <-- important!
+            created_by_commit=artifact.created_by_commit,
+        )
+        new_artifact._history = [v.model_copy(deep=True) for v in artifact._history]
+        new_artifact.created_at = artifact.created_at
+        new_artifact.updated_at = artifact.updated_at
+        new_ws._artifacts[artifact.id] = new_artifact
+    new_ws._log = source._log.copy()
+    new_ws._relations = source._relations.copy()
+    new_ws._recompute_stale()
+    return new_ws
+
+
+def fork_context(source: Context, *, name: str = "") -> Context:
+    """Forks an isolated copy of `source` for alternative state exploration (§39).
+
+    The fork records a snapshot of its base, so a later `merge_contexts` of
+    two fork-mates can detect diverged artifacts three-way (§40). The branch
+    shares `resources` with the parent but is otherwise fully independent:
+    subsequent changes on either side do not affect the other.
+    """
+    fork = clone_context(source)
+    fork.resources = source.resources
+    fork._base = clone_context(source)
+    fork._fork_name = name
+    return fork
+
+
+def merge_context_from(target: Context, other: Context) -> None:
+    """Two-way merge: adopts everything in `other` that is newer/absent in
+    `target` — no conflict detection (see `merge_contexts` for that)."""
+    operations: list[Operation] = []
+    for other_artifact in other.list_artifacts():
+        other_id = other_artifact.id
+        current = target.get(other_id)
+        if current is not None:
+            if other_artifact.version > current.version:
+                new_data = other_artifact.data.model_copy(deep=True)
+                target.update(other_id, new_data)
+                operations.append(Update(other_id, new_data))
+        else:
+            new_data = other_artifact.data.model_copy(deep=True)
+            # NOTE: no `id=other_id` — matches the pre-extraction behavior of
+            # `Context.merge_from()` exactly (a merged-in artifact absent from
+            # `target` gets a freshly minted id, not `other_id`). Not fixed
+            # here — a real behavior change belongs in its own change, not a
+            # pure extraction.
+            target.create(new_data)
+            operations.append(Create(new_data))
+    for rel in other.relations():
+        if (rel.source_id, rel.relation, rel.target_id) not in target._relations:
+            target.link(rel.source_id, rel.relation, rel.target_id)
+            operations.append(Link(rel.source_id, rel.relation, rel.target_id))
+    if operations:
+        target.log_commit(
+            Commit(author="merge", message="Merged Context", operations=operations)
+        )
+
+
+def _data_sig(artifact: Artifact[Any] | None) -> Any:
+    """Canonical signature of an artifact's current data (None = absent)."""
+    if artifact is None:
+        return None
+    return artifact.data.model_dump(mode="json")
+
+
+def _kind_short(signature: Any) -> str:
+    if signature is None:
+        return "absent"
+    return "changed"
+
+
+def merge_contexts(
+    target: Context, other: Context, *, message: str = "Merged branch"
+) -> None:
+    """Merges `other` into `target` with explicit conflicts, atomically (§40).
+
+    Three-way merge against the shared fork base (the fork snapshot of
+    `other`, or of `target` when `other` has none). For every artifact that
+    exists anywhere among base/target/other:
+
+        equal(target, other)  → no-op
+        equal(target, base)   → adopt `other` (only it moved the artifact)
+        equal(other, base)    → keep `target` (only it moved the artifact)
+        otherwise              → MergeConflict, nothing is applied
+
+    So a change adopted from `other` never silently overwrites a change made
+    on `target` since the fork (§40: the framework must not choose silently).
+    """
+    base = other._base if other._base is not None else target._base
+    if base is None:
+        base = Context()
+
+    ids = set(base._artifacts) | set(target._artifacts) | set(other._artifacts)
+    operations: list[Operation] = []
+    pending: dict[str, BaseModel] = {}
+    conflicts: list[str] = []
+
+    for artifact_id in sorted(ids):
+        base_art = base._artifacts.get(artifact_id)
+        target_art = target._artifacts.get(artifact_id)
+        other_art = other._artifacts.get(artifact_id)
+        sb = _data_sig(base_art)
+        st = _data_sig(target_art)
+        so = _data_sig(other_art)
+        if st == so:
+            continue
+        if st == sb or so == sb:
+            if so == sb:
+                continue  # only target moved it — keep as is
+            # only other moved it — adopt
+            if other_art is None:
+                operations.append(Delete(artifact_id))
+            else:
+                pending[artifact_id] = other_art.data.model_copy(deep=True)
+                operations.append(
+                    Create(other_art.data)
+                    if target_art is None
+                    else Update(artifact_id, other_art.data)
+                )
+        else:
+            conflicts.append(
+                f"{artifact_id} diverged since the fork "
+                f"(target={_kind_short(st)}, other={_kind_short(so)})"
+            )
+
+    if conflicts:
+        raise MergeConflict(
+            "merge would overwrite diverged state — resolve first (§40):\n"
+            + "\n".join(conflicts),
+            conflicts=conflicts,
+        )
+
+    removed: set[str] = set()
+    for op in operations:
+        if isinstance(op, Delete):
+            target._artifacts.pop(op.artifact_id, None)
+            removed.add(op.artifact_id)
+    for artifact_id, data in pending.items():
+        existing = target._artifacts.get(artifact_id)
+        if existing is None:
+            target._artifacts[artifact_id] = Artifact(data=data, id=artifact_id)
+        else:
+            existing.update(data)
+
+    for rel in other.relations():
+        if rel.source_id in removed or rel.target_id in removed:
+            continue
+        if (rel.source_id, rel.relation, rel.target_id) not in target._relations:
+            target.link(rel.source_id, rel.relation, rel.target_id)
+            operations.append(Link(rel.source_id, rel.relation, rel.target_id))
+
+    if operations:
+        target.log_commit(
+            Commit(author="merge", message=message, operations=operations)
+        )
+        # merge mutates `_artifacts` directly (create/update/delete above),
+        # bypassing the incremental hooks in `create()`/`update()`/
+        # `delete()` — resync `_stale` from scratch rather than risk it
+        # drifting from the post-merge state.
+        target._recompute_stale()
+
+
+class BranchStore:
+    """Persists named branches (`branch:<session>:<name>`) over a KV backend."""
+
+    def __init__(self, backend: KVBackend):
+        self.backend = backend
+
+    @staticmethod
+    def _key(session_id: str, name: str) -> str:
+        return f"branch:{session_id}:{name}"
+
+    async def save_branch(
+        self, context: Context, *, session_id: str, name: str
+    ) -> None:
+        """Saves a branch (including its fork base snapshot, §40)."""
+        await context.to_kv(self.backend, self._key(session_id, name))
+
+    async def load_branch(self, session_id: str, name: str) -> Context | None:
+        """Loads a branch, or None if it does not exist."""
+        return await Context.from_kv(self.backend, self._key(session_id, name))
+
+    async def list_branches(self, session_id: str) -> list[str]:
+        prefix = f"branch:{session_id}:"
+        names: list[str] = []
+        all_keys = await self.backend.keys()
+        for key in all_keys:
+            if key.startswith(prefix):
+                names.append(key[len(prefix) :])
+        return sorted(names)
+
+    async def delete_branch(self, session_id: str, name: str) -> None:
+        await self.backend.delete(self._key(session_id, name))
+
+
+__all__ = [
+    "BranchStore",
+    "MergeConflict",
+    "clone_context",
+    "fork_context",
+    "merge_context_from",
+    "merge_contexts",
+]

reactifact/budget.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from pydantic import BaseModel
+
+
+class RunOutcome(StrEnum):
+    """Deterministic run outcome (instead of silent nothingness, §58).
+
+    The application routes on it: completed → answer is ready;
+    budget_* / iterations_exhausted → not enough resources, show an honest status.
+    """
+
+    COMPLETED = "completed"
+    ITERATIONS_EXHAUSTED = "iterations_exhausted"
+    BUDGET_RUNS_EXCEEDED = "budget_runs_exceeded"
+    BUDGET_TIME_EXCEEDED = "budget_time_exceeded"
+
+
+class Budget(BaseModel):
+    """Resource limit for a single run (turn), applied by the runtime."""
+
+    max_runs: int | None = None  # max agent runs
+    max_iterations: int | None = None  # max loop generations
+    max_seconds: float | None = None  # time budget
+    max_tool_calls: int | None = None  # max tool calls executed (LLM agent)
+
+
+@dataclass
+class RunStats:
+    """Run summary: how much was done and why it stopped."""
+
+    runs: int
+    iterations: int
+    outcome: RunOutcome
+    duration: float
+    #: Agent executions that raised and were isolated (`Runtime(isolate_errors=True)`).
+    #: Always 0 when isolation is off — an exception propagates instead (§69).
+    errors: int = 0

reactifact/chat.py

@@ -0,0 +1,373 @@
+"""reactifact.chat — the app-facing chat layer (sessions + turns + history).
+
+A thin, transport-agnostic layer on top of the runtime: it owns sessions
+(`SessionStore`), the wire-neutral turn loop ("create the user artifact, stream
+status events, then the terminal reply") and history reconstruction. It knows
+nothing about HTTP/SSE — the web adapter lives in `reactifact.web`.
+
+Two levels of use:
+
+- `ChatAssistant` — concrete, batteries-included for the canonical chat
+  contract. Configure it with hooks (agents, `user_message` model, `reply`).
+- `run_message` / `default_session_state` — building blocks, for apps whose
+  loop or transport differs (bots, custom SSE, medic-lab-style steering).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import AsyncGenerator, AsyncIterator, Callable, Sequence
+from contextlib import asynccontextmanager
+from typing import Any
+
+from pydantic import BaseModel
+
+from .agents import Agent
+from .budget import Budget
+from .context import Context
+from .events import Event
+from .resources import RuntimeResources
+from .runtime import Runtime
+from .session import Session, SessionStore
+
+logger = logging.getLogger("reactifact.chat")
+
+
+class ChatEvent(BaseModel):
+    """One frame of a chat turn, transport-neutral.
+
+    `kind` is the wire contract of the canonical chat:
+    ``session`` (start), ``status`` (progress announcement) or ``message``
+    (terminal reply).
+    """
+
+    kind: str
+    session_id: str = ""
+    message: str = ""
+    waiting: bool = False
+    payload: dict[str, Any] = {}
+
+
+# --- building blocks ------------------------------------------------------- #
+
+
+def _fallback_payload(fallback_reply: str) -> dict[str, Any]:
+    """The honest terminal payload when a turn crashed (§59)."""
+    return {"reply": fallback_reply, "waiting": False, "error": True}
+
+
+async def run_message(
+    runtime: Runtime,
+    text: str,
+    *,
+    user_message: type[BaseModel],
+    reply: Callable[[Context, str], dict[str, Any]],
+    session_id: str = "",
+    create_message: Callable[[Context, str], str] | None = None,
+    status_kinds: Sequence[str] = ("status",),
+    fallback_reply: str = "No reply assembled.",
+) -> AsyncIterator[ChatEvent]:
+    """Run one user turn: create the input artifact, stream status events,
+    emit the terminal reply.
+
+    `reply(ctx, msg_id) -> dict` adapts the app's state into the `message`
+    payload (the only domain hook). Statuses are deduplicated so repeated
+    progress announcements don't double-emit.
+
+    `create_message(ctx, text) -> msg_id` overrides how the turn enters the
+    context (default: create a `user_message` artifact) — HITL apps where a
+    new turn resumes a pending question instead of appending a message
+    (devops-style clarify) pass their own.
+
+    `status_kinds` selects which progress event kinds are forwarded as `status`
+    frames (default: only `status`; e.g. tool-announcing demos also forward
+    `agent`).
+
+    Errors never escape: a failed runtime/reply degrades to the `fallback_reply`
+    `message` event (logged via `reactifact.chat` logger) so a web layer never
+    delivers a 500 mid-stream.
+    """
+    forwarded = set(status_kinds)
+    ctx = runtime.context
+    try:
+        if create_message is not None:
+            msg_id = create_message(ctx, text)
+        else:
+            msg_id = ctx.create(user_message(text=text, session_id=session_id)).id
+    except Exception:
+        logger.exception("chat.run_message: failed to enter the turn")
+        yield ChatEvent(
+            kind="message",
+            session_id=session_id,
+            payload=_fallback_payload(fallback_reply),
+        )
+        return
+
+    last: str | None = None
+    try:
+        async for event in runtime.astream():
+            if event.kind not in forwarded:
+                continue
+            if event.message == last:
+                continue
+            last = event.message
+            yield ChatEvent(kind="status", session_id=session_id, message=event.message)
+    except Exception:
+        # The runtime crashed — the context may be half-applied. Skip the reply
+        # hook (it could echo stale state) and degregate to the honest fallback.
+        logger.exception("chat.run_message: runtime crashed inside the turn")
+        yield ChatEvent(
+            kind="message",
+            session_id=session_id,
+            payload=_fallback_payload(fallback_reply),
+        )
+        return
+    try:
+        payload = reply(ctx, msg_id)
+    except Exception:
+        logger.exception("chat.run_message: reply hook crashed")
+        payload = _fallback_payload(fallback_reply)
+    yield ChatEvent(
+        kind="message",
+        session_id=session_id,
+        payload=payload or _fallback_payload(fallback_reply),
+    )
+
+
+def default_session_state(
+    ctx: Context, *, user_message: type[BaseModel]
+) -> dict[str, Any]:
+    """Generic history: every artifact with a `text` field, in creation order.
+
+    Artifacts of `user_message`'s type are marked `user`, everything else —
+    `assistant`. Apps with richer reply payloads pass their own hook.
+    """
+    messages: list[dict[str, Any]] = []
+    for artifact in sorted(ctx.list_artifacts(), key=lambda a: a.created_at):
+        data = artifact.data
+        text = getattr(data, "text", None)
+        if not isinstance(text, str):
+            continue
+        role = "user" if isinstance(data, user_message) else "assistant"
+        messages.append(
+            {
+                "role": role,
+                "text": text,
+                "at": artifact.created_at.isoformat(),
+            }
+        )
+    return {"messages": messages}
+
+
+def _resolve(value: Any) -> Any:
+    return value() if callable(value) else value
+
+
+# --- the canonical chat assistant ----------------------------------------- #
+
+
+class ChatAssistant:
+    """Session-persisted chat over the runtime, for the canonical contract.
+
+    Configure with hooks — the assistant owns sessions, the turn loop and
+    history. `agents`/`resources` accept values or callables (resolved per
+    request, so a fresh `RuntimeResources` can replace providers).
+
+    A callable `resources=` is assumed to build a fresh, turn-scoped
+    `RuntimeResources` each call (e.g. `resources=lambda: build_resources()`)
+    — `stream()` closes it (`RuntimeResources.aclose()`) after every turn, so
+    its provider's HTTP client doesn't leak. Pass a plain `RuntimeResources`
+    instance instead when you want one shared, long-lived provider across
+    turns/sessions — that instance is never closed automatically; close it
+    yourself at real shutdown.
+
+    Base usage:
+
+        assistant = ChatAssistant(
+            store=store,
+            agents=ALL_AGENTS,
+            user_message=UserQuery,
+            reply=knowledge_reply,
+            resources=lambda: build_resources(),
+        )
+        async for ev in assistant.stream("hello", session_id="s1"):
+            ...
+    """
+
+    def __init__(
+        self,
+        *,
+        store: SessionStore,
+        agents: Sequence[Agent] | Callable[[], Sequence[Agent]],
+        user_message: type[BaseModel],
+        reply: Callable[[Context, str], dict[str, Any]],
+        session_state: Callable[[Context], dict[str, Any]] | None = None,
+        resources: RuntimeResources | Callable[[], RuntimeResources] | None = None,
+        budget: Budget | None = None,
+        max_concurrency: int | None = None,
+        tracer: Any = None,
+        create_message: Callable[[Context, str], str] | None = None,
+        status_kinds: Sequence[str] = ("status",),
+        fallback_reply: str = "No reply assembled.",
+        isolate_errors: bool = False,
+        on_agent_error: Callable[[Agent, Event, BaseException], None] | None = None,
+    ):
+        self.store = store
+        self._agents = agents
+        self._user_message = user_message
+        self._reply = reply
+        self._session_state = session_state
+        self._resources = resources
+        self._budget = budget
+        self._max_concurrency = max_concurrency
+        self._tracer = tracer
+        self._create_message = create_message
+        self._status_kinds = tuple(status_kinds)
+        self._fallback_reply = fallback_reply
+        self._isolate_errors = isolate_errors
+        self._on_agent_error = on_agent_error
+        # Serializes concurrent turns on the *same* session_id (a double
+        # submit, a client retry): without this, two overlapping stream()
+        # calls both load the same starting state and the later save() wins,
+        # silently dropping the other turn (§59: no silent data loss).
+        # Different session_ids never block each other. Entries are removed
+        # once uncontended (`_lock_refs` hits 0) so this stays bounded by
+        # concurrently-active sessions, not by every session_id ever seen —
+        # see `_locked_session`.
+        self._locks_guard = asyncio.Lock()
+        self._session_locks: dict[str, asyncio.Lock] = {}
+        self._lock_refs: dict[str, int] = {}
+
+    @asynccontextmanager
+    async def _locked_session(self, session_id: str) -> AsyncGenerator[None, None]:
+        """Mutual exclusion per `session_id` for the turn's duration (§59).
+
+        The lock is created on first use and dropped once nothing holds it
+        (`_lock_refs` hits 0) — sized by concurrently-active sessions, not
+        every session_id ever seen, so a long-lived server doesn't grow this
+        dict without bound.
+        """
+        async with self._locks_guard:
+            lock = self._session_locks.setdefault(session_id, asyncio.Lock())
+            self._lock_refs[session_id] = self._lock_refs.get(session_id, 0) + 1
+        async with lock:
+            try:
+                yield
+            finally:
+                async with self._locks_guard:
+                    self._lock_refs[session_id] -= 1
+                    if self._lock_refs[session_id] <= 0:
+                        self._lock_refs.pop(session_id, None)
+                        self._session_locks.pop(session_id, None)
+
+    async def _open(self, session_id: str) -> Session:
+        return await self.store.open(session_id, resources=_resolve(self._resources))
+
+    def _build_runtime(self, session: Session) -> Runtime:
+        return Runtime(
+            session.context,
+            agents=list(_resolve(self._agents)),
+            session=session,
+            budget=self._budget,
+            max_concurrency=self._max_concurrency,
+            tracer=_resolve(self._tracer),
+            isolate_errors=self._isolate_errors,
+            on_agent_error=self._on_agent_error,
+        )
+
+    async def stream(self, text: str, session_id: str = "") -> AsyncIterator[ChatEvent]:
+        """Stream one turn: ``session`` → ``status``… → ``message``.
+
+        Never raises for app-level failures: session open / runtime crash /
+        reply hook all degrade to the fallback `message` and are logged via the
+        `reactifact.chat` logger, so a web layer never delivers a 500 mid-stream.
+
+        Turns on the same `session_id` are serialized (`_locked_session`): a
+        second concurrent call for the same session waits for the first to
+        finish instead of racing it to `session.save()` (§59 — no silent lost
+        update). Different `session_id`s never block each other. This only
+        covers calls made through this `ChatAssistant` instance — the
+        lower-level `run_message` building block has no such guarantee, by
+        design (see the module docstring).
+        """
+        async with self._locked_session(session_id):
+            try:
+                session = await self._open(session_id)
+                runtime = self._build_runtime(session)
+            except Exception:
+                logger.exception(
+                    "chat.ChatAssistant: failed to open session %r", session_id
+                )
+                yield ChatEvent(
+                    kind="message",
+                    session_id=session_id,
+                    payload=_fallback_payload(self._fallback_reply),
+                )
+                return
+            yield ChatEvent(kind="session", session_id=session_id)
+            try:
+                async for event in run_message(
+                    runtime,
+                    text,
+                    user_message=self._user_message,
+                    reply=self._reply,
+                    create_message=self._create_message,
+                    status_kinds=self._status_kinds,
+                    fallback_reply=self._fallback_reply,
+                    session_id=session_id,
+                ):
+                    yield event
+            finally:
+                try:
+                    await session.save()  # persist the conversation after the turn
+                except Exception:
+                    logger.exception(
+                        "chat.ChatAssistant: failed to save session %r", session_id
+                    )
+                if callable(self._resources):
+                    # A callable `resources=` builds a fresh RuntimeResources (and
+                    # typically a fresh provider + HTTP client) on every turn —
+                    # nothing else will ever reference this instance again, so
+                    # it's this turn's job to close it. A shared instance passed
+                    # directly is not touched here: it must outlive this turn.
+                    try:
+                        await session.context.resources.aclose()
+                    except Exception:
+                        logger.exception(
+                            "chat.ChatAssistant: failed to close per-turn resources %r",
+                            session_id,
+                        )
+
+    async def invoke(self, text: str, session_id: str = "") -> dict[str, Any]:
+        """Run one turn and return the terminal reply (aggregated stream)."""
+        message: dict[str, Any] = {}
+        async for event in self.stream(text, session_id=session_id):
+            if event.kind == "message":
+                message = dict(event.payload) or {"reply": self._fallback_reply}
+        return message
+
+    async def history(self, session_id: str = "") -> dict[str, Any]:
+        """Reconstruct the chat thread of a persisted session."""
+        try:
+            session = await self._open(session_id)
+        except Exception:
+            logger.exception("chat.ChatAssistant: history open failed %r", session_id)
+            return {"messages": []}
+        if not session.loaded:
+            return {"messages": []}
+        if self._session_state is not None:
+            return self._session_state(session.context)
+        return default_session_state(session.context, user_message=self._user_message)
+
+    def reply_fallback(self) -> dict[str, Any]:
+        """The honest terminal payload when nothing was assembled (§59)."""
+        return {"reply": self._fallback_reply, "waiting": False}
+
+
+__all__ = [
+    "ChatAssistant",
+    "ChatEvent",
+    "default_session_state",
+    "run_message",
+]