trace-agent-sdk 0.0.3__tar.gz → 0.2.0__tar.gz

{trace_agent_sdk-0.0.3 → trace_agent_sdk-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trace-agent-sdk
-Version: 0.0.3
+Version: 0.2.0
 Summary: TraceAgent SDK for instrumenting AI agents.
 Author-email: Enrique Javier Villar Cea <villarcea.enriquejavier@gmail.com>, Javier Rodriguez Castellano <javirodriguezcastellano@gmail.com>
 License: MIT
@@ -29,6 +29,7 @@ Requires-Dist: pytest<9.0.0,>=8.3.2; extra == "dev"
 ![GitHub Stars](https://img.shields.io/github/stars/LixusSoftware/TraceAgent)
 ![GitHub License](https://img.shields.io/github/license/LixusSoftware/TraceAgent)
 ![Tests](https://github.com/LixusSoftware/TraceAgent/actions/workflows/test.yml/badge.svg)
+[![Website](https://img.shields.io/badge/website-traceagent.vercel.app-blue)](https://traceagent.vercel.app)
 
 Python SDK for instrumenting AI agents and streaming events to a TraceAgent backend.
 

{trace_agent_sdk-0.0.3 → trace_agent_sdk-0.2.0}/README.md

@@ -4,6 +4,7 @@
 ![GitHub Stars](https://img.shields.io/github/stars/LixusSoftware/TraceAgent)
 ![GitHub License](https://img.shields.io/github/license/LixusSoftware/TraceAgent)
 ![Tests](https://github.com/LixusSoftware/TraceAgent/actions/workflows/test.yml/badge.svg)
+[![Website](https://img.shields.io/badge/website-traceagent.vercel.app-blue)](https://traceagent.vercel.app)
 
 Python SDK for instrumenting AI agents and streaming events to a TraceAgent backend.
 

{trace_agent_sdk-0.0.3 → trace_agent_sdk-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "trace-agent-sdk"
-version = "0.0.3"
+version = "0.2.0"
 description = "TraceAgent SDK for instrumenting AI agents."
 readme = "README.md"
 authors = [

{trace_agent_sdk-0.0.3 → trace_agent_sdk-0.2.0}/src/trace_agent_sdk/client.py

@@ -8,7 +8,7 @@ import subprocess
 import time
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any, Callable
+from typing import Any, Callable, get_type_hints
 from uuid import uuid4
 
 import httpx
@@ -469,6 +469,34 @@ class RunSession:
             record_retriever_events=record_retriever_events,
         )
 
+    def as_pydantic_ai_capability(
+        self,
+        *,
+        record_model_events: bool = True,
+        record_tool_events: bool = True,
+        record_node_events: bool = False,
+        redact_fields: list[str] | None = None,
+        failure_cooldown: float = 30.0,
+        flush_timeout: float = 5.0,
+    ) -> Any:
+        """Return a Pydantic AI capability bound to this run.
+
+        Usage:
+            agent = Agent("openai:gpt-4o", capabilities=[run.as_pydantic_ai_capability()])
+            agent.run_sync("...")
+        """
+        from trace_agent_pydantic_ai import TraceAgentCapability
+
+        return TraceAgentCapability(
+            self,
+            record_model_events=record_model_events,
+            record_tool_events=record_tool_events,
+            record_node_events=record_node_events,
+            redact_fields=redact_fields or [],
+            failure_cooldown=failure_cooldown,
+            flush_timeout=flush_timeout,
+        )
+
     def _execute_tool(self, call: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]:
         binding = self.tools.get(call["name"])
         if binding is None:
@@ -520,10 +548,15 @@ class RunSession:
 
     def _build_input_schema(self, func: Callable[..., Any]) -> dict[str, Any]:
         signature = inspect.signature(func)
+        try:
+            # Resolves postponed annotations ("int" under `from __future__ import annotations`).
+            hints = get_type_hints(func)
+        except Exception:
+            hints = {}
         properties: dict[str, Any] = {}
         required: list[str] = []
         for parameter_name, parameter in signature.parameters.items():
-            annotation = parameter.annotation if parameter.annotation is not inspect._empty else str
+            annotation = hints.get(parameter_name, parameter.annotation if parameter.annotation is not inspect._empty else str)
             properties[parameter_name] = {"type": TYPE_MAP.get(annotation, "string")}
             if parameter.default is inspect._empty:
                 required.append(parameter_name)

{trace_agent_sdk-0.0.3 → trace_agent_sdk-0.2.0}/src/trace_agent_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trace-agent-sdk
-Version: 0.0.3
+Version: 0.2.0
 Summary: TraceAgent SDK for instrumenting AI agents.
 Author-email: Enrique Javier Villar Cea <villarcea.enriquejavier@gmail.com>, Javier Rodriguez Castellano <javirodriguezcastellano@gmail.com>
 License: MIT
@@ -29,6 +29,7 @@ Requires-Dist: pytest<9.0.0,>=8.3.2; extra == "dev"
 ![GitHub Stars](https://img.shields.io/github/stars/LixusSoftware/TraceAgent)
 ![GitHub License](https://img.shields.io/github/license/LixusSoftware/TraceAgent)
 ![Tests](https://github.com/LixusSoftware/TraceAgent/actions/workflows/test.yml/badge.svg)
+[![Website](https://img.shields.io/badge/website-traceagent.vercel.app-blue)](https://traceagent.vercel.app)
 
 Python SDK for instrumenting AI agents and streaming events to a TraceAgent backend.
 

{trace_agent_sdk-0.0.3 → trace_agent_sdk-0.2.0}/src/trace_agent_sdk.egg-info/SOURCES.txt

@@ -7,4 +7,6 @@ src/trace_agent_sdk.egg-info/PKG-INFO
 src/trace_agent_sdk.egg-info/SOURCES.txt
 src/trace_agent_sdk.egg-info/dependency_links.txt
 src/trace_agent_sdk.egg-info/requires.txt
-src/trace_agent_sdk.egg-info/top_level.txt
+src/trace_agent_sdk.egg-info/top_level.txt
+tests/test_client.py
+tests/test_redaction.py

trace_agent_sdk-0.2.0/tests/test_client.py

@@ -0,0 +1,241 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+import pytest
+
+from trace_agent_sdk import RunSession, TraceAgentClient
+
+
+class Backend:
+    """In-memory stand-in for the TraceAgent API that records every request."""
+
+    def __init__(self) -> None:
+        self.requests: list[tuple[str, str, dict[str, Any]]] = []
+        self.responses: dict[str, list[httpx.Response]] = {}
+
+    def queue(self, path_suffix: str, *responses: httpx.Response) -> None:
+        self.responses.setdefault(path_suffix, []).extend(responses)
+
+    def __call__(self, request: httpx.Request) -> httpx.Response:
+        body = json.loads(request.content) if request.content else {}
+        self.requests.append((request.method, request.url.path, body))
+        for suffix, queued in self.responses.items():
+            if request.url.path.endswith(suffix) and queued:
+                return queued.pop(0)
+        if request.url.path == "/api/runs":
+            return httpx.Response(200, json={"run_id": "run-1"})
+        return httpx.Response(200, json={"status": "ok"})
+
+    def observations(self, kind: str | None = None) -> list[dict[str, Any]]:
+        found = [
+            obs
+            for _, path, body in self.requests
+            if path.endswith("/observations")
+            for obs in body["observations"]
+        ]
+        return [obs for obs in found if kind is None or obs["kind"] == kind]
+
+
+@pytest.fixture
+def backend() -> Backend:
+    return Backend()
+
+
+@pytest.fixture
+def client(backend) -> TraceAgentClient:
+    http = httpx.Client(transport=httpx.MockTransport(backend), base_url="http://trace.test")
+    return TraceAgentClient(base_url="http://trace.test", http_client=http)
+
+
+@pytest.fixture
+def run(client) -> RunSession:
+    return client.start_run("agent", "goal", metadata={"env": "test"})
+
+
+class TestClient:
+    def test_start_run_posts_and_returns_a_bound_session(self, client, backend) -> None:
+        session = client.start_run("agent", "goal", metadata={"env": "test"})
+
+        assert session.run_id == "run-1"
+        assert (session.agent_name, session.goal, session.metadata) == ("agent", "goal", {"env": "test"})
+        assert backend.requests[0] == ("POST", "/api/runs", {"agent_name": "agent", "goal": "goal", "metadata": {"env": "test"}})
+
+    def test_error_responses_raise_with_the_server_detail(self, client, backend) -> None:
+        backend.queue("/api/runs", httpx.Response(404, json={"detail": "Run not found."}))
+
+        with pytest.raises(httpx.HTTPStatusError, match="404 for /api/runs: Run not found."):
+            client.start_run("agent", "goal")
+
+    def test_error_responses_without_json_fall_back_to_the_body_text(self, client, backend) -> None:
+        backend.queue("/api/runs", httpx.Response(502, text="bad gateway"))
+
+        with pytest.raises(httpx.HTTPStatusError, match="bad gateway"):
+            client.start_run("agent", "goal")
+
+    def test_api_key_and_base_url_configure_the_http_client(self) -> None:
+        client = TraceAgentClient(base_url="http://trace.test/", api_key="secret")
+
+        assert client.http.headers["Authorization"] == "Bearer secret"
+        assert str(client.http.base_url).rstrip("/") == "http://trace.test"
+
+
+class TestRecording:
+    def test_command_renders_lists_and_summarizes_output(self, run, backend) -> None:
+        run.record_command(["python", "-m", "pytest"], status="failed", output={"stdout": "x"}, exit_code=1, cwd=".")
+
+        obs = backend.observations("command")[0]
+        assert obs["command"] == "python -m pytest"
+        assert obs["status"] == "failed"
+        assert obs["exit_code"] == 1
+        assert obs["step_id"].startswith("command-")
+        assert json.loads(obs["output_summary"]) == {"stdout": "x"}
+
+    def test_file_read_hashes_the_content(self, run, backend) -> None:
+        run.record_file_read("src/app.py", content="print('x')")
+
+        obs = backend.observations("file_read")[0]
+        assert obs["path"] == "src/app.py"
+        assert obs["extension"] == ".py"
+        assert obs["size_bytes"] == len("print('x')")
+        assert len(obs["content_hash"]) == 64
+
+    def test_file_write_counts_added_and_removed_lines(self, run, backend) -> None:
+        run.record_file_write("a.txt", change_type="update", before_content="one\ntwo\n", after_content="one\nthree\nfour\n")
+
+        obs = backend.observations("file_write")[0]
+        assert (obs["line_additions"], obs["line_deletions"]) == (2, 1)
+        assert obs["before_hash"] != obs["after_hash"]
+        assert obs["change_type"] == "update"
+
+    def test_file_write_without_changes_reports_no_diff(self, run, backend) -> None:
+        run.record_file_write("a.txt", before_content="same", after_content="same")
+
+        obs = backend.observations("file_write")[0]
+        assert obs["diff_summary"] == "No textual diff."
+        assert (obs["line_additions"], obs["line_deletions"]) == (0, 0)
+
+    def test_patch_prefers_the_given_diff_text(self, run, backend) -> None:
+        run.record_patch("a.py", diff_text="--- custom diff", before_content="a", after_content="b")
+
+        assert backend.observations("patch")[0]["diff_summary"] == "--- custom diff"
+
+    def test_artifact_carries_a_content_hash(self, run, backend) -> None:
+        run.record_artifact("report", "weekly", "summary", content={"k": 1}, metadata={"source": "test"})
+
+        artifact = backend.observations("artifact")[0]["artifact"]
+        assert (artifact["kind"], artifact["label"]) == ("report", "weekly")
+        assert artifact["metadata"]["source"] == "test"
+        assert len(artifact["metadata"]["content_hash"]) == 64
+
+    def test_finish_and_fail_payloads(self, run, backend) -> None:
+        run.finish("done", artifacts=[{"kind": "k"}])
+        run.fail("ValueError", "boom")
+
+        assert backend.requests[-2] == ("POST", "/api/runs/run-1/finish", {"final_output": "done", "artifacts": [{"kind": "k"}]})
+        assert backend.requests[-1] == ("POST", "/api/runs/run-1/fail", {"error_code": "ValueError", "error_summary": "boom"})
+
+
+class TestToolsAndTurns:
+    def test_tool_decorator_builds_the_input_schema(self, run) -> None:
+        @run.tool(description="Look things up", redact_fields=["api_key"])
+        def search(query: str, limit: int = 5, exact: bool = False) -> str:
+            return query
+
+        binding = run.tools["search"]
+        assert binding.description == "Look things up"
+        assert binding.redact_fields == ["api_key"]
+        assert binding.input_schema == {
+            "type": "object",
+            "properties": {"query": {"type": "string"}, "limit": {"type": "integer"}, "exact": {"type": "boolean"}},
+            "required": ["query"],
+        }
+
+    def test_tool_description_defaults_to_the_docstring(self, run) -> None:
+        @run.tool()
+        def lookup(item: str) -> str:
+            """Find an item."""
+            return item
+
+        assert run.tools["lookup"].description == "Find an item."
+
+    def test_model_turn_runs_requested_tools_and_returns_the_answer(self, run, backend) -> None:
+        @run.tool()
+        def get_weather(city: str) -> str:
+            return f"Sunny in {city}"
+
+        backend.queue(
+            "/turns",
+            httpx.Response(
+                200,
+                json={
+                    "status": "requires_action",
+                    "tool_calls": [{"id": "call-1", "name": "get_weather", "arguments": {"city": "Madrid"}, "step_id": "step-1"}],
+                },
+            ),
+            httpx.Response(200, json={"status": "message", "assistant_message": {"role": "assistant", "content": "It is sunny."}}),
+        )
+
+        result = run.create_model_turn([{"role": "user", "content": "Weather?"}], model="m")
+
+        assert result.assistant_message["content"] == "It is sunny."
+        assert [t["name"] for t in result.executed_tools] == ["get_weather"]
+        posted = next(body for _, path, body in backend.requests if path.endswith("/tool-results"))["results"][0]
+        assert posted["status"] == "succeeded"
+        assert posted["args"] == {"city": "Madrid"}
+        assert posted["step_id"] == "step-1"
+        roles = [m["role"] for m in run.messages]
+        assert roles == ["user", "assistant", "tool", "assistant"]
+
+    def test_a_failing_tool_is_reported_and_the_error_goes_back_to_the_model(self, run, backend) -> None:
+        @run.tool()
+        def fetch(url: str) -> str:
+            raise ConnectionError("down")
+
+        backend.queue(
+            "/turns",
+            httpx.Response(
+                200,
+                json={"status": "requires_action", "tool_calls": [{"id": "c", "name": "fetch", "arguments": {"url": "u"}, "step_id": "s"}]},
+            ),
+            httpx.Response(200, json={"status": "message", "assistant_message": {"role": "assistant", "content": "failed"}}),
+        )
+
+        run.create_model_turn([{"role": "user", "content": "go"}], model="m")
+
+        posted = next(body for _, path, body in backend.requests if path.endswith("/tool-results"))["results"][0]
+        assert (posted["status"], posted["error_code"], posted["error_summary"]) == ("failed", "ConnectionError", "down")
+        tool_message = next(m for m in run.messages if m["role"] == "tool")
+        assert json.loads(tool_message["content"]) == {"error": "down"}
+
+    def test_calling_an_unregistered_tool_raises(self, run) -> None:
+        with pytest.raises(KeyError, match="not registered"):
+            run._execute_tool({"id": "c", "name": "ghost", "arguments": {}, "step_id": "s"})
+
+    def test_redacted_tool_output_is_masked_in_the_summary(self, run) -> None:
+        @run.tool(redact_fields=["token"])
+        def login(user: str) -> dict:
+            return {"user": user, "token": "abc123"}
+
+        payload, _ = run._execute_tool({"id": "c", "name": "login", "arguments": {"user": "ann"}, "step_id": "s"})
+
+        assert "abc123" not in payload["output_summary"]
+        assert "[redacted]" in payload["output_summary"]
+
+
+class TestIntegrationsFactories:
+    def test_langchain_callback_is_bound_to_the_run(self, run) -> None:
+        pytest.importorskip("trace_agent_langchain")
+        callback = run.as_langchain_callback(record_chain_events=False)
+
+        assert callback.run_session is run
+        assert callback.record_chain_events is False
+
+    def test_pydantic_ai_capability_is_bound_to_the_run(self, run) -> None:
+        pytest.importorskip("trace_agent_pydantic_ai")
+        capability = run.as_pydantic_ai_capability(record_node_events=True, failure_cooldown=5, flush_timeout=1)
+
+        assert capability.run_session is run
+        assert (capability.record_node_events, capability.failure_cooldown, capability.flush_timeout) == (True, 5, 1)

trace_agent_sdk-0.2.0/tests/test_redaction.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from trace_agent_sdk.redaction import redact_payload, stable_hash, summarize_value
+
+
+class TestStableHash:
+    def test_is_independent_of_key_order(self) -> None:
+        assert stable_hash({"a": 1, "b": [1, 2]}) == stable_hash({"b": [1, 2], "a": 1})
+
+    def test_differs_for_different_values(self) -> None:
+        assert stable_hash({"a": 1}) != stable_hash({"a": 2})
+
+    def test_handles_values_json_cannot_encode(self) -> None:
+        assert stable_hash({"when": object}) == stable_hash({"when": object})
+
+
+class TestRedactPayload:
+    def test_redacts_listed_fields_at_any_depth(self) -> None:
+        payload = {"token": "abc", "nested": {"token": "def", "keep": 1}, "items": [{"token": "ghi"}]}
+
+        redacted = redact_payload(payload, ["token"])
+
+        assert redacted == {"token": "[redacted]", "nested": {"token": "[redacted]", "keep": 1}, "items": [{"token": "[redacted]"}]}
+
+    def test_does_not_mutate_the_input(self) -> None:
+        payload = {"token": "abc"}
+        redact_payload(payload, ["token"])
+        assert payload == {"token": "abc"}
+
+    def test_truncates_long_strings_but_not_short_ones(self) -> None:
+        assert redact_payload("short") == "short"
+        long_value = "x" * 500
+        redacted = redact_payload(long_value)
+        assert len(redacted) == 160
+        assert redacted.endswith("...")
+
+    def test_leaves_other_types_untouched(self) -> None:
+        assert redact_payload({"n": 3, "ok": True, "none": None}) == {"n": 3, "ok": True, "none": None}
+
+
+class TestSummarizeValue:
+    def test_strings_are_returned_as_is(self) -> None:
+        assert summarize_value("hello") == "hello"
+
+    def test_dicts_are_rendered_as_sorted_json(self) -> None:
+        assert summarize_value({"b": 1, "a": 2}) == '{"a": 2, "b": 1}'
+
+    def test_output_is_capped_at_max_length(self) -> None:
+        summary = summarize_value({"items": list(range(500))}, max_length=50)
+        assert len(summary) == 50
+        assert summary.endswith("...")
+
+    def test_applies_redaction(self) -> None:
+        assert "secret" not in summarize_value({"password": "secret"}, ["password"])