reactifact 0.8.0__tar.gz → 0.9.0__tar.gz

{reactifact-0.8.0/reactifact.egg-info → reactifact-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reactifact
-Version: 0.8.0
+Version: 0.9.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
@@ -106,21 +106,21 @@ DOCS = {
 
 
 @produce(Evidence)
-async def find_evidence(context, inputs, event, effects):
-    question = next((a for a in inputs if isinstance(a.data, Question)), None)
+async def find_evidence(call):
+    question = next((a for a in call.inputs if isinstance(a.data, Question)), None)
     if question is None:
         return None
     hit = next((v for k, v in DOCS.items() if k in question.data.text.lower()), None)
     if hit is not None:
-        effects.create(Evidence(text=hit))
+        call.effects.create(Evidence(text=hit))
 
 
 @produce(Answer)
-async def answer_from_evidence(context, inputs, event, effects):
-    evidence = next((a for a in inputs if isinstance(a.data, Evidence)), None)
+async def answer_from_evidence(call):
+    evidence = next((a for a in call.inputs if isinstance(a.data, Evidence)), None)
     if evidence is None:
         return None
-    effects.create(Answer(text=evidence.data.text)).link("supported_by", evidence)
+    call.effects.create(Answer(text=evidence.data.text)).link("supported_by", evidence)
 
 
 search_agent = create_agent("search", consumes=[Consume(Question)], produces=[find_evidence])

{reactifact-0.8.0 → reactifact-0.9.0}/README.md

@@ -62,21 +62,21 @@ DOCS = {
 
 
 @produce(Evidence)
-async def find_evidence(context, inputs, event, effects):
-    question = next((a for a in inputs if isinstance(a.data, Question)), None)
+async def find_evidence(call):
+    question = next((a for a in call.inputs if isinstance(a.data, Question)), None)
     if question is None:
         return None
     hit = next((v for k, v in DOCS.items() if k in question.data.text.lower()), None)
     if hit is not None:
-        effects.create(Evidence(text=hit))
+        call.effects.create(Evidence(text=hit))
 
 
 @produce(Answer)
-async def answer_from_evidence(context, inputs, event, effects):
-    evidence = next((a for a in inputs if isinstance(a.data, Evidence)), None)
+async def answer_from_evidence(call):
+    evidence = next((a for a in call.inputs if isinstance(a.data, Evidence)), None)
     if evidence is None:
         return None
-    effects.create(Answer(text=evidence.data.text)).link("supported_by", evidence)
+    call.effects.create(Answer(text=evidence.data.text)).link("supported_by", evidence)
 
 
 search_agent = create_agent("search", consumes=[Consume(Question)], produces=[find_evidence])

{reactifact-0.8.0 → reactifact-0.9.0}/pyproject.toml

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

{reactifact-0.8.0 → reactifact-0.9.0}/reactifact/__init__.py

@@ -31,7 +31,7 @@ from .effects import Effects, Handle
 from .events import Event, EventType
 from .interrupt import PendingQuestion
 from .patches import Create, Delete, Link, Patch, Relation, Unlink, Update
-from .produce import Produce, produce
+from .produce import Produce, ProduceCall, produce
 from .providers import (
     EmbeddingProvider,
     FakeEmbedder,
@@ -48,7 +48,7 @@ from .session import Session, SessionStore
 from .tools import FunctionTool, Tool, ToolOutput, tool
 from .triggers import Trigger
 
-__version__ = "0.8.0"
+__version__ = "0.9.0"
 
 __all__ = [
     "Agent",
@@ -72,6 +72,7 @@ __all__ = [
     "Patch",
     "PendingQuestion",
     "Produce",
+    "ProduceCall",
     "Relation",
     "RunOutcome",
     "RunStats",

{reactifact-0.8.0 → reactifact-0.9.0}/reactifact/agents.py

@@ -7,9 +7,9 @@ from typing import Any
 from .artifacts import Artifact
 from .consume import Consume
 from .context import Context
-from .events import Event
+from .events import Event, EventType
 from .patches import Patch
-from .produce import Produce
+from .produce import Produce, ProduceCall
 from .triggers import Trigger
 
 
@@ -25,6 +25,15 @@ class Agent(ABC):  # noqa: B024 — interface without abstract methods, run() ha
     produces: Sequence[Produce[Any]] | None = None
     #: Declarative capability labels (§25), consumed by the adaptive policy.
     capabilities: tuple[str, ...] = ()
+    #: Explicit trigger override — for the *imperative* style (`Agent`
+    #: subclass overriding `run()` directly, no `consumes`/`produces` at
+    #: all, see `run()`'s own docstring). That style never calls
+    #: `_collect_inputs()`, so `Consume` has nothing to attach to; `triggers`
+    #: is the only way such an agent says when to wake up. For the
+    #: declarative style (`consumes`/`produces`, the common case), leave this
+    #: unset — `triggers` auto-derives from `consumes` instead, and a
+    #: `Consume` that should feed inputs without also waking the agent uses
+    #: `Consume(..., wakes=False)` rather than a second, hand-maintained list.
     triggers: list[Trigger] = []
     # Run priority within a single generation: lower value runs earlier.
     # Useful for "finishers"/evaluators that logically run last (§24).
@@ -80,7 +89,17 @@ class Agent(ABC):  # noqa: B024 — interface without abstract methods, run() ha
                     )
 
     def matches(self, event: Event, context: Context | None = None) -> bool:
-        return any(trigger.matches(event, context) for trigger in self.triggers)
+        return bool(self.matching_triggers(event, context))
+
+    def matching_triggers(
+        self, event: Event, context: Context | None = None
+    ) -> list[Trigger]:
+        """Every trigger that matches `event` — `matches()` is just
+        `bool(...)` of this. `Runtime._arun_once_impl` uses the full list
+        (not just the bool) to decide whether *every* matching trigger asks
+        for debouncing (`Trigger.debounce`) before collapsing repeat events
+        into one run."""
+        return [trigger for trigger in self.triggers if trigger.matches(event, context)]
 
     def collect_inputs(self, context: Context) -> list[Artifact[Any]]:
         """Public access to the consumed artifacts.
@@ -102,10 +121,7 @@ class Agent(ABC):  # noqa: B024 — interface without abstract methods, run() ha
             return []
         inputs: list[Artifact[Any]] = []
         for c in self.consumes:
-            artifacts = context.list_artifacts(c.artifact_type)
-            if c.condition:
-                artifacts = [a for a in artifacts if c.condition(a)]
-            inputs.extend(artifacts)
+            inputs.extend(c.collect(context))
         builder = context.resources.context_builder
         if builder is not None:
             inputs = builder.build(context, self, inputs)
@@ -128,8 +144,9 @@ class Agent(ABC):  # noqa: B024 — interface without abstract methods, run() ha
     async def execute(self, context: Context, event: Event | None = None) -> None:
         """Runs the agent's produces (usually on an event).
 
-        Effects-first (§24): produces write `self.effects.*` and return None;
-        the *runtime* compiles the effect slot into one atomic patch. This method
+        Effects-first (§24): produces write `self.effects.*`/`call.effects.*`
+        and return None; the *runtime* compiles the effect slot into one
+        atomic patch. This method
         only *runs* the produces — it does not build a patch. (`run` remains the
         agent-level escape hatch for custom Agent subclasses that assemble a
         change-set by hand; the runtime merges its result after the effects.)
@@ -138,9 +155,56 @@ class Agent(ABC):  # noqa: B024 — interface without abstract methods, run() ha
             return None
         inputs = self._collect_inputs(context)
         for p in self.produces:
-            await p.produce(context, inputs, event)
+            runs, trigger = self._resolve_produce_call(p, event, context)
+            if not runs:
+                continue
+            call = ProduceCall(
+                context=context, inputs=inputs, event=event, trigger=trigger
+            )
+            await p.produce(call)
         return None
 
+    @staticmethod
+    def _resolve_produce_call(
+        p: Produce[Any], event: Event | None, context: Context
+    ) -> tuple[bool, Artifact[Any] | None]:
+        """Whether to call `p.produce()` for `event`, and the triggering
+        artifact to put on the `ProduceCall.trigger` field (see `Produce`'s
+        docstring, and `ProduceCall`'s, for the full contract).
+
+        `p.reacts_to is None` (the default): unrestricted, matching the
+        pre-`reacts_to` behavior where every produce ran on every event this
+        agent got — `trigger` is still resolved on a best-effort basis (for
+        a produce that wants it without narrowing `reacts_to`), but never a
+        reason to skip the call, since there's no per-type contract to hold
+        it to.
+
+        `p.reacts_to` set: exact type equality against `event.artifact_type`
+        (same convention as `Trigger.artifact_type`, not `issubclass` — that
+        one's a `Context.list_artifacts()` convention for querying by base
+        type). For a CREATED/UPDATED/STALE event, also requires
+        `context.get(event.artifact_id)` to still resolve — the artifact may
+        have been deleted by another agent earlier in the same generation
+        (the same race `Trigger.matches()` documents) — so `reacts_to`, once
+        set, guarantees `call.trigger` is always a live, correctly-typed
+        artifact. A DELETED event is exempt from that liveness requirement:
+        `context.get(...)` correctly returning `None` *is* the event there,
+        not a race, so the produce still runs with `trigger=None` —
+        deletion-reacting code is expected to handle that itself.
+        """
+        if event is None:
+            return (p.reacts_to is None), None
+        if p.reacts_to is not None and event.artifact_type not in p.reacts_to:
+            return False, None
+        trigger = context.get(event.artifact_id)
+        if (
+            p.reacts_to is not None
+            and trigger is None
+            and event.type is not EventType.ARTIFACT_DELETED
+        ):
+            return False, None
+        return True, trigger
+
 
 def create_agent(
     name: str,
@@ -166,7 +230,10 @@ def create_agent(
     )
     ```
 
-    Falls back to `name` defaults the same way as `Agent.__init__`.
+    Falls back to `name` defaults the same way as `Agent.__init__`. Pass
+    `triggers` only for the rare imperative style with no `consumes` at all
+    (see `Agent.triggers`'s own docstring) — the ordinary declarative case
+    should leave it unset and use `Consume(..., wakes=False)` instead.
     """
     agent = Agent(
         name=name, triggers=triggers if triggers is not None else [], priority=priority

{reactifact-0.8.0 → reactifact-0.9.0}/reactifact/chat.py

@@ -16,10 +16,11 @@ Two levels of use:
 from __future__ import annotations
 
 import asyncio
+import inspect
 import logging
 from collections.abc import AsyncGenerator, AsyncIterator, Callable, Sequence
 from contextlib import asynccontextmanager
-from typing import Any
+from typing import Any, Literal
 
 from pydantic import BaseModel
 
@@ -64,7 +65,7 @@ async def run_message(
     user_message: type[BaseModel],
     reply: Callable[[Context, str], dict[str, Any]],
     session_id: str = "",
-    create_message: Callable[[Context, str], str] | None = None,
+    create_message: Callable[..., str] | None = None,
     status_kinds: Sequence[str] = ("status",),
     fallback_reply: str = "No reply assembled.",
 ) -> AsyncIterator[ChatEvent]:
@@ -78,7 +79,11 @@ async def run_message(
     `create_message(ctx, text) -> msg_id` overrides how the turn enters the
     context (default: create a `user_message` artifact) — HITL apps where a
     new turn resumes a pending question instead of appending a message
-    (devops-style clarify) pass their own.
+    (devops-style clarify) pass their own. Also accepts the 3-arg shape
+    `create_message(ctx, text, session_id) -> msg_id` for a hook that needs
+    the current turn's `session_id` (e.g. to stamp it onto the created
+    artifact) — detected from the callable's own arity, so the 2-arg shape
+    keeps working unchanged.
 
     `status_kinds` selects which progress event kinds are forwarded as `status`
     frames (default: only `status`; e.g. tool-announcing demos also forward
@@ -92,7 +97,7 @@ async def run_message(
     ctx = runtime.context
     try:
         if create_message is not None:
-            msg_id = create_message(ctx, text)
+            msg_id = _call_create_message(create_message, ctx, text, session_id)
         else:
             msg_id = ctx.create(user_message(text=text, session_id=session_id)).id
     except Exception:
@@ -164,6 +169,45 @@ def _resolve(value: Any) -> Any:
     return value() if callable(value) else value
 
 
+def _accepts_arg(func: Callable[..., Any], count: int) -> bool:
+    """Whether `func` (already known callable) declares at least `count`
+    positional-or-keyword parameters — used to detect the opt-in, per-request
+    call shapes below without breaking the plain zero/two-arg factories that
+    predate them. A callable whose signature can't be inspected (a builtin, a
+    C extension) is assumed to be the old, arg-less shape."""
+    try:
+        params = inspect.signature(func).parameters
+    except (TypeError, ValueError):
+        return False
+    return len(params) >= count
+
+
+def _resolve_with_session(value: Any, session_id: str) -> Any:
+    """Like `_resolve`, but passes `session_id` to `value` when it declares a
+    parameter for it — the per-request factory shape
+    (`resources=lambda session_id: build_resources(session_id)`) alongside
+    the pre-existing zero-arg one (`resources=lambda: build_resources()`),
+    which keeps working unchanged. `ChatAssistant` already knows `session_id`
+    at the point it resolves `resources=`; this just lets a factory opt into
+    reading it instead of reaching for a contextvar/side-channel to get
+    per-request data (e.g. an authenticated user) into `RuntimeResources`.
+    """
+    if not callable(value):
+        return value
+    return value(session_id) if _accepts_arg(value, 1) else value()
+
+
+def _call_create_message(
+    create_message: Callable[..., str], ctx: Context, text: str, session_id: str
+) -> str:
+    """Calls `create_message` with `session_id` appended when it declares a
+    third parameter for it (`(ctx, text, session_id) -> msg_id`), alongside
+    the pre-existing two-arg shape (`(ctx, text) -> msg_id`)."""
+    if _accepts_arg(create_message, 3):
+        return create_message(ctx, text, session_id)
+    return create_message(ctx, text)
+
+
 # --- the canonical chat assistant ----------------------------------------- #
 
 
@@ -182,6 +226,23 @@ class ChatAssistant:
     turns/sessions — that instance is never closed automatically; close it
     yourself at real shutdown.
 
+    `session_save_policy=` passes straight through to `Runtime` — `"per_turn"`
+    trades finer crash-resilience granularity (a save at every commit, the
+    default) for one `session.save()` per turn instead of one per commit,
+    worthwhile once a multi-stage pipeline routinely produces several commits
+    per turn (see `Runtime.__init__`'s own docstring for the trade-off).
+
+    `resources=`/`create_message=` may optionally take the current turn's
+    `session_id` — `resources=lambda session_id: build_resources(session_id)`
+    (e.g. to attach an authenticated user looked up from the session) and
+    `create_message=lambda ctx, text, session_id: ...` — detected from each
+    callable's own arity, so the pre-existing zero/two-arg shapes keep
+    working unchanged. Without this, per-request data (who's asking, not
+    just what they asked) has no way into a turn short of a contextvar/
+    side-channel set by the caller before `stream()`/`invoke()` — `resources=`
+    and `create_message=` were otherwise the only two hooks in this class
+    that never saw it.
+
     Base usage:
 
         assistant = ChatAssistant(
@@ -203,15 +264,16 @@ class ChatAssistant:
         user_message: type[BaseModel],
         reply: Callable[[Context, str], dict[str, Any]],
         session_state: Callable[[Context], dict[str, Any]] | None = None,
-        resources: RuntimeResources | Callable[[], RuntimeResources] | None = None,
+        resources: RuntimeResources | Callable[..., RuntimeResources] | None = None,
         budget: Budget | None = None,
         max_concurrency: int | None = None,
         tracer: Any = None,
-        create_message: Callable[[Context, str], str] | None = None,
+        create_message: Callable[..., str] | None = None,
         status_kinds: Sequence[str] = ("status",),
         fallback_reply: str = "No reply assembled.",
         isolate_errors: bool = False,
         on_agent_error: Callable[[Agent, Event, BaseException], None] | None = None,
+        session_save_policy: Literal["per_commit", "per_turn"] = "per_commit",
     ):
         self.store = store
         self._agents = agents
@@ -227,6 +289,7 @@ class ChatAssistant:
         self._fallback_reply = fallback_reply
         self._isolate_errors = isolate_errors
         self._on_agent_error = on_agent_error
+        self._session_save_policy = session_save_policy
         # Serializes concurrent turns on the *same* session_id (a double
         # submit, a client retry): without this, two overlapping stream()
         # calls both load the same starting state and the later save() wins,
@@ -262,7 +325,9 @@ class ChatAssistant:
                         self._session_locks.pop(session_id, None)
 
     async def _open(self, session_id: str) -> Session:
-        return await self.store.open(session_id, resources=_resolve(self._resources))
+        return await self.store.open(
+            session_id, resources=_resolve_with_session(self._resources, session_id)
+        )
 
     def _build_runtime(self, session: Session) -> Runtime:
         return Runtime(
@@ -274,6 +339,7 @@ class ChatAssistant:
             tracer=_resolve(self._tracer),
             isolate_errors=self._isolate_errors,
             on_agent_error=self._on_agent_error,
+            session_save_policy=self._session_save_policy,
         )
 
     async def stream(self, text: str, session_id: str = "") -> AsyncIterator[ChatEvent]: