reactifact 0.16.0__tar.gz → 0.17.0__tar.gz

{reactifact-0.16.0/reactifact.egg-info → reactifact-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reactifact
-Version: 0.16.0
+Version: 0.17.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

{reactifact-0.16.0 → reactifact-0.17.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "reactifact"
-version = "0.16.0"
+version = "0.17.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.16.0 → reactifact-0.17.0}/reactifact/__init__.py

@@ -51,7 +51,7 @@ from .tools import FunctionTool, Tool, ToolError, ToolOutput, tool
 from .triggers import Trigger
 from .types import register as register_type
 
-__version__ = "0.16.0"
+__version__ = "0.17.0"
 
 __all__ = [
     "Agent",

{reactifact-0.16.0 → reactifact-0.17.0}/reactifact/resources.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import inspect
+import warnings
 from collections.abc import Awaitable, Callable
 from contextlib import AbstractAsyncContextManager
 from typing import (
@@ -27,6 +28,15 @@ if TYPE_CHECKING:
 
 T = TypeVar("T")
 
+
+class _UnsetTraceTruncate:
+    """Sentinel so an explicit `trace_truncate=` can be told apart from the default."""
+
+    __slots__ = ()
+
+
+_UNSET_TRACE_TRUNCATE = _UnsetTraceTruncate()
+
 #: 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]
@@ -85,7 +95,7 @@ class RuntimeResources:
         context_builder: ContextBuilder | None = None,
         verification_threshold: float | None = None,
         redactor: Redactor | None = None,
-        trace_truncate: int | None = 1500,
+        trace_truncate: int | None | _UnsetTraceTruncate = _UNSET_TRACE_TRUNCATE,
         record_tool_args: bool = False,
         id_factory: IdFactory | None = None,
         pricer: Pricer | None = None,
@@ -136,10 +146,19 @@ class RuntimeResources:
         # `redactor` when set). Off by default because args may carry secrets.
         self.record_tool_args = record_tool_args
         # How many characters of an artifact's JSON (and an LLM response) are
-        # kept in a trace. `None` disables truncation. Larger values make
-        # configurable table columns / deep fields resolvable, at the cost of
-        # trace size.
-        self.trace_truncate = trace_truncate
+        # kept in a trace. `None` disables truncation. Deprecated: configure
+        # `Tracer(limits=TraceLimits(max_data_chars=...))` instead; this stays
+        # as a fallback for older code.
+        if isinstance(trace_truncate, _UnsetTraceTruncate):
+            self.trace_truncate: int | None = 1500
+        else:
+            warnings.warn(
+                "RuntimeResources(trace_truncate=...) is deprecated; use "
+                "Tracer(limits=TraceLimits(max_data_chars=...)) instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            self.trace_truncate = trace_truncate
         # Framework-wide pass/fail cutoff for `Verify` (verify.py): `None`
         # means "use Verify's own DEFAULT_THRESHOLD". A `Verify` instance's
         # own explicit `threshold=` still overrides this per agent.

{reactifact-0.16.0 → reactifact-0.17.0}/reactifact/runtime.py

@@ -853,7 +853,7 @@ class Runtime:
         tool_runs_token = begin_tool_runs(
             record_args=self.context.resources.record_tool_args,
             redactor=self.context.resources.redactor,
-            truncate=self.context.resources.trace_truncate,
+            truncate=self._trace.data_char_limit,
         )
         slot: Effects | None = None
         patch: Patch | None = None

{reactifact-0.16.0 → reactifact-0.17.0}/reactifact/tracing/__init__.py

@@ -9,6 +9,7 @@ from ..tools import ToolRun
 from .columns import TraceColumn
 from .langfuse import LangfuseTracer
 from .models import (
+    AgentContract,
     AgentSpan,
     ArtifactRef,
     LLMCall,
@@ -17,6 +18,7 @@ from .models import (
     RunTrace,
     Tag,
     TagAssignment,
+    TraceLimits,
 )
 from .otlp import OTLPTracer
 from .postgres import PostgresStore
@@ -30,6 +32,7 @@ from .store import (
 from .tracer import CompositeTracer, RecordingLLM, RunTracer, Tracer
 
 __all__ = [
+    "AgentContract",
     "AgentSpan",
     "ArtifactRef",
     "CompositeTracer",
@@ -46,6 +49,7 @@ __all__ = [
     "TagAssignment",
     "TraceAnnotator",
     "TraceColumn",
+    "TraceLimits",
     "TraceReader",
     "TraceSink",
     "TraceStore",

{reactifact-0.16.0 → reactifact-0.17.0}/reactifact/tracing/models.py

@@ -90,6 +90,20 @@ class TagAssignment(BaseModel):
     updated_at: datetime | None = None
 
 
+class AgentContract(BaseModel):
+    """The agent's declared contract, recorded on each span for the UI.
+
+    `consumes`/`produces`/`tools` are the *declared* names (not only what ran),
+    so the dashboard can show a consume/produce that never fired as a muted
+    chip instead of hiding it.
+    """
+
+    consumes: list[str] = Field(default_factory=list)
+    produces: list[str] = Field(default_factory=list)
+    tools: list[str] = Field(default_factory=list)
+    priority: int = 0
+
+
 class ProduceRun(BaseModel):
     """One produce execution within an agent span (§54).
 
@@ -104,6 +118,23 @@ class ProduceRun(BaseModel):
     latency_ms: float = 0.0
 
 
+class TraceLimits(BaseModel):
+    """Write-time limits for one recorded run.
+
+    Configure on the tracer (`Tracer(store=..., limits=TraceLimits(...))`),
+    not on `RuntimeResources`: these are recording policy, independent of the
+    app's providers/sources. When a cap is hit, extra data is dropped and the
+    trace is marked `trace_truncated` instead of growing without bound.
+    """
+
+    max_spans: int | None = 5000
+    max_refs_per_span: int | None = 50
+    max_llm_calls_per_span: int | None = 20
+    #: Per-artifact/response text cap. `None` = use
+    #: `RuntimeResources.trace_truncate` (the legacy setting).
+    max_data_chars: int | None = None
+
+
 class AgentSpan(BaseModel):
     """A single agent execution within a run (§54)."""
 
@@ -113,6 +144,10 @@ class AgentSpan(BaseModel):
     #: ``Consume``) — e.g. ``DraftAnswer`` vs ``FinalResponse`` for an agent that
     #: consumes both. ``event_type`` alone (created/updated) can't tell them apart.
     event_artifact_type: str = ""
+    #: The concrete artifact whose change triggered this span.
+    event_artifact_id: str = ""
+    #: The agent's declared consumes/produces/tools (for the UI contract view).
+    contract: AgentContract = Field(default_factory=AgentContract)
     #: The produces that ran for this event, in execution order.
     produces: list[ProduceRun] = Field(default_factory=list)
     #: Tool executions that happened during this agent run (name/latency/status).
@@ -135,6 +170,14 @@ class RunTrace(BaseModel):
     duration_ms: float = 0.0
     outcome: str = ""
     spans: list[AgentSpan] = Field(default_factory=list)
+    #: Total spans stored for this run (even when `spans` is a page).
+    span_total: int = 0
+    #: Offset of `spans` within the stored run (for pagination).
+    span_offset: int = 0
+    #: Whether the store has more spans beyond this page.
+    has_more_spans: bool = False
+    #: Whether the run was truncated while it was recorded (write-time cap).
+    trace_truncated: bool = False
     #: Reviewer annotations attached *after* the run (UI review workflow, §54).
     #: The runtime always leaves this empty; `TraceStore.get` populates it.
     annotations: list[TagAssignment] = Field(default_factory=list)

{reactifact-0.16.0 → reactifact-0.17.0}/reactifact/tracing/postgres.py

@@ -25,6 +25,7 @@ from typing import Any
 from ..tools import ToolRun
 from .columns import SpanArtifacts, TraceColumn, extract_columns
 from .models import (
+    AgentContract,
     AgentSpan,
     ArtifactRef,
     LLMCall,
@@ -39,11 +40,21 @@ from .store import _SORT_COLUMNS, _like
 class PostgresStore:
     """Postgres trace sink with async write + read. Requires the `pg` extra."""
 
-    def __init__(self, dsn: str):
+    def __init__(
+        self,
+        dsn: str,
+        *,
+        max_runs: int | None = 200,
+        column_scan_limit: int | None = 1000,
+        max_session_runs: int = 50,
+    ):
         from .._extras import require_extra
 
         self._psycopg = require_extra("PostgresStore", "psycopg", "pg")
         self.dsn = dsn
+        self.max_runs = max_runs
+        self.column_scan_limit = column_scan_limit
+        self.max_session_runs = max_session_runs
         self._schema_ready = False
 
     async def _ensure_schema(self) -> None:
@@ -61,7 +72,8 @@ class PostgresStore:
                         duration_ms REAL NOT NULL,
                         outcome TEXT NOT NULL,
                         prompt_tokens INTEGER NOT NULL DEFAULT 0,
-                        completion_tokens INTEGER NOT NULL DEFAULT 0
+                        completion_tokens INTEGER NOT NULL DEFAULT 0,
+                        truncated INTEGER NOT NULL DEFAULT 0
                     )
                     """
                 )
@@ -81,7 +93,9 @@ class PostgresStore:
                         relations JSONB NOT NULL DEFAULT '[]',
                         llm_calls JSONB NOT NULL DEFAULT '[]',
                         produces JSONB NOT NULL DEFAULT '[]',
-                        tools JSONB NOT NULL DEFAULT '[]'
+                        tools JSONB NOT NULL DEFAULT '[]',
+                        event_artifact_id TEXT NOT NULL DEFAULT '',
+                        contract JSONB NOT NULL DEFAULT '{}'
                     )
                     """
                 )
@@ -124,6 +138,10 @@ class PostgresStore:
                     "ALTER TABLE runs ADD COLUMN IF NOT EXISTS "
                     "completion_tokens INTEGER NOT NULL DEFAULT 0"
                 )
+                await cur.execute(
+                    "ALTER TABLE runs ADD COLUMN IF NOT EXISTS "
+                    "truncated INTEGER NOT NULL DEFAULT 0"
+                )
                 await cur.execute(
                     "ALTER TABLE spans ADD COLUMN IF NOT EXISTS started_at TIMESTAMPTZ"
                 )
@@ -139,6 +157,14 @@ class PostgresStore:
                     "ALTER TABLE spans ADD COLUMN IF NOT EXISTS "
                     "tools JSONB NOT NULL DEFAULT '[]'"
                 )
+                await cur.execute(
+                    "ALTER TABLE spans ADD COLUMN IF NOT EXISTS "
+                    "event_artifact_id TEXT NOT NULL DEFAULT ''"
+                )
+                await cur.execute(
+                    "ALTER TABLE spans ADD COLUMN IF NOT EXISTS "
+                    "contract JSONB NOT NULL DEFAULT '{}'"
+                )
             await conn.commit()
         finally:
             await conn.close()
@@ -159,8 +185,8 @@ class PostgresStore:
             async with conn.cursor() as cur:
                 await cur.execute(
                     "INSERT INTO runs (id, session_id, started_at, duration_ms, "
-                    "outcome, prompt_tokens, completion_tokens) "
-                    "VALUES (%s, %s, %s, %s, %s, %s, %s)",
+                    "outcome, prompt_tokens, completion_tokens, truncated) "
+                    "VALUES (%s, %s, %s, %s, %s, %s, %s, %s)",
                     (
                         trace.id,
                         trace.session_id,
@@ -169,6 +195,7 @@ class PostgresStore:
                         trace.outcome,
                         prompt_tokens,
                         completion_tokens,
+                        1 if trace.trace_truncated else 0,
                     ),
                 )
                 for span in trace.spans:
@@ -178,8 +205,8 @@ class PostgresStore:
                     await cur.execute(
                         "INSERT INTO spans (run_id, agent, event_type, event_artifact_type, "
                         "latency_ms, error, started_at, reads, writes, relations, llm_calls, "
-                        "produces, tools) "
-                        "VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s)",
+                        "produces, tools, event_artifact_id, contract) "
+                        "VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s)",
                         (
                             trace.id,
                             span.agent,
@@ -206,11 +233,91 @@ class PostgresStore:
                             psycopg.types.json.Jsonb(
                                 [tr.model_dump(mode="json") for tr in span.tools]
                             ),
+                            span.event_artifact_id,
+                            psycopg.types.json.Jsonb(
+                                span.contract.model_dump(mode="json")
+                            ),
                         ),
                     )
+            if self.max_runs is not None:
+                await self._prune_cur(cur, self.max_runs)
+            await conn.commit()
+        finally:
+            await conn.close()
+
+    async def _prune_cur(self, cur: Any, keep: int) -> int:
+        await cur.execute(
+            "SELECT id FROM runs ORDER BY started_at DESC, id DESC OFFSET %s",
+            (keep,),
+        )
+        ids = [r[0] for r in await cur.fetchall()]
+        if not ids:
+            return 0
+        placeholders = ",".join("%s" for _ in ids)
+        await cur.execute(
+            f"DELETE FROM spans WHERE run_id IN ({placeholders})", tuple(ids)
+        )
+        await cur.execute(
+            f"DELETE FROM run_tags WHERE run_id IN ({placeholders})", tuple(ids)
+        )
+        await cur.execute(f"DELETE FROM runs WHERE id IN ({placeholders})", tuple(ids))
+        return len(ids)
+
+    async def prune(self, keep: int | None = None) -> int:
+        keep = self.max_runs if keep is None else keep
+        if keep is None:
+            return 0
+        await self._ensure_schema()
+        conn = await self._psycopg.AsyncConnection.connect(self.dsn)
+        try:
+            async with conn.cursor() as cur:
+                removed = await self._prune_cur(cur, keep)
+            await conn.commit()
+        finally:
+            await conn.close()
+        return removed
+
+    async def delete_run(self, trace_id: str) -> bool:
+        await self._ensure_schema()
+        conn = await self._psycopg.AsyncConnection.connect(self.dsn)
+        try:
+            async with conn.cursor() as cur:
+                await cur.execute("SELECT 1 FROM runs WHERE id = %s", (trace_id,))
+                if await cur.fetchone() is None:
+                    return False
+                await cur.execute("DELETE FROM spans WHERE run_id = %s", (trace_id,))
+                await cur.execute("DELETE FROM run_tags WHERE run_id = %s", (trace_id,))
+                await cur.execute("DELETE FROM runs WHERE id = %s", (trace_id,))
+            await conn.commit()
+        finally:
+            await conn.close()
+        return True
+
+    async def delete_session(self, session_id: str) -> int:
+        await self._ensure_schema()
+        conn = await self._psycopg.AsyncConnection.connect(self.dsn)
+        try:
+            async with conn.cursor() as cur:
+                await cur.execute(
+                    "SELECT id FROM runs WHERE session_id = %s", (session_id,)
+                )
+                ids = [r[0] for r in await cur.fetchall()]
+                if not ids:
+                    return 0
+                placeholders = ",".join("%s" for _ in ids)
+                await cur.execute(
+                    f"DELETE FROM spans WHERE run_id IN ({placeholders})", tuple(ids)
+                )
+                await cur.execute(
+                    f"DELETE FROM run_tags WHERE run_id IN ({placeholders})", tuple(ids)
+                )
+                await cur.execute(
+                    f"DELETE FROM runs WHERE id IN ({placeholders})", tuple(ids)
+                )
             await conn.commit()
         finally:
             await conn.close()
+        return len(ids)
 
     def _where(
         self,
@@ -317,21 +424,32 @@ class PostgresStore:
                         )
                 fields_by_run: dict[str, dict[str, str]] = {}
                 if run_ids and columns:
-                    placeholders = ",".join("%s" for _ in run_ids)
-                    await cur.execute(
-                        "SELECT run_id, agent, reads, writes FROM spans "
-                        f"WHERE run_id IN ({placeholders}) ORDER BY id",
-                        tuple(run_ids),
-                    )
-                    spans_by_run: dict[str, list[SpanArtifacts]] = {}
-                    for run_id, agent, reads, writes in await cur.fetchall():
-                        spans_by_run.setdefault(run_id, []).append(
-                            SpanArtifacts(
-                                agent=agent,
-                                reads=[ArtifactRef(**d) for d in reads],
-                                writes=[ArtifactRef(**d) for d in writes],
+
+                    async def spans_of(
+                        ids: list[str],
+                    ) -> dict[str, list[SpanArtifacts]]:
+                        out: dict[str, list[SpanArtifacts]] = {}
+                        for rid in ids:
+                            sql = (
+                                "SELECT agent, reads, writes FROM spans "
+                                "WHERE run_id = %s ORDER BY id"
                             )
-                        )
+                            args: tuple[Any, ...] = (rid,)
+                            if self.column_scan_limit is not None:
+                                sql += " LIMIT %s"
+                                args = (rid, self.column_scan_limit)
+                            await cur.execute(sql, args)
+                            for agent, reads, writes in await cur.fetchall():
+                                out.setdefault(rid, []).append(
+                                    SpanArtifacts(
+                                        agent=agent,
+                                        reads=[ArtifactRef(**d) for d in reads],
+                                        writes=[ArtifactRef(**d) for d in writes],
+                                    )
+                                )
+                        return out
+
+                    spans_by_run = await spans_of(run_ids)
                     needs_session = any(c.scope == "session" for c in columns)
                     session_order: dict[str, list[tuple[str, list[SpanArtifacts]]]] = {}
                     if needs_session:
@@ -345,21 +463,10 @@ class PostgresStore:
                             ordered = [x[0] for x in await cur.fetchall()]
                             if not ordered:
                                 continue
-                            sph = ",".join("%s" for _ in ordered)
-                            await cur.execute(
-                                "SELECT run_id, agent, reads, writes FROM spans "
-                                f"WHERE run_id IN ({sph}) ORDER BY id",
-                                tuple(ordered),
-                            )
-                            by_run: dict[str, list[SpanArtifacts]] = {}
-                            for run_id, agent, reads, writes in await cur.fetchall():
-                                by_run.setdefault(run_id, []).append(
-                                    SpanArtifacts(
-                                        agent=agent,
-                                        reads=[ArtifactRef(**d) for d in reads],
-                                        writes=[ArtifactRef(**d) for d in writes],
-                                    )
-                                )
+                            if len(ordered) > self.max_session_runs:
+                                half = max(1, self.max_session_runs // 2)
+                                ordered = ordered[:half] + ordered[-half:]
+                            by_run = await spans_of(ordered)
                             session_order[sid] = [
                                 (rid, by_run.get(rid, [])) for rid in ordered
                             ]
@@ -393,18 +500,29 @@ class PostgresStore:
                 "spans": r[7],
                 "tags": tags_by_run.get(r[0], []),
                 "fields": fields_by_run.get(r[0], {}),
+                "fields_truncated": bool(
+                    columns
+                    and self.column_scan_limit is not None
+                    and r[7] > self.column_scan_limit
+                ),
             }
             for r in rows
         ]
         return {"items": items, "total": total, "stats": stats}
 
-    async def get(self, trace_id: str) -> RunTrace | None:
+    async def get(
+        self,
+        trace_id: str,
+        *,
+        span_limit: int | None = 500,
+        span_offset: int = 0,
+    ) -> RunTrace | None:
         await self._ensure_schema()
         conn = await self._psycopg.AsyncConnection.connect(self.dsn)
         try:
             async with conn.cursor() as cur:
                 await cur.execute(
-                    "SELECT id, session_id, started_at, duration_ms, outcome "
+                    "SELECT id, session_id, started_at, duration_ms, outcome, truncated "
                     "FROM runs WHERE id = %s",
                     (trace_id,),
                 )
@@ -412,11 +530,20 @@ class PostgresStore:
                 if row is None:
                     return None
                 await cur.execute(
-                    "SELECT agent, event_type, event_artifact_type, latency_ms, error, "
-                    "started_at, reads, writes, relations, llm_calls, produces, tools "
-                    "FROM spans WHERE run_id = %s ORDER BY id",
-                    (trace_id,),
+                    "SELECT COUNT(*) FROM spans WHERE run_id = %s", (trace_id,)
                 )
+                span_total = (await cur.fetchone())[0]
+                span_sql = (
+                    "SELECT agent, event_type, event_artifact_type, latency_ms, error, "
+                    "started_at, reads, writes, relations, llm_calls, produces, tools, "
+                    "event_artifact_id, contract "
+                    "FROM spans WHERE run_id = %s ORDER BY id"
+                )
+                span_args: tuple[Any, ...] = (trace_id,)
+                if span_limit is not None:
+                    span_sql += " LIMIT %s OFFSET %s"
+                    span_args = (trace_id, span_limit, span_offset)
+                await cur.execute(span_sql, span_args)
                 span_rows = await cur.fetchall()
                 await cur.execute(
                     "SELECT rt.tag, rt.note, COALESCE(t.color, ''), "
@@ -443,6 +570,8 @@ class PostgresStore:
                 llm_calls=[LLMCall(**d) for d in r[9]],
                 produces=[ProduceRun(**d) for d in r[10]],
                 tools=[ToolRun(**d) for d in r[11]],
+                event_artifact_id=r[12],
+                contract=AgentContract(**r[13]),
             )
             for r in span_rows
         ]
@@ -466,6 +595,10 @@ class PostgresStore:
             duration_ms=row[3],
             outcome=row[4],
             spans=spans,
+            span_total=span_total,
+            span_offset=span_offset,
+            has_more_spans=span_offset + len(spans) < span_total,
+            trace_truncated=bool(row[5]),
             annotations=annotations,
         )
 
@@ -489,21 +622,25 @@ class PostgresStore:
                 async def spans_of(
                     run_ids: list[str],
                 ) -> dict[str, list[SpanArtifacts]]:
-                    placeholders = ",".join("%s" for _ in run_ids)
-                    await cur.execute(
-                        "SELECT run_id, agent, reads, writes FROM spans "
-                        f"WHERE run_id IN ({placeholders}) ORDER BY id",
-                        tuple(run_ids),
-                    )
                     out: dict[str, list[SpanArtifacts]] = {}
-                    for rid, agent, reads, writes in await cur.fetchall():
-                        out.setdefault(rid, []).append(
-                            SpanArtifacts(
-                                agent=agent,
-                                reads=[ArtifactRef(**d) for d in reads],
-                                writes=[ArtifactRef(**d) for d in writes],
-                            )
+                    for rid in run_ids:
+                        sql = (
+                            "SELECT agent, reads, writes FROM spans "
+                            "WHERE run_id = %s ORDER BY id"
                         )
+                        args: tuple[Any, ...] = (rid,)
+                        if self.column_scan_limit is not None:
+                            sql += " LIMIT %s"
+                            args = (rid, self.column_scan_limit)
+                        await cur.execute(sql, args)
+                        for agent, reads, writes in await cur.fetchall():
+                            out.setdefault(rid, []).append(
+                                SpanArtifacts(
+                                    agent=agent,
+                                    reads=[ArtifactRef(**d) for d in reads],
+                                    writes=[ArtifactRef(**d) for d in writes],
+                                )
+                            )
                     return out
 
                 run_spans = (await spans_of([run_id])).get(run_id, [])
@@ -516,6 +653,9 @@ class PostgresStore:
                     )
                     ordered = [r[0] for r in await cur.fetchall()]
                     if ordered:
+                        if len(ordered) > self.max_session_runs:
+                            half = max(1, self.max_session_runs // 2)
+                            ordered = ordered[:half] + ordered[-half:]
                         by_run = await spans_of(ordered)
                         session_spans = []
                         for rid in ordered: