reactifact 0.6.0__tar.gz → 0.7.0__tar.gz

{reactifact-0.6.0 → reactifact-0.7.0}/PKG-INFO

@@ -1,10 +1,21 @@
 Metadata-Version: 2.4
 Name: reactifact
-Version: 0.6.0
+Version: 0.7.0
 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
 Project-URL: Repository, https://github.com/bzdvdn/reactifact
 Project-URL: Documentation, https://github.com/bzdvdn/reactifact/tree/master/docs
+Project-URL: Changelog, https://github.com/bzdvdn/reactifact/blob/master/CHANGELOG.md
+Keywords: agents,llm,ai-agents,reactive,provenance,orchestration,agentic
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -21,16 +32,22 @@ Requires-Dist: fastapi>=0.115; extra == "web"
 Requires-Dist: uvicorn[standard]>=0.30; extra == "web"
 Provides-Extra: pg
 Requires-Dist: psycopg[binary]>=3.2; extra == "pg"
+Provides-Extra: mcp
+Requires-Dist: mcp>=2.2; extra == "mcp"
 Dynamic: license-file
 
-# reactifact
+<p align="center">
+  <img src="docs/img/reactifact-hero.png" alt="reactifact — Agents that react to artifacts, not graphs" width="800">
+</p>
 
 **Stop drawing the graph. Build agents as reactions to versioned, provable artifacts.**
 
 [![CI](https://github.com/bzdvdn/reactifact/actions/workflows/ci.yml/badge.svg)](https://github.com/bzdvdn/reactifact/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/bzdvdn/reactifact/graph/badge.svg)](https://codecov.io/gh/bzdvdn/reactifact)
 [![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue)](https://github.com/bzdvdn/reactifact)
 [![PyPI version](https://img.shields.io/pypi/v/reactifact)](https://pypi.org/project/reactifact/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/bzdvdn/reactifact)
 
 Most agent frameworks make you **draw the graph**: connect nodes, wire memory,
 declare control flow. But a knowledge question — *"why did infra costs jump in
@@ -41,6 +58,13 @@ reactifact flips the model. You describe **what artifacts exist and what agents
 do with them**; the runtime derives what runs next from **state changes**. Agents
 react to events — there is no graph, no node pipeline.
 
+![Left: a hand-wired fetch → verify → answer pipeline. Right: reactifact — search_agent and answer_agent each declare only what they consume and produce, wired together by Context, never each other.](docs/img/wiring.svg)
+
+Two agents explore independently on their own forks and merge back automatically
+— and when they disagree, reactifact refuses to merge silently:
+
+![forklab demo: two strategies (depth/breadth) investigate on separate forks and merge cleanly; a second run edits the same artifact on both forks and reactifact raises MergeConflict instead of guessing, then re-merges under an explicit policy.](docs/img/forklab-demo.gif)
+
 ```bash
 pip install reactifact
 ```
@@ -107,6 +131,12 @@ print(answer.data.text)                     # "Refunds are available within 14 d
 print("supported_by:", evidence.data.text)  # provenance you can trace, not just a string in a log
 ```
 
+The same idea, live — the [`knowledge`](examples/knowledge) example's CLI answering a
+harder, multi-source question (docs + a CSV) with a real computed number and
+its sources, no LLM key required:
+
+![CLI demo: asking "how much does gpu cost in total?" — the runtime searches docs and a spreadsheet, computes the sum, verifies it, and answers with sources.](docs/img/knowledge-cli-demo.gif)
+
 ## How it works
 
 ```text
@@ -136,12 +166,33 @@ actual state.
 | Retries/rollback are manual | Context is **git-like versioned** (diff, rollback, branch, merge) |
 | "Who produced this?" is lost | **Provenance** links every derived artifact to its inputs |
 | The model guesses the numbers | **Calculations are calculated** — the LLM is a reasoning component, not the source of truth |
+| Tracing needs a SaaS add-on | **Native trace store** (SQLite + dashboard), exportable to Langfuse/Postgres |
+| MCP via a framework adapter | **MCP both ways** built in — call any server, or expose your own `Context` as one |
+| Pulls in a framework's dependency tree | **3 core deps**: `pydantic`, `httpx`, `python-dotenv` |
 
 Reactive. Deterministic. Accountable.
 
 Full breakdown, including where reactifact is *not* the right choice:
 [docs/en/comparison.md](docs/en/comparison.md).
 
+**Proof, not a claim** — [`examples/ledger`](examples/ledger) is a 4-artifact
+billing calc (`LaborCost`, `Tax`, `Discount`, `Total`) with no LLM, fully
+offline. Edit *one* fact and see what actually reruns:
+
+```text
+>>> editing ONLY TaxRate (0.08 -> 0.12) — a fact nothing about
+>>> LaborCost or Discount ever consumed.
+
+  LaborCost    value=500.0      version=0   # untouched
+  Tax          value=60.0       version=1   # recomputed
+  Discount     value=25.0       version=0   # untouched
+  Total        value=535.0      version=1   # recomputed
+```
+
+2 of 4 artifacts recompute — the 2 that actually depend on `TaxRate` —
+because `Artifact.version` tracks real consumption, not a graph edge you drew
+by hand. Run it yourself: `uv run python -m examples.ledger.main`.
+
 ## Core primitives
 
 - **Context** — versioned working state, git-like commits, `diff`/`rollback`/`merge`.
@@ -149,7 +200,7 @@ Full breakdown, including where reactifact is *not* the right choice:
 - **Effects** — an agent states its change via `self.effects.create/update/link/ask`; the runtime compiles it.
 - **Patch** — the compiled, validated change-set applied as one atomic commit.
 - **Agent** — a thin container declaring `consumes`/`produces`; logic lives in a `Produce`.
-- **Source** — retrieval is a capability: vector search is *one* strategy; direct API, keyword, SQL, filesystem are equally first-class.
+- **Source** — retrieval is a capability: vector search is *one* strategy, not the only one; filesystem, CSV, and the web are equally first-class today (direct API, keyword, and SQL sources are on the [roadmap](docs/roadmap.md#next), not yet shipped).
 - **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.
@@ -160,6 +211,10 @@ Full breakdown, including where reactifact is *not* the right choice:
   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).
+- **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
+  Code, or another agent to call into (`mcp` extra).
 - **Budgets & replanning** — cap by runs/time/iterations/tool-calls, replan on decline.
 - **Branching & replay** — `context.branch()`, three-way `merge()`, deterministic
   `ReplayLLM`, all for audit and safe alternative states.
@@ -186,7 +241,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,adaptive,ledger}.main`.
+`python -m examples.{reflection,map_reduce,supervisor,summarize,time_travel,plan_execute,adaptive,ledger}.main`.
 
 ## Examples (in-repo, not shipped)
 
@@ -199,7 +254,7 @@ Classic-pattern ports run as one-liners too:
 - `ledger` — offline proof of reactive recompute: edit one fact, only its real `Consume`rs re-run.
 - `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}` — canonical ports (see [port-matrix](docs/en/port-matrix.md)).
+- `{reflection,map_reduce,supervisor,summarize,time_travel,plan_execute}` — canonical ports (see [port-matrix](docs/en/port-matrix.md)).
 
 ## Documentation
 
@@ -211,6 +266,7 @@ Classic-pattern ports run as one-liners too:
 - [Comparison](docs/en/comparison.md) — reactifact vs LangGraph/CrewAI, feature by feature, and when *not* to use reactifact.
 - [Tutorial · llm-ladder](docs/en/examples.md#tutorial-ladder) — learn the workflow.
 - [docs/constitution.md](docs/constitution.md) — the full design rationale and invariants.
+- [Roadmap](docs/roadmap.md) — what's next, and what's deliberately out of scope.
 
 ## Development
 

reactifact-0.6.0/reactifact.egg-info/PKG-INFO → reactifact-0.7.0/README.md

@@ -1,36 +1,15 @@
-Metadata-Version: 2.4
-Name: reactifact
-Version: 0.6.0
-Summary: Reactive, artifact-driven agent runtime: agents transform versioned, typed, provenance-aware artifacts inside an evolving context
-Project-URL: Homepage, https://github.com/bzdvdn/reactifact
-Project-URL: Repository, https://github.com/bzdvdn/reactifact
-Project-URL: Documentation, https://github.com/bzdvdn/reactifact/tree/master/docs
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: pydantic>=2.13.4
-Requires-Dist: httpx>=0.27
-Requires-Dist: python-dotenv>=1.0
-Provides-Extra: dev
-Requires-Dist: ruff>=0.8; extra == "dev"
-Requires-Dist: mypy>=1.11; extra == "dev"
-Requires-Dist: pytest>=9.1.1; extra == "dev"
-Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
-Provides-Extra: web
-Requires-Dist: fastapi>=0.115; extra == "web"
-Requires-Dist: uvicorn[standard]>=0.30; extra == "web"
-Provides-Extra: pg
-Requires-Dist: psycopg[binary]>=3.2; extra == "pg"
-Dynamic: license-file
-
-# reactifact
+<p align="center">
+  <img src="docs/img/reactifact-hero.png" alt="reactifact — Agents that react to artifacts, not graphs" width="800">
+</p>
 
 **Stop drawing the graph. Build agents as reactions to versioned, provable artifacts.**
 
 [![CI](https://github.com/bzdvdn/reactifact/actions/workflows/ci.yml/badge.svg)](https://github.com/bzdvdn/reactifact/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/bzdvdn/reactifact/graph/badge.svg)](https://codecov.io/gh/bzdvdn/reactifact)
 [![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue)](https://github.com/bzdvdn/reactifact)
 [![PyPI version](https://img.shields.io/pypi/v/reactifact)](https://pypi.org/project/reactifact/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/bzdvdn/reactifact)
 
 Most agent frameworks make you **draw the graph**: connect nodes, wire memory,
 declare control flow. But a knowledge question — *"why did infra costs jump in
@@ -41,6 +20,13 @@ reactifact flips the model. You describe **what artifacts exist and what agents
 do with them**; the runtime derives what runs next from **state changes**. Agents
 react to events — there is no graph, no node pipeline.
 
+![Left: a hand-wired fetch → verify → answer pipeline. Right: reactifact — search_agent and answer_agent each declare only what they consume and produce, wired together by Context, never each other.](docs/img/wiring.svg)
+
+Two agents explore independently on their own forks and merge back automatically
+— and when they disagree, reactifact refuses to merge silently:
+
+![forklab demo: two strategies (depth/breadth) investigate on separate forks and merge cleanly; a second run edits the same artifact on both forks and reactifact raises MergeConflict instead of guessing, then re-merges under an explicit policy.](docs/img/forklab-demo.gif)
+
 ```bash
 pip install reactifact
 ```
@@ -107,6 +93,12 @@ print(answer.data.text)                     # "Refunds are available within 14 d
 print("supported_by:", evidence.data.text)  # provenance you can trace, not just a string in a log
 ```
 
+The same idea, live — the [`knowledge`](examples/knowledge) example's CLI answering a
+harder, multi-source question (docs + a CSV) with a real computed number and
+its sources, no LLM key required:
+
+![CLI demo: asking "how much does gpu cost in total?" — the runtime searches docs and a spreadsheet, computes the sum, verifies it, and answers with sources.](docs/img/knowledge-cli-demo.gif)
+
 ## How it works
 
 ```text
@@ -136,12 +128,33 @@ actual state.
 | Retries/rollback are manual | Context is **git-like versioned** (diff, rollback, branch, merge) |
 | "Who produced this?" is lost | **Provenance** links every derived artifact to its inputs |
 | The model guesses the numbers | **Calculations are calculated** — the LLM is a reasoning component, not the source of truth |
+| Tracing needs a SaaS add-on | **Native trace store** (SQLite + dashboard), exportable to Langfuse/Postgres |
+| MCP via a framework adapter | **MCP both ways** built in — call any server, or expose your own `Context` as one |
+| Pulls in a framework's dependency tree | **3 core deps**: `pydantic`, `httpx`, `python-dotenv` |
 
 Reactive. Deterministic. Accountable.
 
 Full breakdown, including where reactifact is *not* the right choice:
 [docs/en/comparison.md](docs/en/comparison.md).
 
+**Proof, not a claim** — [`examples/ledger`](examples/ledger) is a 4-artifact
+billing calc (`LaborCost`, `Tax`, `Discount`, `Total`) with no LLM, fully
+offline. Edit *one* fact and see what actually reruns:
+
+```text
+>>> editing ONLY TaxRate (0.08 -> 0.12) — a fact nothing about
+>>> LaborCost or Discount ever consumed.
+
+  LaborCost    value=500.0      version=0   # untouched
+  Tax          value=60.0       version=1   # recomputed
+  Discount     value=25.0       version=0   # untouched
+  Total        value=535.0      version=1   # recomputed
+```
+
+2 of 4 artifacts recompute — the 2 that actually depend on `TaxRate` —
+because `Artifact.version` tracks real consumption, not a graph edge you drew
+by hand. Run it yourself: `uv run python -m examples.ledger.main`.
+
 ## Core primitives
 
 - **Context** — versioned working state, git-like commits, `diff`/`rollback`/`merge`.
@@ -149,7 +162,7 @@ Full breakdown, including where reactifact is *not* the right choice:
 - **Effects** — an agent states its change via `self.effects.create/update/link/ask`; the runtime compiles it.
 - **Patch** — the compiled, validated change-set applied as one atomic commit.
 - **Agent** — a thin container declaring `consumes`/`produces`; logic lives in a `Produce`.
-- **Source** — retrieval is a capability: vector search is *one* strategy; direct API, keyword, SQL, filesystem are equally first-class.
+- **Source** — retrieval is a capability: vector search is *one* strategy, not the only one; filesystem, CSV, and the web are equally first-class today (direct API, keyword, and SQL sources are on the [roadmap](docs/roadmap.md#next), not yet shipped).
 - **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.
@@ -160,6 +173,10 @@ Full breakdown, including where reactifact is *not* the right choice:
   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).
+- **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
+  Code, or another agent to call into (`mcp` extra).
 - **Budgets & replanning** — cap by runs/time/iterations/tool-calls, replan on decline.
 - **Branching & replay** — `context.branch()`, three-way `merge()`, deterministic
   `ReplayLLM`, all for audit and safe alternative states.
@@ -186,7 +203,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,adaptive,ledger}.main`.
+`python -m examples.{reflection,map_reduce,supervisor,summarize,time_travel,plan_execute,adaptive,ledger}.main`.
 
 ## Examples (in-repo, not shipped)
 
@@ -199,7 +216,7 @@ Classic-pattern ports run as one-liners too:
 - `ledger` — offline proof of reactive recompute: edit one fact, only its real `Consume`rs re-run.
 - `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}` — canonical ports (see [port-matrix](docs/en/port-matrix.md)).
+- `{reflection,map_reduce,supervisor,summarize,time_travel,plan_execute}` — canonical ports (see [port-matrix](docs/en/port-matrix.md)).
 
 ## Documentation
 
@@ -211,6 +228,7 @@ Classic-pattern ports run as one-liners too:
 - [Comparison](docs/en/comparison.md) — reactifact vs LangGraph/CrewAI, feature by feature, and when *not* to use reactifact.
 - [Tutorial · llm-ladder](docs/en/examples.md#tutorial-ladder) — learn the workflow.
 - [docs/constitution.md](docs/constitution.md) — the full design rationale and invariants.
+- [Roadmap](docs/roadmap.md) — what's next, and what's deliberately out of scope.
 
 ## Development
 

{reactifact-0.6.0 → reactifact-0.7.0}/pyproject.toml

@@ -4,10 +4,23 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "reactifact"
-version = "0.6.0"
+version = "0.7.0"
 description = "Reactive, artifact-driven agent runtime: agents transform versioned, typed, provenance-aware artifacts inside an evolving context"
 readme = "README.md"
 requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["agents", "llm", "ai-agents", "reactive", "provenance", "orchestration", "agentic"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
 dependencies = [
     "pydantic>=2.13.4",
     "httpx>=0.27",
@@ -18,6 +31,7 @@ dependencies = [
 Homepage = "https://github.com/bzdvdn/reactifact"
 Repository = "https://github.com/bzdvdn/reactifact"
 Documentation = "https://github.com/bzdvdn/reactifact/tree/master/docs"
+Changelog = "https://github.com/bzdvdn/reactifact/blob/master/CHANGELOG.md"
 
 [project.optional-dependencies]
 dev = [
@@ -33,10 +47,16 @@ web = [
 pg = [
     "psycopg[binary]>=3.2",
 ]
+mcp = [
+    "mcp>=2.2",
+]
 
 # uv-native groups mirror the extras so `uv run`/`uv sync` installs the web demo
 # deps by default (no `--extra` flag needed to boot the examples). Extras stay
-# for PyPI (`pip install reactifact[web]`).
+# for PyPI (`pip install reactifact[web]`). `mcp` joins the default groups too —
+# unlike `pg`, its tests need no external service (in-memory MCP transport), so
+# there's no reason not to run them for real in CI. `pg` stays opt-in; its own
+# test only checks the graceful ImportError path without psycopg installed.
 [dependency-groups]
 dev = [
     "ruff>=0.8",
@@ -51,9 +71,12 @@ web = [
 pg = [
     "psycopg[binary]>=3.2",
 ]
+mcp = [
+    "mcp>=2.2",
+]
 
 [tool.uv]
-default-groups = ["dev", "web"]
+default-groups = ["dev", "web", "mcp"]
 
 # Публикация: в wheel едет только пакет `reactifact`; examples/tests остаются
 # в репозитории для демо и разработки, но не попадают в дистрибутив.
@@ -70,6 +93,15 @@ reactifact = ["py.typed"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 
+# Enforced by CI's `pytest --cov=reactifact --cov-fail-under=85` (see
+# .github/workflows/ci.yml). Current coverage is ~90%; 85% leaves headroom
+# for `reactifact/tracing/postgres.py`, whose own test intentionally only
+# checks the graceful-ImportError path without `psycopg` installed (`pg` is
+# an opt-in extra with no external service in CI) rather than needing a
+# per-file carve-out.
+[tool.coverage.report]
+fail_under = 85
+
 [tool.ruff]
 target-version = "py311"
 line-length = 88

{reactifact-0.6.0 → reactifact-0.7.0}/reactifact/__init__.py

@@ -48,7 +48,7 @@ from .session import Session, SessionStore
 from .tools import FunctionTool, Tool, ToolOutput, tool
 from .triggers import Trigger
 
-__version__ = "0.6.0"
+__version__ = "0.7.0"
 
 __all__ = [
     "Agent",

{reactifact-0.6.0 → reactifact-0.7.0}/reactifact/branching.py

@@ -5,8 +5,12 @@
 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:
+HITL surface. Application code should call the `Context` methods (see
+[docs/en/branching.md](../docs/en/branching.md)); these module-level
+functions are exported for building on `Context` without one already in
+hand (e.g. `BranchStore`'s own load/merge path below), not as an equally
+first-class alternative entry point. `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")
@@ -91,13 +95,8 @@ def merge_context_from(target: Context, other: Context) -> None:
                 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))
+            target.create(new_data, id=other_id)
+            operations.append(Create(new_data, id=other_id))
     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)

{reactifact-0.6.0 → reactifact-0.7.0}/reactifact/effects.py

@@ -128,14 +128,24 @@ class Effects:
     def upsert(self, data: Any, *, id: str) -> Handle:
         """Explicit create-or-refresh: same effect as `create(data, id=id)`.
 
-        Prefer this over `create(..., id=...)` when the artifact may already
-        exist (e.g. a re-derived id like `f"answer:{qid}"`) — it says at the
-        call site that an update is an expected outcome, not a surprise.
+        Purely a call-site name: identical to `create(..., id=...)`, but says
+        at the call site that a refresh is an expected outcome, not a
+        surprise — reach for it when the artifact may already exist (e.g. a
+        re-derived id like `f"answer:{qid}"`).
         """
         return self.create(data, id=id)
 
     def update(self, artifact: Artifact[Any], **fields: Any) -> Effects:
-        """Bumps fields of an *existing* artifact (a new version)."""
+        """Bumps fields of an *existing* artifact (a new version).
+
+        Note the name means something different here than on `Patch.update`/
+        `Context.update`/`Artifact.update` (a full data replacement) — this is
+        the one intentional exception, matching `Patch.update_fields`
+        instead. `Effects` is the everyday authoring surface where "update
+        some fields" is the common case (§18 above), so it gets the short
+        name; the lower-level, less-used `Patch`/`Context`/`Artifact` surface
+        keeps `update` for the operation it's actually named after.
+        """
         new_data = artifact.data.model_copy(update=fields)
         self.operations.append(Update(artifact.id, new_data))
         return self

{reactifact-0.6.0 → reactifact-0.7.0}/reactifact/llm_agent.py

@@ -25,7 +25,7 @@ from .events import Event
 from .interrupt import PendingQuestion
 from .produce import Produce
 from .structured import SYSTEM_STRUCTURED, structured_llm
-from .tool_use import Observation, ToolAnswer, ToolUse, ToolUseHITL
+from .tool_use import DeferredToolGroup, Observation, ToolAnswer, ToolUse, ToolUseHITL
 from .tools import Tool
 
 
@@ -98,6 +98,7 @@ class LLMAgent(Agent):
     max_steps: int = 8
     temperature: float | None = None
     max_tokens: int | None = None
+    deferred_tool_groups: Sequence[DeferredToolGroup] = ()
 
     def __init__(self, *, name: str | None = None, **kwargs: Any):
         llm_name = name or self.name or self.__class__.__name__.lower()
@@ -116,6 +117,7 @@ class LLMAgent(Agent):
                 max_steps=self.max_steps,
                 temperature=self.temperature,
                 max_tokens=self.max_tokens,
+                deferred_tool_groups=self.deferred_tool_groups,
             ),
             Produce(ToolAnswer),
             *user_produces,

reactifact-0.7.0/reactifact/mcp/__init__.py

@@ -0,0 +1,21 @@
+"""MCP integration: talk to external MCP servers, or serve reactifact `Tool`s
+and `Context` artifacts as one. Requires the `mcp` extra — nothing here is
+imported by reactifact's core, so a bare `pip install reactifact` never pulls
+in the `mcp` SDK.
+"""
+
+from __future__ import annotations
+
+from .client import MCPTool, mcp_http_tools, mcp_stdio_tools, mcp_tools
+from .oauth import InMemoryTokenStorage, oauth_client_credentials
+from .server import create_mcp_server
+
+__all__ = [
+    "InMemoryTokenStorage",
+    "MCPTool",
+    "create_mcp_server",
+    "mcp_http_tools",
+    "mcp_stdio_tools",
+    "mcp_tools",
+    "oauth_client_credentials",
+]

reactifact-0.7.0/reactifact/mcp/client.py

@@ -0,0 +1,133 @@
+"""MCP client: turns tools exposed by an external MCP server into `Tool`s, so
+`ToolUse`/`ToolUseHITL`/`LLMAgent` call remote MCP tools the same way they
+call local ones — no separate code path for "MCP tool" vs. `@tool`. Requires
+the `mcp` extra.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+from contextlib import AsyncExitStack, asynccontextmanager
+from typing import Any
+
+from .._extras import require_extra
+from ..tools import Tool, ToolOutput
+
+
+class MCPTool(Tool):
+    """One tool from a connected `mcp.ClientSession`, wrapped as a `Tool`."""
+
+    def __init__(
+        self,
+        session: Any,
+        *,
+        name: str,
+        description: str,
+        schema: dict[str, Any],
+        destructive: bool = False,
+    ):
+        self._session = session
+        self.name = name
+        self.description = description
+        self.schema = schema
+        self.destructive = destructive
+
+    async def execute(self, args: dict[str, Any]) -> ToolOutput:
+        result = await self._session.call_tool(self.name, args)
+        return _to_tool_output(result)
+
+
+def _to_tool_output(result: Any) -> ToolOutput:
+    texts = [block.text for block in result.content if getattr(block, "text", None)]
+    text = "\n".join(texts)
+    if result.is_error:
+        return ToolOutput(text=text, error=text or "MCP tool call failed")
+    data = dict(result.structured_content) if result.structured_content else {}
+    return ToolOutput(text=text, data=data)
+
+
+async def mcp_tools(session: Any) -> list[Tool]:
+    """Lists tools on a connected, initialized `mcp.ClientSession` and wraps each as a `Tool`."""
+    listed = await session.list_tools()
+    return [
+        MCPTool(
+            session,
+            name=t.name,
+            description=t.description or t.name,
+            schema=t.input_schema,
+            destructive=bool(t.annotations and t.annotations.destructive_hint),
+        )
+        for t in listed.tools
+    ]
+
+
+@asynccontextmanager
+async def mcp_stdio_tools(
+    command: str,
+    args: list[str] | None = None,
+    *,
+    env: dict[str, str] | None = None,
+) -> AsyncGenerator[list[Tool], None]:
+    """Spawns an MCP server over stdio and yields its tools as `Tool`s.
+
+    Example: `mcp_stdio_tools("npx", ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"])`.
+    The connection stays open for the `async with` block; tools called after
+    it exits will fail.
+    """
+    require_extra("mcp_stdio_tools", "mcp", "mcp")
+    from mcp.client.stdio import StdioServerParameters, stdio_client
+
+    from mcp import ClientSession
+
+    params = StdioServerParameters(command=command, args=args or [], env=env)
+    async with (
+        stdio_client(params) as (read, write),
+        ClientSession(read, write) as session,
+    ):
+        await session.initialize()
+        yield await mcp_tools(session)
+
+
+@asynccontextmanager
+async def mcp_http_tools(
+    url: str,
+    *,
+    headers: dict[str, str] | None = None,
+    auth: Any = None,
+) -> AsyncGenerator[list[Tool], None]:
+    """Connects to an MCP server over streamable HTTP and yields its tools as
+    `Tool`s.
+
+    Pass `headers` for servers that require a static credential (e.g.
+    `{"Authorization": "Bearer ..."}`), or `auth` (an `httpx2.Auth`) for a
+    server that requires OAuth — see `reactifact.mcp.oauth_client_credentials`
+    for the machine-to-machine case. The SDK's `streamable_http_client` has
+    no `headers=`/`auth=` kwarg of its own; the documented way is a
+    pre-configured client, which this builds (and owns/closes) with the same
+    recommended timeouts the SDK's own default client uses (30s
+    connect/write/pool, 300s read — a server may hold a response stream
+    open). Note this must be `httpx2.AsyncClient` (the MCP SDK's own httpx
+    fork/dependency, not plain `httpx` — `streamable_http_client` rejects
+    the wrong one at the type level), imported lazily here since it's only
+    guaranteed installed alongside the `mcp` extra.
+    """
+    require_extra("mcp_http_tools", "mcp", "mcp")
+    import httpx2
+    from mcp.client.streamable_http import streamable_http_client
+
+    from mcp import ClientSession
+
+    async with AsyncExitStack() as stack:
+        http_client = None
+        if headers is not None or auth is not None:
+            http_client = await stack.enter_async_context(
+                httpx2.AsyncClient(
+                    headers=headers, auth=auth, timeout=httpx2.Timeout(30.0, read=300.0)
+                )
+            )
+        read, write = await stack.enter_async_context(
+            streamable_http_client(url, http_client=http_client)
+        )
+        session = await stack.enter_async_context(ClientSession(read, write))
+        await session.initialize()
+        yield await mcp_tools(session)