reactifact 0.10.0__tar.gz → 0.11.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reactifact
-Version: 0.10.0
+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)
 

{reactifact-0.10.0 → 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)
 

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "reactifact"
-version = "0.10.0"
+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"]

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

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

{reactifact-0.10.0 → 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).

{reactifact-0.10.0 → reactifact-0.11.0}/reactifact/context.py

@@ -124,6 +124,8 @@ class Context:
         """
         if id is not None and id in self._artifacts:
             return self._artifacts[id]
+        if id is None and self.resources.id_factory is not None:
+            id = self.resources.id_factory(type(data).__name__)
         artifact = Artifact(data=data, id=id)
         self._artifacts[artifact.id] = artifact
         self._by_type.setdefault(type(data), set()).add(artifact.id)

{reactifact-0.10.0 → reactifact-0.11.0}/reactifact/effects.py

@@ -102,9 +102,15 @@ class Effects:
         site when that "may already exist" intent should be explicit instead
         of implicit in a plain `create(..., id=...)`.
         """
-        artifact_id = id or _auto_id(type(data).__name__)
-        self.operations.append(Create(data, id=artifact_id))
-        return Handle(self, artifact_id, data)
+        if id is None:
+            factory = self._context.resources.id_factory
+            id = (
+                factory(type(data).__name__)
+                if factory is not None
+                else _auto_id(type(data).__name__)
+            )
+        self.operations.append(Create(data, id=id))
+        return Handle(self, id, data)
 
     def create_once(self, data: Any, *, id: str) -> Handle | None:
         """Idempotent create (§42): `None` if `id` already exists in the

{reactifact-0.10.0 → reactifact-0.11.0}/reactifact/replay.py

@@ -21,17 +21,23 @@ Two complementary halves:
 from __future__ import annotations
 
 import hashlib
+import itertools
 import json
 import logging
+from collections.abc import Awaitable, Callable
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Literal
 
+from pydantic import BaseModel
+
+from .audit import context_hash
 from .context import Context
 from .providers import LLMProvider, LLMRequest, LLMResponse, LLMResponseChunk
 
 if TYPE_CHECKING:
     from collections.abc import AsyncIterator
 
+    from .resources import RuntimeResources
     from .session import SessionStore
 
 logger = logging.getLogger(__name__)
@@ -168,6 +174,83 @@ async def replay_context(
     return context
 
 
+def counter_ids(start: int = 0) -> Callable[[str], str]:
+    """A deterministic id factory: `Model:0000`, `Model:0001`, … per run.
+
+    Assign it to `RuntimeResources(id_factory=…)` and every artifact created
+    without an explicit id gets a stable, order-derived id instead of a
+    `uuid4` — enough to make an otherwise-unmodified app's `context_hash`
+    reproducible run to run. Pair with `ReplayLLM` (recorded model calls) for
+    full reproducibility; `verify_run` wires both.
+    """
+    counter = itertools.count(start)
+
+    def make(model_name: str) -> str:
+        return f"{model_name.lower()}:{next(counter):04d}"
+
+    return make
+
+
+class ReproReport(BaseModel):
+    """Outcome of `verify_run`: were repeated runs byte-identical?"""
+
+    ok: bool
+    hashes: list[str]
+    repeat: int
+    recording: str | None = None
+
+
+#: A run builder: given resources, produce the finished `Context`.
+RunBuilder = Callable[["RuntimeResources"], Awaitable["Context"]]
+
+
+async def verify_run(
+    build: RunBuilder,
+    *,
+    recording: str | Path | None = None,
+    repeat: int = 2,
+    resources_factory: Callable[[], RuntimeResources] | None = None,
+) -> ReproReport:
+    """Runs `build` `repeat` times and checks the `context_hash` is identical.
+
+    Each run gets fresh resources with **deterministic ids**
+    (`counter_ids()`) and — when `recording` is given — a `ReplayLLM` replaying
+    it, so a difference between runs is real nondeterminism in the app (time,
+    randomness, unstable ids, order), not model variance. `build(resources)`
+    must build the app on the given resources and return the finished
+    `Context` (it must not create resources itself).
+
+        report = await verify_run(build, recording="calls.jsonl")
+        assert report.ok, report.hashes
+
+    Returns a `ReproReport`; `ok` is False (with every hash) when they differ.
+    """
+    if repeat < 2:
+        raise ValueError("verify_run needs repeat >= 2 to compare runs")
+    hashes: list[str] = []
+    for _ in range(repeat):
+        resources = (
+            resources_factory() if resources_factory is not None else _resources()
+        )
+        resources.id_factory = counter_ids()
+        if recording is not None:
+            resources.llm = ReplayLLM(recording, mode="replay")
+        context = await build(resources)
+        hashes.append(context_hash(context))
+    return ReproReport(
+        ok=len(set(hashes)) == 1,
+        hashes=hashes,
+        repeat=repeat,
+        recording=str(recording) if recording is not None else None,
+    )
+
+
+def _resources() -> RuntimeResources:
+    from .resources import RuntimeResources
+
+    return RuntimeResources()
+
+
 def replay_summary(context: Context) -> dict[str, Any]:
     """A compact "state at this point" summary for the replay CLI."""
     artifacts = context.list_artifacts()
@@ -184,4 +267,12 @@ def replay_summary(context: Context) -> dict[str, Any]:
     }
 
 
-__all__ = ["ReplayLLM", "ReplayMiss", "replay_context", "replay_summary"]
+__all__ = [
+    "ReproReport",
+    "ReplayLLM",
+    "ReplayMiss",
+    "counter_ids",
+    "replay_context",
+    "replay_summary",
+    "verify_run",
+]

{reactifact-0.10.0 → reactifact-0.11.0}/reactifact/resources.py

@@ -15,6 +15,10 @@ if TYPE_CHECKING:
 
 T = TypeVar("T")
 
+#: Mints an artifact id from its model/type name — injectable for deterministic
+#: runs (`reactifact.replay.counter_ids`). `None` keeps the uuid default.
+IdFactory = Callable[[str], str]
+
 
 class ResourceKey(Generic[T]):
     """A typed key for registering a resource when the *type* isn't a good key.
@@ -47,11 +51,17 @@ class RuntimeResources:
         context_builder: ContextBuilder | None = None,
         verification_threshold: float | None = None,
         redactor: Redactor | None = None,
+        id_factory: IdFactory | None = None,
         **additional: Any,
     ):
         self.llm = llm
         self.embedder = embedder
         self.sources = sources or {}
+        # Injected id source for artifacts created without an explicit id
+        # (`None` = the uuid default). A deterministic factory
+        # (`reactifact.replay.counter_ids`) makes an unmodified app's
+        # `context_hash` reproducible run to run — see `reactifact.replay.verify_run`.
+        self.id_factory = id_factory
         # Applied to trace text only (artifact `data`, LLM messages/responses,
         # errors) before it reaches a sink — never to the live `Context` or a
         # persisted session. `None` (default) reproduces the pre-hook behavior.
@@ -133,6 +143,15 @@ class RuntimeResources:
         """The keys of every registered typed resource (for diagnostics)."""
         return frozenset(self._typed)
 
+    def typed_values(self) -> list[Any]:
+        """Every registered typed resource value (read-only introspection).
+
+        `registered` gives the keys; this gives the values — e.g. so a generic
+        tool scanner (`reactifact.testing.fault`) can find a `list[Tool]`
+        registered with `register(...)`, not just one stashed via `set(...)`.
+        """
+        return list(self._typed.values())
+
     def set(self, name: str, value: Any) -> None:
         self.additional[name] = value
 

{reactifact-0.10.0 → reactifact-0.11.0}/reactifact/runtime.py

@@ -498,7 +498,9 @@ class Runtime:
             self._warn_no_runs()
         await self._trace.end_turn(
             session_id=self.session.session_id if self.session is not None else "",
-            duration_ms=time.monotonic() - self._turn_started_at,
+            # `time.monotonic()` is seconds; the trace's `duration_ms` (and every
+            # sink/UI reading it) is milliseconds — same unit as span latency.
+            duration_ms=(time.monotonic() - self._turn_started_at) * 1000,
             outcome=self.outcome.value,
         )
         if self.session is not None and self.session_save_policy == "per_turn":

{reactifact-0.10.0 → reactifact-0.11.0}/reactifact/testing/fault.py

@@ -108,17 +108,24 @@ def _iter_tool_dicts(agents: Sequence[Agent]) -> Iterator[dict[str, Tool]]:
 
 
 def _iter_tool_lists(resources: RuntimeResources | None) -> Iterator[list[Tool]]:
-    """Yields every `list[Tool]`-shaped value found in `resources.additional`.
-
-    Covers tools resolved dynamically at produce-time (`context.resources.get(...)`)
-    rather than fixed on a `Produce` instance at construction — `_iter_tool_dicts`
-    has nothing to scan for those, since no static attribute holds them. Same
-    duck-typing as `_iter_tool_dicts`: any non-empty list whose items all have
-    `.execute` is treated as a tool list, whatever key it's stored under.
+    """Yields every `list[Tool]`-shaped value found on `resources`.
+
+    Covers tools resolved dynamically at produce-time
+    (`context.resources.get(...)` / `resources.require(...)`) rather than fixed
+    on a `Produce` instance at construction — `_iter_tool_dicts` has nothing to
+    scan for those, since no static attribute holds them. Both storage shapes
+    are scanned: the string-keyed `additional` escape hatch, and resources
+    registered typedly via `resources.register(...)` (`_typed`, surfaced by
+    `RuntimeResources.typed_values()`). Missing the latter silently made
+    `result.tools.called/never_called` blind to tools registered that way.
+
+    Same duck-typing as `_iter_tool_dicts`: any non-empty list whose items all
+    have `.execute` is treated as a tool list, wherever it is stored. The
+    caller de-dupes by identity, so a list present in both is wrapped once.
     """
     if resources is None:
         return
-    for value in resources.additional.values():
+    for value in (*resources.additional.values(), *resources.typed_values()):
         if (
             isinstance(value, list)
             and value

{reactifact-0.10.0 → reactifact-0.11.0}/reactifact/testing/lab.py

@@ -33,7 +33,7 @@ from pydantic import BaseModel
 from reactifact.agents import Agent
 from reactifact.budget import Budget, RunStats
 from reactifact.context import Context
-from reactifact.resources import RuntimeResources
+from reactifact.resources import ResourceKey, RuntimeResources
 from reactifact.runtime import Runtime
 from reactifact.streaming import ProgressEvent, QueueEvent
 from reactifact.tracing.models import RunTrace
@@ -176,27 +176,30 @@ class ScenarioLab:
 
     def fail_resource(
         self,
-        name: str,
+        resource: str | type[Any] | ResourceKey[Any],
         error: BaseException | Callable[[], BaseException],
         *,
         method: str | None = None,
         times: int | None = None,
     ) -> None:
-        """Queues a fault for a named resource — the general-purpose analog
-        of `fail()` for anything that isn't a tool: `"llm"`, `"embedder"`, a
-        source id (`resources.sources[id]`), or a name set via
-        `resources.set(name, ...)`.
+        """Queues a fault for a resource — the general-purpose analog of
+        `fail()` for anything that isn't a tool.
+
+        `resource` addresses it either by **string name** — `"llm"`,
+        `"embedder"`, a source id (`resources.sources[id]`), or a name set via
+        `resources.set(name, ...)` — or by a **typed key**: a class or a
+        `ResourceKey` registered with `resources.register(...)`.
 
         Wraps the resource in a duck-typed proxy for the next `run()`/
         `.turn()`: `method=None` (default) fails every callable on it;
         naming one method (e.g. `"embed"`, `"search"`) faults only that
         method. `times=None` faults every call; `times=N` faults the first
         `N`, then delegates to the real resource — same shape as `fail()`.
-        Raises `ScenarioError` at run time if `name` doesn't match any
+        Raises `ScenarioError` at run time if `resource` doesn't match any
         resource, or matches one that's `None` (nothing configured to fail).
         """
         self._resource_faults.append(
-            ResourceFault(name, error, method=method, times=times)
+            ResourceFault(resource, error, method=method, times=times)
         )
 
     def _build_resources(self) -> RuntimeResources:

{reactifact-0.10.0 → reactifact-0.11.0}/reactifact/testing/mock.py

@@ -24,15 +24,17 @@ from typing import TYPE_CHECKING, Any
 from .exceptions import ScenarioError
 
 if TYPE_CHECKING:
-    from reactifact.resources import RuntimeResources
+    from reactifact.resources import ResourceKey, RuntimeResources
 
 
 @dataclass
 class ResourceFault:
-    """A queued fault for one named resource.
+    """A queued fault for one resource.
 
-    `resource` is `"llm"`, `"embedder"`, a source id (`resources.sources
-    [id]`), or a name set via `resources.set(name, ...)`. `method=None`
+    `resource` addresses it either by **string name** — `"llm"`, `"embedder"`,
+    a source id (`resources.sources[id]`), or a name set via
+    `resources.set(name, ...)` — or by a **typed key**: a class or a
+    `ResourceKey` registered with `resources.register(...)`. `method=None`
     (default) fails every callable on the resource; naming one (e.g.
     `"embed"`) faults only that method, leaving the rest of the resource
     working normally. `times=None` faults every call; `times=N` faults the
@@ -40,15 +42,20 @@ class ResourceFault:
     `fault.ToolFault`.
     """
 
-    resource: str
+    resource: str | type[Any] | ResourceKey[Any]
     error: BaseException | Callable[[], BaseException]
     method: str | None = None
     times: int | None = None
 
 
-def _get_resource(resources: RuntimeResources, name: str) -> tuple[Any, bool]:
+def _get_resource(
+    resources: RuntimeResources, key: str | type[Any] | ResourceKey[Any]
+) -> tuple[Any, bool]:
     """Returns `(value, found)` — `found=False` means no such resource exists
     at all (as opposed to existing but being `None`)."""
+    if not isinstance(key, str):
+        return (resources.get(key), True) if resources.has(key) else (None, False)
+    name = key
     if name == "llm":
         return resources.llm, True
     if name == "embedder":
@@ -60,7 +67,13 @@ def _get_resource(resources: RuntimeResources, name: str) -> tuple[Any, bool]:
     return None, False
 
 
-def _set_resource(resources: RuntimeResources, name: str, value: Any) -> None:
+def _set_resource(
+    resources: RuntimeResources, key: str | type[Any] | ResourceKey[Any], value: Any
+) -> None:
+    if not isinstance(key, str):
+        resources.register(key, value)
+        return
+    name = key
     if name == "llm":
         resources.llm = value
     elif name == "embedder":
@@ -140,7 +153,7 @@ class ResourceFaultInstaller:
     ) -> None:
         self._resources = resources
         self._faults = {f.resource: f for f in faults}
-        self._originals: list[tuple[str, Any]] = []
+        self._originals: list[tuple[str | type[Any] | ResourceKey[Any], Any]] = []
 
     def __enter__(self) -> ResourceFaultInstaller:
         for name, fault in self._faults.items():
@@ -148,8 +161,9 @@ class ResourceFaultInstaller:
             if not found:
                 raise ScenarioError(
                     f"fail_resource({name!r}, ...): no such resource — expected "
-                    '"llm", "embedder", a source id, or a name set via '
-                    "resources.set(...)"
+                    '"llm", "embedder", a source id, a name set via '
+                    "resources.set(...), or a key registered via "
+                    "resources.register(Type | ResourceKey, ...)"
                 )
             if original is None:
                 raise ScenarioError(

{reactifact-0.10.0 → reactifact-0.11.0}/reactifact/tracing/__init__.py

@@ -6,10 +6,24 @@ but without `web`, so that importing the package does not pull in FastAPI.
 """
 
 from .langfuse import LangfuseTracer
-from .models import AgentSpan, ArtifactRef, LLMCall, RelationRef, RunTrace
+from .models import (
+    AgentSpan,
+    ArtifactRef,
+    LLMCall,
+    RelationRef,
+    RunTrace,
+    Tag,
+    TagAssignment,
+)
 from .otlp import OTLPTracer
 from .postgres import PostgresStore
-from .store import TraceReader, TraceSink, TraceStore
+from .store import (
+    TraceAnnotator,
+    TraceReader,
+    TraceSink,
+    TraceStore,
+    TraceStoreProtocol,
+)
 from .tracer import CompositeTracer, RecordingLLM, RunTracer, Tracer
 
 __all__ = [
@@ -24,8 +38,12 @@ __all__ = [
     "RelationRef",
     "RunTrace",
     "RunTracer",
+    "Tag",
+    "TagAssignment",
+    "TraceAnnotator",
     "TraceReader",
     "TraceSink",
     "TraceStore",
+    "TraceStoreProtocol",
     "Tracer",
 ]