trace-agent-server 0.7.0__tar.gz → 0.8.0__tar.gz

{trace_agent_server-0.7.0 → trace_agent_server-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trace-agent-server
-Version: 0.7.0
+Version: 0.8.0
 Summary: TraceAgent FastAPI backend server.
 Author-email: Enrique Javier Villar Cea <villarcea.enriquejavier@gmail.com>, Javier Rodriguez Castellano <javirodriguezcastellano@gmail.com>
 License: MIT

{trace_agent_server-0.7.0 → trace_agent_server-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "trace-agent-server"
-version = "0.7.0"
+version = "0.8.0"
 description = "TraceAgent FastAPI backend server."
 readme = "README.md"
 authors = [

{trace_agent_server-0.7.0 → trace_agent_server-0.8.0}/src/trace_agent_server/schemas.py

@@ -60,6 +60,8 @@ class ToolResultInput(BaseModel):
     parent_step_id: str | None = None
     status: Literal["succeeded", "failed"]
     args: dict[str, Any] = Field(default_factory=dict)
+    # Hash of the arguments as the tool received them (the ones in args may have long texts cut).
+    args_hash: str | None = None
     output_summary: str | None = None
     # What the tool returned, whole (masked by the sender). Stored only with full payloads on.
     output: Any | None = None

{trace_agent_server-0.7.0 → trace_agent_server-0.8.0}/src/trace_agent_server/services/explanation.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import re
 from collections import defaultdict
 from typing import Any
 
@@ -9,6 +10,17 @@ from sqlalchemy.orm import Session
 from trace_agent_server.models import Decision, Event, Run
 
 
+def command_title(command: str, limit: int = 80) -> str:
+    """A short name for a command, not its whole text: the first comment of a script says what it does; without
+    one, its first line that is not an import."""
+    code = re.sub(r"^\s*(?:python3?|py)\s+-c\s+", "", command)
+    lines = [line.strip() for line in code.splitlines() if line.strip()]
+    comment = next((line.lstrip("#").strip() for line in lines if line.startswith("#")), None)
+    first_code = next((line for line in lines if not line.startswith("#") and not re.match(r"(?:import|from)\s", line)), None)
+    text = " ".join((comment or first_code or (lines[0] if lines else command)).split())
+    return text if len(text) <= limit else f"{text[: limit - 1]}…"
+
+
 def derive_explanation(session: Session, run: Run) -> dict[str, Any]:
     events = list(session.scalars(select(Event).where(Event.run_id == run.id).order_by(Event.seq)))
     session.execute(delete(Decision).where(Decision.run_id == run.id))
@@ -17,6 +29,7 @@ def derive_explanation(session: Session, run: Run) -> dict[str, Any]:
     flags: list[dict[str, Any]] = []
     seen_flags: set[tuple[str, str]] = set()
     loop_tracker: dict[tuple[str, str], list[Event]] = defaultdict(list)
+    loop_flags: dict[tuple[str, str], dict[str, Any]] = {}
     failure_streaks: dict[str, int] = defaultdict(int)
     last_failure_by_tool: dict[str, Event] = {}
     last_failure_by_command: dict[str, Event] = {}
@@ -78,13 +91,17 @@ def derive_explanation(session: Session, run: Run) -> dict[str, Any]:
             # "Started X." is identical for every call, so tell calls apart by their arguments.
             key = (tool_name, (event.payload_hash or event.summary) if derived_request else event.summary)
             loop_tracker[key].append(event)
-            if len(loop_tracker[key]) >= 3:
-                add_flag(
-                    "loop",
-                    f"{tool_name} repeated {len(loop_tracker[key])} times without a new observable branch.",
-                    [item.id for item in loop_tracker[key][-3:]],
-                    {"tool_name": tool_name},
-                )
+            repeats = len(loop_tracker[key])
+            if repeats >= 3:
+                # One flag per repeated call, kept up to date, not a new flag for every repetition.
+                flag = loop_flags.get(key)
+                if flag is None:
+                    flag = {"type": "loop", "label": "", "event_ids": [], "metadata": {"tool_name": tool_name}}
+                    loop_flags[key] = flag
+                    flags.append(flag)
+                flag["label"] = f"{tool_name} was called {repeats} times with the same arguments."
+                flag["event_ids"] = [item.id for item in loop_tracker[key]]
+                flag["metadata"] = {"tool_name": tool_name, "count": repeats}
             if tool_name in last_failure_by_tool:
                 failed_event = last_failure_by_tool[tool_name]
                 retry_count += 1
@@ -141,9 +158,10 @@ def derive_explanation(session: Session, run: Run) -> dict[str, Any]:
             command_name = str(event.event_metadata.get("command") or "unknown command")
             last_failure_by_command[command_name] = event
             failure_streaks[event.step_id or command_name] += 1
+            exit_code = event.event_metadata.get("exit_code")
             add_flag(
                 "command_failure",
-                f"{command_name} failed and may have blocked the run.",
+                f"Command failed{f' (exit code {exit_code})' if exit_code is not None else ''}: {command_title(command_name)}",
                 [event.id],
                 {"command": command_name, "step_id": event.step_id},
             )

{trace_agent_server-0.7.0 → trace_agent_server-0.8.0}/src/trace_agent_server/services/otlp.py

@@ -372,6 +372,7 @@ def _tool_steps(session: Session, run: Run, span: SpanRecord, capture_full: bool
         parent_step_id=span.parent_span_id,
         status="failed" if failed else "succeeded",
         args=redact_payload(arguments if isinstance(arguments, dict) else {"input": arguments} if arguments is not None else {}),
+        args_hash=stable_hash(arguments),
         output_summary=summarize_value(_readable(result_text), sort_keys=False) if result_text is not None else None,
         output=_parse_json(result_text) if result_text is not None and not failed else None,
         output_hash=stable_hash(result_text if not failed else {"error": message}),

{trace_agent_server-0.7.0 → trace_agent_server-0.8.0}/src/trace_agent_server/services/run_lifecycle.py

@@ -67,7 +67,9 @@ def record_tool_result(
         step_id=result.step_id,
         parent_step_id=result.parent_step_id,
         tool_name=result.name,
-        payload_hash=stable_hash(result.args),
+        # The sender hashes the whole arguments: the ones it sends have long texts cut, so two calls that differ
+        # only after the cut would look the same (and be flagged as a loop).
+        payload_hash=result.args_hash or stable_hash(result.args),
         payload_full={"args": result.args} if capture_full else None,
         metadata={"call_id": result.call_id, "args_summary": summarize_value(result.args)},
         timestamp=started_at,

{trace_agent_server-0.7.0 → trace_agent_server-0.8.0}/src/trace_agent_server.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trace-agent-server
-Version: 0.7.0
+Version: 0.8.0
 Summary: TraceAgent FastAPI backend server.
 Author-email: Enrique Javier Villar Cea <villarcea.enriquejavier@gmail.com>, Javier Rodriguez Castellano <javirodriguezcastellano@gmail.com>
 License: MIT

{trace_agent_server-0.7.0 → trace_agent_server-0.8.0}/src/trace_agent_server.egg-info/SOURCES.txt

@@ -35,6 +35,7 @@ tests/test_audit_guardrails_api.py
 tests/test_concurrent_writers.py
 tests/test_dashboard.py
 tests/test_events.py
+tests/test_flags.py
 tests/test_framework_observations.py
 tests/test_graph.py
 tests/test_inactivity_sweep.py

trace_agent_server-0.8.0/tests/test_flags.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import pytest
+from fastapi.testclient import TestClient
+
+from trace_agent_server.config import Settings
+from trace_agent_server.main import create_app
+from trace_agent_server.services.explanation import command_title
+
+SCRIPT = "python -c \n# OEE de las líneas del 14 al 18 de septiembre\nimport json\nkpis = kpis('L1')\nprint(kpis)"
+
+
+@pytest.fixture
+def client(tmp_path) -> TestClient:
+    return TestClient(create_app(Settings(database_url=f"sqlite:///{tmp_path / 'flags.db'}", cors_origins=["http://localhost:5173"])))
+
+
+def run_with_command(client: TestClient, **observation) -> dict:
+    run_id = client.post("/api/runs", json={"agent_name": "a", "goal": "g"}).json()["run_id"]
+    body = {"kind": "command", "step_id": "c1", **observation}
+    assert client.post(f"/api/runs/{run_id}/observations", json={"observations": [body]}).status_code == 200
+    assert client.post(f"/api/runs/{run_id}/finish", json={"final_output": "done"}).status_code == 200
+    return client.get(f"/api/runs/{run_id}/explanation").json()
+
+
+class TestCommandTitle:
+    def test_uses_the_first_comment_of_a_script(self) -> None:
+        assert command_title(SCRIPT) == "OEE de las líneas del 14 al 18 de septiembre"
+
+    def test_without_a_comment_uses_the_first_line_that_is_not_an_import(self) -> None:
+        assert command_title("python -c \nimport json\nfrom os import path\nvalor = 1\nprint(valor)") == "valor = 1"
+
+    def test_a_plain_command_stays_and_a_long_one_is_cut(self) -> None:
+        assert command_title("pytest -q packages") == "pytest -q packages"
+        cut = command_title("python3 -c " + "x = 1; " * 60)
+        assert len(cut) == 80
+        assert cut.endswith("…")
+
+
+class TestCommandFailureFlag:
+    def test_says_what_failed_and_with_what_code_instead_of_dumping_the_script(self, client) -> None:
+        flags = run_with_command(client, command=SCRIPT, status="failed", exit_code=1)["flags"]
+
+        failure = next(flag for flag in flags if flag["type"] == "command_failure")
+        assert failure["label"] == "Command failed (exit code 1): OEE de las líneas del 14 al 18 de septiembre"
+        assert "import json" not in failure["label"]
+
+    def test_without_an_exit_code_it_still_reads(self, client) -> None:
+        flags = run_with_command(client, command="pytest -q", status="failed")["flags"]
+
+        failure = next(flag for flag in flags if flag["type"] == "command_failure")
+        assert failure["label"] == "Command failed: pytest -q"

{trace_agent_server-0.7.0 → trace_agent_server-0.8.0}/tests/test_framework_observations.py

@@ -269,6 +269,38 @@ class TestDecisionsFromFrameworkTools:
         flags = explanation(client, run_id)["flags"]
         assert any(flag["type"] == "loop" for flag in flags)
 
+    def test_a_repeated_call_is_one_flag_with_its_count_in_plain_words(self, client) -> None:
+        run_id = start_run(client)
+        for step in ("t1", "t2", "t3", "t4", "t5", "t6"):
+            post_tool(client, run_id, step, "search", args={"q": "same"})
+
+        loops = [flag for flag in explanation(client, run_id)["flags"] if flag["type"] == "loop"]
+
+        assert len(loops) == 1
+        assert loops[0]["label"] == "search was called 6 times with the same arguments."
+        assert loops[0]["metadata"]["count"] == 6
+        assert len(loops[0]["event_ids"]) == 6
+
+    def test_different_programs_that_share_a_long_start_are_not_a_loop(self, client) -> None:
+        # The arguments are cut at 160 characters before they are sent: what tells the calls apart is their hash.
+        run_id = start_run(client)
+        common = "# OEE de las lineas del 14 al 18 de septiembre " * 6
+        for step, ending in (("t1", "kpis('L1')"), ("t2", "kpis('L2')"), ("t3", "kpis('L3')")):
+            result = {"call_id": step, "name": "ejecutar_python", "step_id": step, "status": "succeeded",
+                      "args": {"codigo": common[:157] + "..."}, "args_hash": f"hash-of-the-whole-{ending}"}
+            assert client.post(f"/api/runs/{run_id}/tool-results", json={"results": [result]}).status_code == 200
+
+        assert not any(flag["type"] == "loop" for flag in explanation(client, run_id)["flags"])
+
+    def test_the_same_whole_arguments_are_a_loop_even_when_what_was_sent_was_cut(self, client) -> None:
+        run_id = start_run(client)
+        for step in ("t1", "t2", "t3"):
+            result = {"call_id": step, "name": "ejecutar_python", "step_id": step, "status": "succeeded",
+                      "args": {"codigo": "x" * 157 + "..."}, "args_hash": "the-same-program"}
+            client.post(f"/api/runs/{run_id}/tool-results", json={"results": [result]})
+
+        assert any(flag["type"] == "loop" for flag in explanation(client, run_id)["flags"])
+
     def test_the_same_tool_with_different_arguments_is_not_a_loop(self, client) -> None:
         run_id = start_run(client)
         for step, query in (("t1", "a"), ("t2", "b"), ("t3", "c")):