reactifact 0.9.1__tar.gz → 0.11.0__tar.gz

{reactifact-0.9.1/reactifact.egg-info → reactifact-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reactifact
-Version: 0.9.1
+Version: 0.11.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
@@ -46,7 +46,7 @@ Dynamic: license-file
   <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.**
+**Event-driven agents for Python developers — tasks wake on typed artifacts, like Celery tasks wake on messages. No graph to draw.**
 
 [![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)
@@ -56,14 +56,79 @@ Dynamic: license-file
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/bzdvdn/reactifact)
 [![Docs](https://img.shields.io/badge/docs-bzdvdn.github.io%2Freactifact-blue)](https://bzdvdn.github.io/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
-Q2?"* — needs Confluence + GitLab + CSV + calculations + verification, and the
-*next* question needs a different path. There is no universal graph to draw.
+Python developers already know this model from Celery: define a **task**,
+declare what triggers it, let the runtime run it. reactifact applies it to agents — a task
+reacts to a **typed, versioned artifact** appearing in the context, not to a
+queue message you push or a graph edge you draw. The runtime derives what runs
+next from state.
 
-reactifact flips the model. You describe **what artifacts exist and what agents can
-do with them**; the runtime derives what runs next from **state changes**. Agents
-react to events — there is no graph, no node pipeline.
+| Celery | reactifact |
+| --- | --- |
+| a task | `@produce(Model)` — a unit of work that writes an artifact |
+| `delay()` / `apply_async()` | you don't call it: creating the input artifact **is** the trigger |
+| routing key / queue | `Consume(Type)` — which artifact type wakes the task |
+| chain / group / chord | several `consumes` / `produces`; the runtime derives the order |
+| retries, `acks_late` | guards + `Budget`, an honest `None` instead of a wrong result |
+| result backend | the `Context` — typed, versioned artifacts |
+| worker | `Runtime` |
+
+Single process today (no broker, no worker pool) — the *model* is Celery-shaped,
+not its distributed runtime.
+
+On top of that model you get something a task queue doesn't: every artifact is
+**versioned with provenance**, so a run is reproducible (`context_hash`) and
+auditable (`audit.report`) for free. The model reasons; the arithmetic stays
+deterministic; every claim carries provenance.
+
+## On top: a provable answer
+
+[`examples/fintech_audit`](examples/fintech_audit) — a transactions CSV, a budget
+CSV and a policy doc, **no API key**. The model never produces the number; plain
+Python does, and the answer is linked to its evidence:
+
+```text
+$ .venv/bin/python -m examples.fintech_audit.main
+
+  cloud spend:        $45,000   (2026-04 $12k, 2026-05 $15k, 2026-06 $18k)
+  variance vs budget: +12.5%    budget $40,000, policy threshold 10% → over
+
+  answer:    Q2 cloud spend was $45,000 against a $40,000 budget (+12.5%) —
+             exceeds the 10% policy threshold. CFO approval is required.
+  citations: budget.csv, transactions.csv, policy.md
+  audit:     Answer —supported_by→ {Variance, Spend, Table, Policy}
+             answer sha256 5461290d…  ·  context sha256 24449f6f…
+
+  >>> re-running the pipeline hashes identically — or verify a saved run:
+  >>> reactifact replay <store> --session <id> --verify 24449f6f…
+```
+
+That hash is the whole point: the answer is *reproducible* and its provenance is
+a queryable graph (`context.related(answer.id, "supported_by")`), not a log line.
+
+![fintech_audit demo: the variance, the answer, and the reproducible context hash — a second run prints the same hash.](docs/img/fintech-audit-short.gif)
+
+The number is computed, and its provenance recorded, in plain Python — the model
+is never the source of truth (trimmed from
+[`examples/fintech_audit/produce.py`](examples/fintech_audit/produce.py)):
+
+```python
+@produce(Variance, reacts_to=Spend)              # wakes when a Spend artifact exists
+async def compute_variance(call: ProduceCall) -> None:
+    spend = call.trigger                         # the artifact that triggered this run
+    budget = cloud_budget(call.context)          # read from budget.csv
+    pct = (spend.data.total - budget) / budget   # deterministic — never the model
+    variance = call.effects.create_once_from(
+        spend,                                   # stable id → idempotent re-runs (§42)
+        Variance(actual=spend.data.total, budget=budget, pct=pct,
+                 threshold=0.10, within_policy=abs(pct) <= 0.10),
+    )
+    variance.link("calculated_from", spend)      # provenance edge, queryable
+
+
+answer = ctx.latest(AuditAnswer)
+print(report_to_markdown(build_report(ctx, answer)))  # hash per artifact + edges
+print(context_hash(ctx))                              # reproducible fingerprint
+```
 
 ![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)
 
@@ -250,6 +315,9 @@ 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`.
 
+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.
+
 ## Examples (in-repo, not shipped)
 
 - `knowledge` — multi-source chat: search → evidence → claim verification → answer, with CSV calculation.
@@ -267,8 +335,11 @@ Classic-pattern ports run as one-liners too:
 
 - [English](docs/en/index.md) · [Русский](docs/ru/index.md) — concepts, sources,
   providers, recipes, patterns, observability, eval, branching, replay, viz/CLI, API.
-- [Quickstart](docs/en/quickstart.md) — three runnable snippets: tool-calling
-  agent, retrieval over your docs, session-persisted chat bot.
+- [Quickstart](docs/en/quickstart.md) — the four `quick` cases (structured call,
+  RAG, tools, chat) in a few lines; also as a
+  [Colab notebook](examples/quickstart.ipynb).
+- [Migrating](docs/en/migrating.md) — from LangGraph / CrewAI / LlamaIndex /
+  plain Python: concept map, port-one-node, interop, checklist.
 - [Why reactifact](docs/en/why-reactifact.md) — the *design argument*: why effects, why no graph, why determinism.
 - [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.

{reactifact-0.9.1 → reactifact-0.11.0}/README.md

@@ -2,7 +2,7 @@
   <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.**
+**Event-driven agents for Python developers — tasks wake on typed artifacts, like Celery tasks wake on messages. No graph to draw.**
 
 [![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)
@@ -12,14 +12,79 @@
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/bzdvdn/reactifact)
 [![Docs](https://img.shields.io/badge/docs-bzdvdn.github.io%2Freactifact-blue)](https://bzdvdn.github.io/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
-Q2?"* — needs Confluence + GitLab + CSV + calculations + verification, and the
-*next* question needs a different path. There is no universal graph to draw.
+Python developers already know this model from Celery: define a **task**,
+declare what triggers it, let the runtime run it. reactifact applies it to agents — a task
+reacts to a **typed, versioned artifact** appearing in the context, not to a
+queue message you push or a graph edge you draw. The runtime derives what runs
+next from state.
 
-reactifact flips the model. You describe **what artifacts exist and what agents can
-do with them**; the runtime derives what runs next from **state changes**. Agents
-react to events — there is no graph, no node pipeline.
+| Celery | reactifact |
+| --- | --- |
+| a task | `@produce(Model)` — a unit of work that writes an artifact |
+| `delay()` / `apply_async()` | you don't call it: creating the input artifact **is** the trigger |
+| routing key / queue | `Consume(Type)` — which artifact type wakes the task |
+| chain / group / chord | several `consumes` / `produces`; the runtime derives the order |
+| retries, `acks_late` | guards + `Budget`, an honest `None` instead of a wrong result |
+| result backend | the `Context` — typed, versioned artifacts |
+| worker | `Runtime` |
+
+Single process today (no broker, no worker pool) — the *model* is Celery-shaped,
+not its distributed runtime.
+
+On top of that model you get something a task queue doesn't: every artifact is
+**versioned with provenance**, so a run is reproducible (`context_hash`) and
+auditable (`audit.report`) for free. The model reasons; the arithmetic stays
+deterministic; every claim carries provenance.
+
+## On top: a provable answer
+
+[`examples/fintech_audit`](examples/fintech_audit) — a transactions CSV, a budget
+CSV and a policy doc, **no API key**. The model never produces the number; plain
+Python does, and the answer is linked to its evidence:
+
+```text
+$ .venv/bin/python -m examples.fintech_audit.main
+
+  cloud spend:        $45,000   (2026-04 $12k, 2026-05 $15k, 2026-06 $18k)
+  variance vs budget: +12.5%    budget $40,000, policy threshold 10% → over
+
+  answer:    Q2 cloud spend was $45,000 against a $40,000 budget (+12.5%) —
+             exceeds the 10% policy threshold. CFO approval is required.
+  citations: budget.csv, transactions.csv, policy.md
+  audit:     Answer —supported_by→ {Variance, Spend, Table, Policy}
+             answer sha256 5461290d…  ·  context sha256 24449f6f…
+
+  >>> re-running the pipeline hashes identically — or verify a saved run:
+  >>> reactifact replay <store> --session <id> --verify 24449f6f…
+```
+
+That hash is the whole point: the answer is *reproducible* and its provenance is
+a queryable graph (`context.related(answer.id, "supported_by")`), not a log line.
+
+![fintech_audit demo: the variance, the answer, and the reproducible context hash — a second run prints the same hash.](docs/img/fintech-audit-short.gif)
+
+The number is computed, and its provenance recorded, in plain Python — the model
+is never the source of truth (trimmed from
+[`examples/fintech_audit/produce.py`](examples/fintech_audit/produce.py)):
+
+```python
+@produce(Variance, reacts_to=Spend)              # wakes when a Spend artifact exists
+async def compute_variance(call: ProduceCall) -> None:
+    spend = call.trigger                         # the artifact that triggered this run
+    budget = cloud_budget(call.context)          # read from budget.csv
+    pct = (spend.data.total - budget) / budget   # deterministic — never the model
+    variance = call.effects.create_once_from(
+        spend,                                   # stable id → idempotent re-runs (§42)
+        Variance(actual=spend.data.total, budget=budget, pct=pct,
+                 threshold=0.10, within_policy=abs(pct) <= 0.10),
+    )
+    variance.link("calculated_from", spend)      # provenance edge, queryable
+
+
+answer = ctx.latest(AuditAnswer)
+print(report_to_markdown(build_report(ctx, answer)))  # hash per artifact + edges
+print(context_hash(ctx))                              # reproducible fingerprint
+```
 
 ![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)
 
@@ -206,6 +271,9 @@ 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`.
 
+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.
+
 ## Examples (in-repo, not shipped)
 
 - `knowledge` — multi-source chat: search → evidence → claim verification → answer, with CSV calculation.
@@ -223,8 +291,11 @@ Classic-pattern ports run as one-liners too:
 
 - [English](docs/en/index.md) · [Русский](docs/ru/index.md) — concepts, sources,
   providers, recipes, patterns, observability, eval, branching, replay, viz/CLI, API.
-- [Quickstart](docs/en/quickstart.md) — three runnable snippets: tool-calling
-  agent, retrieval over your docs, session-persisted chat bot.
+- [Quickstart](docs/en/quickstart.md) — the four `quick` cases (structured call,
+  RAG, tools, chat) in a few lines; also as a
+  [Colab notebook](examples/quickstart.ipynb).
+- [Migrating](docs/en/migrating.md) — from LangGraph / CrewAI / LlamaIndex /
+  plain Python: concept map, port-one-node, interop, checklist.
 - [Why reactifact](docs/en/why-reactifact.md) — the *design argument*: why effects, why no graph, why determinism.
 - [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.

{reactifact-0.9.1 → reactifact-0.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "reactifact"
-version = "0.9.1"
+version = "0.11.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"
@@ -100,7 +100,7 @@ packages = { find = { where = ["."], include = ["reactifact*"], exclude = ["exam
 
 [tool.setuptools.package-data]
 reactifact = ["py.typed"]
-"reactifact.tracing" = ["templates/*.html"]
+"reactifact.tracing" = ["templates/*.html", "templates/*.css"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
@@ -118,6 +118,9 @@ fail_under = 85
 target-version = "py311"
 line-length = 88
 src = ["reactifact", "examples"]
+# Notebooks are Colab artifacts (IPython magics, top-level await) — not package
+# code; don't lint/format them.
+extend-exclude = ["*.ipynb"]
 
 [tool.ruff.lint]
 select = [

{reactifact-0.9.1 → reactifact-0.11.0}/reactifact/__init__.py

@@ -42,13 +42,14 @@ from .providers import (
     LLMResponseChunk,
     Message,
 )
-from .resources import RuntimeResources
+from .request import current_request
+from .resources import ResourceKey, ResourceScope, RuntimeResources
 from .runtime import Runtime
 from .session import Session, SessionStore
 from .tools import FunctionTool, Tool, ToolOutput, tool
 from .triggers import Trigger
 
-__version__ = "0.9.1"
+__version__ = "0.11.0"
 
 __all__ = [
     "Agent",
@@ -74,6 +75,8 @@ __all__ = [
     "Produce",
     "ProduceCall",
     "Relation",
+    "ResourceKey",
+    "ResourceScope",
     "RunOutcome",
     "RunStats",
     "Runtime",
@@ -92,6 +95,7 @@ __all__ = [
     "View",
     "consume",
     "create_agent",
+    "current_request",
     "produce",
     "tool",
 ]

reactifact-0.11.0/reactifact/_httpx.py

@@ -0,0 +1,87 @@
+"""Loop-aware `httpx.AsyncClient` ownership for providers and sinks.
+
+`httpx.AsyncClient` binds its connection pool (and internal locks) to the event
+loop it was created on. A provider/sink instance that caches the client forever
+and is then reused on a *different* loop — pytest gives each test its own loop,
+a CLI calls `asyncio.run(...)` more than once, uvicorn reloads — raises
+`RuntimeError: Event loop is closed` (or "bound to a different event loop") on
+the second use.
+
+`LoopBoundClient` keeps the client **lazy** (created on first use, as before)
+but **rebinds it to the current running loop**: when the loop changes, a fresh
+client is created. The previous client's loop is already gone, so it is dropped
+rather than awaited (its pool died with the loop). An injected `client=` (tests,
+a custom transport) is returned as-is and never recreated.
+
+Typical use inside a provider:
+
+    self._http = LoopBoundClient(
+        lambda: httpx.AsyncClient(timeout=self._timeout, headers=self._headers)
+    )
+
+    async def complete(self, ...):
+        response = await self._http.get().post(url, json=payload)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+from typing import Any, cast
+
+import httpx
+
+
+class LoopBoundClient:
+    """Owns an `httpx.AsyncClient` bound to the current event loop."""
+
+    def __init__(
+        self,
+        factory: Callable[[], httpx.AsyncClient],
+        *,
+        client: Any | None = None,
+    ):
+        self._factory = factory
+        self._fixed = client
+        self._client: httpx.AsyncClient | None = None
+        self._loop: asyncio.AbstractEventLoop | None = None
+
+    def get(self) -> httpx.AsyncClient:
+        """The client for the running loop (created/recreated as needed)."""
+        if self._fixed is not None:
+            return cast("httpx.AsyncClient", self._fixed)
+        loop = asyncio.get_running_loop()
+        if self._client is None or self._loop is not loop:
+            self._client = self._factory()
+            self._loop = loop
+        return self._client
+
+    async def aclose(self) -> None:
+        """Closes the current client, if it belongs to the running loop.
+
+        A client whose owner loop is closed (or is a different, still-running
+        loop) cannot be awaited here; it is dropped — nothing can safely close
+        it from this loop. The injected `client=`, if any, is left to its owner.
+        """
+        client, loop = self._client, self._loop
+        self._client = None
+        self._loop = None
+        if client is None:
+            return
+        try:
+            current = asyncio.get_running_loop()
+        except RuntimeError:
+            return
+        if loop is not None and loop is not current:
+            return
+        await client.aclose()
+
+    def raw(self) -> Any | None:
+        """The injected client if there is one, else the current one (or None)."""
+        return self._fixed if self._fixed is not None else self._client
+
+
+__all__ = ["LoopBoundClient"]

reactifact-0.11.0/reactifact/audit.py

@@ -0,0 +1,255 @@
+"""reactifact.audit — answer provenance and reproducibility (§34, §55, §56).
+
+Two things an auditable agent needs, both offline and dependency-free:
+
+1. `build_report(context, answer)` — a self-contained record of *why* an answer
+   exists: the answer's content hash, the provenance chain behind it
+   (`supported_by` / `derived_from` / `materialized_from` / …), each artifact's
+   version, author and content hash, and the source locators it rests on.
+   Exportable as JSON (machine-checkable) or Markdown (human/regulator-readable).
+
+2. `context_hash(context)` — a sha256 over the run's canonical state
+   (artifacts + relations + version). Two runs that produce the same state hash
+   the same; recording it with a `ReplayLLM` recording turns "is this run
+   reproducible?" into a string comparison (`reactifact replay --verify <hash>`,
+   and the `fintech_audit` example).
+
+Hashes are sha256 over canonical (sorted, JSON-safe) content, so the *hash*
+fields are reproducible: the same state yields the same `context_sha256` and
+per-artifact hashes, run to run. The report also carries `created_at` values
+for a human reader, so the full JSON is not byte-identical across runs — the
+fingerprint is.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Sequence
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel
+
+from .artifacts import Artifact
+from .context import Context
+
+#: Relations followed by default when walking an answer's provenance chain.
+DEFAULT_RELATIONS: tuple[str, ...] = (
+    "supported_by",
+    "derived_from",
+    "extracted_from",
+    "materialized_from",
+    "resolved_from",
+    "calculated_from",
+    "refuted_by",
+    "contradicted_by",
+)
+
+
+def _canonical(value: Any) -> str:
+    """Canonical JSON for hashing (sorted keys; pydantic models dumped)."""
+    if isinstance(value, BaseModel):
+        payload: Any = value.model_dump(mode="json")
+    else:
+        payload = value
+    return json.dumps(payload, sort_keys=True, ensure_ascii=False, default=str)
+
+
+def data_hash(value: Any) -> str:
+    """sha256 of a value's canonical JSON — a stable content fingerprint."""
+    return hashlib.sha256(_canonical(value).encode("utf-8")).hexdigest()
+
+
+def artifact_hash(artifact: Artifact[Any]) -> str:
+    """Content hash of one artifact's data (its type + id are not included)."""
+    return data_hash(artifact.data)
+
+
+def context_hash(context: Context) -> str:
+    """sha256 over the run's canonical state: version, artifacts, relations.
+
+    Includes each artifact's id, type, version and content hash, plus every
+    relation edge — everything that makes two runs' states the same or
+    different. Timestamps are deliberately excluded, so a re-run that reaches
+    the same state hashes identically.
+    """
+    artifacts = [
+        {
+            "id": artifact.id,
+            "type": type(artifact.data).__name__,
+            "version": artifact.version,
+            "sha256": artifact_hash(artifact),
+        }
+        for artifact in sorted(context.list_artifacts(), key=lambda a: a.id)
+    ]
+    relations = sorted(
+        (rel.source_id, rel.relation, rel.target_id) for rel in context.relations()
+    )
+    payload = {
+        "version": context.version,
+        "artifacts": artifacts,
+        "relations": relations,
+    }
+    return hashlib.sha256(_canonical(payload).encode("utf-8")).hexdigest()
+
+
+class ProvenanceEntry(BaseModel):
+    """One artifact in an answer's provenance chain, with its content hash."""
+
+    artifact_id: str
+    data_type: str
+    version: int
+    sha256: str
+    produced_by: str = ""
+    created_at: datetime | None = None
+
+
+class AuditReport(BaseModel):
+    """A reproducible record of an answer and the evidence behind it."""
+
+    session_id: str = ""
+    context_version: int
+    context_sha256: str
+    answer: ProvenanceEntry
+    provenance: list[ProvenanceEntry] = []
+    relations: list[tuple[str, str, str]] = []
+    sources: list[str] = []
+
+
+def _entry(artifact: Artifact[Any], produced_by: str) -> ProvenanceEntry:
+    return ProvenanceEntry(
+        artifact_id=artifact.id,
+        data_type=type(artifact.data).__name__,
+        version=artifact.version,
+        sha256=artifact_hash(artifact),
+        produced_by=produced_by,
+        created_at=artifact.created_at,
+    )
+
+
+def _producers(context: Context) -> dict[str, str]:
+    """artifact_id → author of the commit that last wrote it (from history)."""
+    producers: dict[str, str] = {}
+    for commit in context.history():
+        for write in commit.writes:
+            producers[write.artifact_id] = commit.author
+    return producers
+
+
+def _resolve_answer(context: Context, answer: Artifact[Any] | str) -> Artifact[Any]:
+    if isinstance(answer, Artifact):
+        return answer
+    artifact = context.get(answer)
+    if artifact is None:
+        raise KeyError(f"answer artifact {answer!r} not found in context")
+    return artifact
+
+
+def build_report(
+    context: Context,
+    answer: Artifact[Any] | str,
+    *,
+    relations: Sequence[str] | None = None,
+    session_id: str = "",
+) -> AuditReport:
+    """Walks the provenance chain behind `answer` into a verifiable report.
+
+    Breadth-first over `context.relations()`, following `relations` (all by
+    default), so every artifact that contributed to the answer is included with
+    its content hash and producing author. `SourceRef` locators in the chain
+    become `sources`.
+    """
+    followed = set(relations) if relations is not None else set(DEFAULT_RELATIONS)
+    answer_artifact = _resolve_answer(context, answer)
+    producers = _producers(context)
+
+    entries: list[ProvenanceEntry] = []
+    edges: list[tuple[str, str, str]] = []
+    sources: list[str] = []
+    visited: set[str] = set()
+    queue = [answer_artifact]
+    while queue:
+        artifact = queue.pop(0)
+        if artifact.id in visited:
+            continue
+        visited.add(artifact.id)
+        entries.append(_entry(artifact, producers.get(artifact.id, "")))
+        locator = getattr(artifact.data, "locator", None)
+        if isinstance(locator, str) and locator and locator not in sources:
+            sources.append(locator)
+        for rel in context.relations(source_id=artifact.id):
+            if rel.relation not in followed:
+                continue
+            edges.append((rel.source_id, rel.relation, rel.target_id))
+            target = context.get(rel.target_id)
+            if target is not None and target.id not in visited:
+                queue.append(target)
+
+    return AuditReport(
+        session_id=session_id,
+        context_version=context.version,
+        context_sha256=context_hash(context),
+        answer=entries[0],
+        provenance=entries[1:],
+        relations=edges,
+        sources=sources,
+    )
+
+
+def report_to_json(report: AuditReport, *, indent: int | None = 2) -> str:
+    """The report as canonical JSON (sorted keys → reproducible bytes)."""
+    return json.dumps(
+        report.model_dump(mode="json"),
+        indent=indent,
+        sort_keys=True,
+        ensure_ascii=False,
+    )
+
+
+def report_to_markdown(report: AuditReport) -> str:
+    """The report as Markdown — for a PR comment, a ticket, or a regulator."""
+    lines = [
+        "# Audit report",
+        "",
+        f"- context version: {report.context_version}",
+        f"- context sha256: `{report.context_sha256}`",
+        f"- session: {report.session_id or '(none)'}",
+        "",
+        "## Answer",
+        "",
+        f"- `{report.answer.artifact_id}` ({report.answer.data_type}, "
+        f"v{report.answer.version})",
+        f"- sha256: `{report.answer.sha256}`",
+        f"- produced by: {report.answer.produced_by or '(seed)'}",
+        "",
+        "## Provenance",
+        "",
+        "| artifact | type | v | sha256 | produced by |",
+        "| --- | --- | --- | --- | --- |",
+    ]
+    for entry in [report.answer, *report.provenance]:
+        lines.append(
+            f"| `{entry.artifact_id}` | {entry.data_type} | {entry.version} | "
+            f"`{entry.sha256[:12]}…` | {entry.produced_by or '(seed)'} |"
+        )
+    if report.relations:
+        lines += ["", "## Edges", ""]
+        lines += [f"- `{s}` —{r}→ `{t}`" for s, r, t in report.relations]
+    if report.sources:
+        lines += ["", "## Sources", ""]
+        lines += [f"- `{source}`" for source in report.sources]
+    return "\n".join(lines) + "\n"
+
+
+__all__ = [
+    "DEFAULT_RELATIONS",
+    "AuditReport",
+    "ProvenanceEntry",
+    "artifact_hash",
+    "build_report",
+    "context_hash",
+    "data_hash",
+    "report_to_json",
+    "report_to_markdown",
+]

{reactifact-0.9.1 → reactifact-0.11.0}/reactifact/budget.py

@@ -35,6 +35,8 @@ class RunStats:
     runs: int
     iterations: int
     outcome: RunOutcome
+    #: Wall-clock duration of the turn, in **seconds** (`time.monotonic()`).
+    #: Distinct from `RunTrace.duration_ms`, which is in milliseconds.
     duration: float
     #: Agent executions that raised and were isolated (`Runtime(isolate_errors=True)`).
     #: Always 0 when isolation is off — an exception propagates instead (§69).