reactifact 0.13.0__tar.gz → 0.14.1__tar.gz

{reactifact-0.13.0/reactifact.egg-info → reactifact-0.14.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reactifact
-Version: 0.13.0
+Version: 0.14.1
 Summary: Reactive, artifact-driven agent runtime: agents transform versioned, typed, provenance-aware artifacts inside an evolving context
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/bzdvdn/reactifact
@@ -36,6 +36,8 @@ Provides-Extra: pg
 Requires-Dist: psycopg[binary]>=3.2; extra == "pg"
 Provides-Extra: mcp
 Requires-Dist: mcp>=2.2; extra == "mcp"
+Provides-Extra: a2a
+Requires-Dist: a2a-sdk>=1.0; extra == "a2a"
 Provides-Extra: docs
 Requires-Dist: mkdocs>=1.6; extra == "docs"
 Requires-Dist: mkdocs-material>=9.5; extra == "docs"
@@ -289,13 +291,19 @@ by hand. Run it yourself: `uv run python -m examples.ledger.main`.
 - **Provenance** — every derived artifact links to what produced it
   (`Answer —supported_by→ Claim —derived_from→ Evidence —extracted_from→ Doc`).
 - **HITL** — humans as `effects.ask(...)` → `PendingQuestion`, answered via `effects.resume(...)` like any agent.
+- **Outbox** — outbound side effects as `effects.act(...)` → `PendingAction`, performed once *after* the commit by `Runtime(dispatcher=...)`; safe across replay, retries and merged branches.
 
 ## In the box
 
 - **Deterministic by design** — calculations over structured data, honest `None`
   fallbacks instead of hallucinated answers; the model reasons, never "knows".
 - **Observability** — every run traces agent spans, reads/writes, LLM calls,
-  tokens: SQLite store + web dashboard, exportable to Langfuse/Postgres (async sinks).
+  tokens: SQLite store + web dashboard, exportable to Langfuse/Postgres (async sinks);
+  **correlated logs** (`configure_logging()`, silent until called) carry
+  `run_id`/`session_id`/`agent` on every line.
+- **Lifecycle** — `Budget.max_seconds` is a hard deadline (a hung LLM call is
+  cancelled); `request_stop()`/`ashutdown()` stop at a generation boundary
+  (`RunOutcome.STOPPED`); `active_runs()`/`in_flight` give a readiness view.
 - **MCP, both ways** — call any MCP server's tools as a `Tool`
   (`mcp_stdio_tools`/`mcp_http_tools`), or expose your own `Tool`s and a live
   `Context` as an MCP server (`create_mcp_server`) for Claude Desktop, Claude
@@ -326,7 +334,7 @@ uv run python ./examples/devops/web.py         # HITL ops assistant + trace dash
 ```
 
 Classic-pattern ports run as one-liners too:
-`python -m examples.{reflection,map_reduce,supervisor,summarize,time_travel,plan_execute,adaptive,ledger}.main`.
+`python -m examples.{reflection,map_reduce,supervisor,summarize,time_travel,plan_execute,adaptive,ledger,outbox}.main`.
 
 Prefer a notebook? [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/bzdvdn/reactifact/blob/master/examples/quickstart.ipynb)
 — `examples/quickstart.ipynb` covers the four `quick` cases (`agent`/`rag`/`tools_agent`/`chat_agent`), offline by default.
@@ -341,6 +349,7 @@ Prefer a notebook? [![Open in Colab](https://colab.research.google.com/assets/co
 - `chat` — minimal offline single-model multi-turn conversation (`Conversation` + bounded `ChatMemory`).
 - `forklab` — deterministic branch & merge: two strategies on their own forks, three-way merge.
 - `ledger` — offline proof of reactive recompute: edit one fact, only its real `Consume`rs re-run.
+- `outbox` — one intent, one send: `effects.act(...)` + `Runtime(dispatcher=...)`, safe across replays, retries and merged branches (§42).
 - `llm_ladder` — the workflow from one LLM call to state-changing patches (3 levels).
 - `adaptive` — hybrid scheduler: rule filters + deterministic rank + LLM tie-break + `rank_limit`.
 - `{reflection,map_reduce,supervisor,summarize,time_travel,plan_execute}` — canonical ports (see [port-matrix](docs/en/port-matrix.md)).
@@ -371,7 +380,7 @@ uv sync --extra dev --extra web
 
 ## Status & contributing
 
-Active, `0.13.x`, pre-1.0 — the API is stabilizing and `1.0` will freeze it
+Active, `0.14.x`, pre-1.0 — the API is stabilizing and `1.0` will freeze it
 (see the [roadmap](docs/roadmap.md)); releases follow
 [Keep a Changelog](CHANGELOG.md). Questions and design discussion live in
 [GitHub Discussions](https://github.com/bzdvdn/reactifact/discussions); a star,

{reactifact-0.13.0 → reactifact-0.14.1}/README.md

@@ -245,13 +245,19 @@ by hand. Run it yourself: `uv run python -m examples.ledger.main`.
 - **Provenance** — every derived artifact links to what produced it
   (`Answer —supported_by→ Claim —derived_from→ Evidence —extracted_from→ Doc`).
 - **HITL** — humans as `effects.ask(...)` → `PendingQuestion`, answered via `effects.resume(...)` like any agent.
+- **Outbox** — outbound side effects as `effects.act(...)` → `PendingAction`, performed once *after* the commit by `Runtime(dispatcher=...)`; safe across replay, retries and merged branches.
 
 ## In the box
 
 - **Deterministic by design** — calculations over structured data, honest `None`
   fallbacks instead of hallucinated answers; the model reasons, never "knows".
 - **Observability** — every run traces agent spans, reads/writes, LLM calls,
-  tokens: SQLite store + web dashboard, exportable to Langfuse/Postgres (async sinks).
+  tokens: SQLite store + web dashboard, exportable to Langfuse/Postgres (async sinks);
+  **correlated logs** (`configure_logging()`, silent until called) carry
+  `run_id`/`session_id`/`agent` on every line.
+- **Lifecycle** — `Budget.max_seconds` is a hard deadline (a hung LLM call is
+  cancelled); `request_stop()`/`ashutdown()` stop at a generation boundary
+  (`RunOutcome.STOPPED`); `active_runs()`/`in_flight` give a readiness view.
 - **MCP, both ways** — call any MCP server's tools as a `Tool`
   (`mcp_stdio_tools`/`mcp_http_tools`), or expose your own `Tool`s and a live
   `Context` as an MCP server (`create_mcp_server`) for Claude Desktop, Claude
@@ -282,7 +288,7 @@ uv run python ./examples/devops/web.py         # HITL ops assistant + trace dash
 ```
 
 Classic-pattern ports run as one-liners too:
-`python -m examples.{reflection,map_reduce,supervisor,summarize,time_travel,plan_execute,adaptive,ledger}.main`.
+`python -m examples.{reflection,map_reduce,supervisor,summarize,time_travel,plan_execute,adaptive,ledger,outbox}.main`.
 
 Prefer a notebook? [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/bzdvdn/reactifact/blob/master/examples/quickstart.ipynb)
 — `examples/quickstart.ipynb` covers the four `quick` cases (`agent`/`rag`/`tools_agent`/`chat_agent`), offline by default.
@@ -297,6 +303,7 @@ Prefer a notebook? [![Open in Colab](https://colab.research.google.com/assets/co
 - `chat` — minimal offline single-model multi-turn conversation (`Conversation` + bounded `ChatMemory`).
 - `forklab` — deterministic branch & merge: two strategies on their own forks, three-way merge.
 - `ledger` — offline proof of reactive recompute: edit one fact, only its real `Consume`rs re-run.
+- `outbox` — one intent, one send: `effects.act(...)` + `Runtime(dispatcher=...)`, safe across replays, retries and merged branches (§42).
 - `llm_ladder` — the workflow from one LLM call to state-changing patches (3 levels).
 - `adaptive` — hybrid scheduler: rule filters + deterministic rank + LLM tie-break + `rank_limit`.
 - `{reflection,map_reduce,supervisor,summarize,time_travel,plan_execute}` — canonical ports (see [port-matrix](docs/en/port-matrix.md)).
@@ -327,7 +334,7 @@ uv sync --extra dev --extra web
 
 ## Status & contributing
 
-Active, `0.13.x`, pre-1.0 — the API is stabilizing and `1.0` will freeze it
+Active, `0.14.x`, pre-1.0 — the API is stabilizing and `1.0` will freeze it
 (see the [roadmap](docs/roadmap.md)); releases follow
 [Keep a Changelog](CHANGELOG.md). Questions and design discussion live in
 [GitHub Discussions](https://github.com/bzdvdn/reactifact/discussions); a star,

{reactifact-0.13.0 → reactifact-0.14.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "reactifact"
-version = "0.13.0"
+version = "0.14.1"
 description = "Reactive, artifact-driven agent runtime: agents transform versioned, typed, provenance-aware artifacts inside an evolving context"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -52,6 +52,9 @@ pg = [
 mcp = [
     "mcp>=2.2",
 ]
+a2a = [
+    "a2a-sdk>=1.0",
+]
 docs = [
     "mkdocs>=1.6",
     "mkdocs-material>=9.5",
@@ -81,6 +84,9 @@ pg = [
 mcp = [
     "mcp>=2.2",
 ]
+a2a = [
+    "a2a-sdk>=1.0",
+]
 docs = [
     "mkdocs>=1.6",
     "mkdocs-material>=9.5",

{reactifact-0.13.0 → reactifact-0.14.1}/reactifact/__init__.py

@@ -29,7 +29,8 @@ 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 .interrupt import PendingAction, PendingQuestion
+from .logging import bind, configure_logging, get_logger
 from .patches import Create, Delete, Link, Patch, Relation, Unlink, Update
 from .produce import Produce, ProduceCall, produce
 from .providers import (
@@ -50,7 +51,7 @@ from .tools import FunctionTool, Tool, ToolOutput, tool
 from .triggers import Trigger
 from .types import register as register_type
 
-__version__ = "0.13.0"
+__version__ = "0.14.1"
 
 __all__ = [
     "Agent",
@@ -73,6 +74,7 @@ __all__ = [
     "Message",
     "MergeConflict",
     "Patch",
+    "PendingAction",
     "PendingQuestion",
     "Produce",
     "ProduceCall",
@@ -95,9 +97,12 @@ __all__ = [
     "Unlink",
     "Update",
     "View",
+    "bind",
+    "configure_logging",
     "consume",
     "create_agent",
     "current_request",
+    "get_logger",
     "produce",
     "register_type",
     "tool",

reactifact-0.14.1/reactifact/a2a/__init__.py

@@ -0,0 +1,77 @@
+"""A2A (Agent2Agent) integration: call remote agents, or serve reactifact ones.
+
+No extra dependency: the client uses `httpx` (core), the server uses FastAPI
+from the existing `web` extra and imports it lazily — so importing this package
+never needs FastAPI.
+
+- Client (`reactifact.a2a.client`): `A2AClient` (Agent Card + `message/send`,
+  `message/stream`, `tasks/get`, `tasks/cancel`) and `A2AAgentTool`/`a2a_tool`,
+  a reactifact `Tool` that delegates to a remote agent.
+- Server (`reactifact.a2a.server`): `create_a2a_router(agents, ...)` — an Agent
+  Card plus a JSON-RPC endpoint where a `Task` is a conversation and a HITL
+  `PendingQuestion` maps to `input-required`.
+
+The JSON-RPC binding implements the A2A `0.3` wire shape (camelCase fields,
+`kind`-discriminated parts).
+"""
+
+from __future__ import annotations
+
+from .client import (
+    AGENT_CARD_PATH,
+    LEGACY_AGENT_CARD_PATH,
+    A2AAgentTool,
+    A2AClient,
+    A2AError,
+    a2a_tool,
+)
+from .models import (
+    AgentCapabilities,
+    AgentCard,
+    AgentProvider,
+    AgentSkill,
+    Artifact,
+    ErrorCode,
+    JSONRPCError,
+    JSONRPCRequest,
+    JSONRPCResponse,
+    Message,
+    MessageSendParams,
+    Part,
+    Task,
+    TaskState,
+    TaskStatus,
+    UserMessage,
+)
+from .remote import A2ARemoteProduce, remote_agent
+from .server import create_a2a_router, default_create_message, default_reply
+
+__all__ = [
+    "AGENT_CARD_PATH",
+    "LEGACY_AGENT_CARD_PATH",
+    "A2AAgentTool",
+    "A2AClient",
+    "A2AError",
+    "A2ARemoteProduce",
+    "AgentCapabilities",
+    "AgentCard",
+    "AgentProvider",
+    "AgentSkill",
+    "Artifact",
+    "ErrorCode",
+    "JSONRPCError",
+    "JSONRPCRequest",
+    "JSONRPCResponse",
+    "Message",
+    "MessageSendParams",
+    "Part",
+    "Task",
+    "TaskState",
+    "TaskStatus",
+    "UserMessage",
+    "a2a_tool",
+    "create_a2a_router",
+    "default_create_message",
+    "default_reply",
+    "remote_agent",
+]

reactifact-0.14.1/reactifact/a2a/client.py

@@ -0,0 +1,282 @@
+"""A2A client: call a remote Agent2Agent server, and expose one as a `Tool`.
+
+Speaks the JSON-RPC binding (v0.3 shape) over `httpx` — no extra dependency.
+Two ways to consume a remote agent:
+
+- `A2AClient` — the low-level protocol surface (`fetch_agent_card`, `send`,
+  `stream`, `get_task`, `cancel_task`), returning the A2A `Task`/`Message`.
+- `A2AAgentTool` / `a2a_tool` — a reactifact `Tool` wrapping a remote agent, so
+  an `LLMAgent` can delegate to it: `message/send`, then the reply's text (or
+  the task's artifact) becomes the tool result.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Any
+from urllib.parse import urlsplit
+from uuid import uuid4
+
+import httpx
+
+from .._httpx import LoopBoundClient
+from ..tools import Tool, ToolOutput
+from .models import (
+    AgentCard,
+    ErrorCode,
+    JSONRPCRequest,
+    JSONRPCResponse,
+    Message,
+    MessageSendParams,
+    Task,
+    TaskIdParams,
+    TaskQueryParams,
+)
+
+#: Well-known Agent Card paths (v0.3 recommends `agent-card.json`; v0.2 used
+#: `agent.json` — the server serves both).
+AGENT_CARD_PATH = "/.well-known/agent-card.json"
+LEGACY_AGENT_CARD_PATH = "/.well-known/agent.json"
+
+
+class A2AError(Exception):
+    """A remote A2A server returned a JSON-RPC error."""
+
+    def __init__(self, code: int, message: str, data: Any = None) -> None:
+        self.code = code
+        self.message = message
+        self.data = data
+        super().__init__(f"A2A error {code}: {message}")
+
+
+def _default_card_url(url: str) -> str:
+    parts = urlsplit(url)
+    origin = f"{parts.scheme}://{parts.netloc}"
+    return origin + AGENT_CARD_PATH
+
+
+def _as_message(
+    value: str | Message, *, task_id: str | None, context_id: str | None
+) -> Message:
+    if isinstance(value, Message):
+        message = value.model_copy()
+        if task_id is not None:
+            message.taskId = task_id
+        if context_id is not None:
+            message.contextId = context_id
+        return message
+    return Message.user(value, taskId=task_id, contextId=context_id)
+
+
+def _parse_result(result: Any) -> Task | Message | dict[str, Any]:
+    """Reads a `message/send`/`stream` result into its typed model."""
+    if isinstance(result, dict):
+        kind = result.get("kind")
+        if kind == "task":
+            return Task.model_validate(result)
+        if kind == "message":
+            return Message.model_validate(result)
+        return result
+    return {}
+
+
+class A2AClient:
+    """A JSON-RPC A2A client for one server `url`.
+
+    `url` is the JSON-RPC endpoint from the server's Agent Card; the card is
+    fetched from the well-known path on the same origin unless `card_url` is
+    given. `headers` are sent on every request (auth lives here, per the spec:
+    credentials travel in HTTP headers, not in A2A messages). Pass `client=` to
+    inject an `httpx.AsyncClient` (tests, a custom transport).
+    """
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        card_url: str | None = None,
+        headers: dict[str, str] | None = None,
+        timeout: float = 30.0,
+        client: Any | None = None,
+    ) -> None:
+        self.url = url.rstrip("/")
+        self.card_url = card_url or _default_card_url(self.url)
+        self._headers = {"Content-Type": "application/json", **(headers or {})}
+        self._http = LoopBoundClient(
+            lambda: httpx.AsyncClient(timeout=timeout, headers=self._headers),
+            client=client,
+        )
+
+    async def fetch_agent_card(self) -> AgentCard:
+        response = await self._http.get().get(self.card_url)
+        response.raise_for_status()
+        return AgentCard.model_validate(response.json())
+
+    async def _rpc(self, method: str, params: dict[str, Any]) -> Any:
+        payload = JSONRPCRequest(
+            id=uuid4().hex, method=method, params=params
+        ).model_dump(mode="json")
+        response = await self._http.get().post(self.url, json=payload)
+        response.raise_for_status()
+        envelope = JSONRPCResponse.model_validate(response.json())
+        if envelope.error is not None:
+            raise A2AError(
+                envelope.error.code, envelope.error.message, envelope.error.data
+            )
+        return envelope.result
+
+    async def send(
+        self,
+        message: str | Message,
+        *,
+        task_id: str | None = None,
+        context_id: str | None = None,
+        blocking: bool = True,
+    ) -> Task | Message:
+        """`message/send` → the task state (or a direct reply `Message`)."""
+        params = MessageSendParams(
+            message=_as_message(message, task_id=task_id, context_id=context_id),
+            configuration=None if blocking else {"blocking": False},
+        )
+        result = _parse_result(
+            await self._rpc("message/send", params.model_dump(mode="json"))
+        )
+        if not isinstance(result, (Task, Message)):
+            raise A2AError(ErrorCode.INTERNAL_ERROR, "unexpected message/send result")
+        return result
+
+    async def stream(
+        self,
+        message: str | Message,
+        *,
+        task_id: str | None = None,
+        context_id: str | None = None,
+    ) -> AsyncIterator[Task | Message | dict[str, Any]]:
+        """`message/stream` → an async iterator of task/message/update events."""
+        params = MessageSendParams(
+            message=_as_message(message, task_id=task_id, context_id=context_id)
+        )
+        payload = JSONRPCRequest(
+            id=uuid4().hex,
+            method="message/stream",
+            params=params.model_dump(mode="json"),
+        ).model_dump(mode="json")
+        client = self._http.get()
+        async with client.stream("POST", self.url, json=payload) as response:
+            response.raise_for_status()
+            async for line in response.aiter_lines():
+                if not line.startswith("data:"):
+                    continue
+                data = line[len("data:") :].strip()
+                if not data or data == "[DONE]":
+                    continue
+                envelope = JSONRPCResponse.model_validate_json(data)
+                if envelope.error is not None:
+                    raise A2AError(
+                        envelope.error.code,
+                        envelope.error.message,
+                        envelope.error.data,
+                    )
+                yield _parse_result(envelope.result)
+
+    async def get_task(
+        self, task_id: str, *, history_length: int | None = None
+    ) -> Task:
+        params = TaskQueryParams(id=task_id, historyLength=history_length)
+        return Task.model_validate(
+            await self._rpc("tasks/get", params.model_dump(mode="json"))
+        )
+
+    async def cancel_task(self, task_id: str) -> Task:
+        params = TaskIdParams(id=task_id)
+        return Task.model_validate(
+            await self._rpc("tasks/cancel", params.model_dump(mode="json"))
+        )
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+
+def _task_reply_text(task: Task) -> str:
+    if task.status.message is not None and task.status.message.text:
+        return task.status.message.text
+    return "\n".join(
+        part.as_text() for artifact in task.artifacts for part in artifact.parts
+    )
+
+
+class A2AAgentTool(Tool):
+    """A reactifact `Tool` that delegates to a remote A2A agent.
+
+    The tool takes a single `message` string, sends it with `message/send`, and
+    returns the reply text (the task's status message, else its artifacts) — so
+    an `LLMAgent` can call another agent the way it calls any tool.
+    """
+
+    def __init__(
+        self,
+        target: str | A2AClient,
+        *,
+        name: str = "a2a_agent",
+        description: str | None = None,
+        card_url: str | None = None,
+        headers: dict[str, str] | None = None,
+        client: Any | None = None,
+    ) -> None:
+        self.client = (
+            target
+            if isinstance(target, A2AClient)
+            else A2AClient(target, card_url=card_url, headers=headers, client=client)
+        )
+        self.name = name
+        self.description = description or (
+            f"Send a request to the A2A agent at {self.client.url} and get its reply."
+        )
+        self.schema = {
+            "type": "object",
+            "properties": {
+                "message": {
+                    "type": "string",
+                    "description": "The request to send to the remote agent.",
+                }
+            },
+            "required": ["message"],
+        }
+
+    async def execute(self, args: dict[str, Any]) -> ToolOutput:
+        text = str(args.get("message", "")).strip()
+        if not text:
+            return ToolOutput(error="'message' is required")
+        try:
+            result = await self.client.send(text)
+        except A2AError as exc:
+            return ToolOutput(error=str(exc))
+        if isinstance(result, Task):
+            return ToolOutput(text=_task_reply_text(result), data=result.model_dump())
+        if isinstance(result, Message):
+            return ToolOutput(text=result.text, data=result.model_dump())
+        return ToolOutput(text="", data=result)
+
+
+def a2a_tool(
+    url: str,
+    *,
+    name: str = "a2a_agent",
+    description: str | None = None,
+    card_url: str | None = None,
+    headers: dict[str, str] | None = None,
+) -> A2AAgentTool:
+    """Builds an `A2AAgentTool` for the server at `url` (convenience wrapper)."""
+    return A2AAgentTool(
+        url, name=name, description=description, card_url=card_url, headers=headers
+    )
+
+
+__all__ = [
+    "AGENT_CARD_PATH",
+    "LEGACY_AGENT_CARD_PATH",
+    "A2AAgentTool",
+    "A2AClient",
+    "A2AError",
+    "a2a_tool",
+]