agentshadow 0.1.0__tar.gz

agentshadow-0.1.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: agentshadow
+Version: 0.1.0
+Summary: AgentTrace Python SDK
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: async
+Requires-Dist: aiohttp>=3.9; extra == "async"
+
+# SDK Environment
+
+Use `uv` for local development:
+
+```bash
+cd sdk
+uv sync --dev
+source .venv/bin/activate
+pytest -q
+```

agentshadow-0.1.0/README.md

@@ -0,0 +1,10 @@
+# SDK Environment
+
+Use `uv` for local development:
+
+```bash
+cd sdk
+uv sync --dev
+source .venv/bin/activate
+pytest -q
+```

agentshadow-0.1.0/agentshadow.egg-info/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: agentshadow
+Version: 0.1.0
+Summary: AgentTrace Python SDK
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: async
+Requires-Dist: aiohttp>=3.9; extra == "async"
+
+# SDK Environment
+
+Use `uv` for local development:
+
+```bash
+cd sdk
+uv sync --dev
+source .venv/bin/activate
+pytest -q
+```

agentshadow-0.1.0/agentshadow.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+README.md
+pyproject.toml
+agentshadow.egg-info/PKG-INFO
+agentshadow.egg-info/SOURCES.txt
+agentshadow.egg-info/dependency_links.txt
+agentshadow.egg-info/requires.txt
+agentshadow.egg-info/top_level.txt
+agenttrace/__init__.py
+agenttrace/client.py
+agenttrace/contracts.py
+agenttrace/crewai.py
+agenttrace/langchain.py
+agenttrace/llamaindex.py
+agenttrace/trace.py
+tests/test_contracts.py
+tests/test_crewai_callback.py
+tests/test_langchain_callback.py
+tests/test_llamaindex_callback.py
+tests/test_trace.py

agentshadow-0.1.0/agentshadow.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agentshadow-0.1.0/agentshadow.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[async]
+aiohttp>=3.9

agentshadow-0.1.0/agentshadow.egg-info/top_level.txt

@@ -0,0 +1 @@
+agenttrace

agentshadow-0.1.0/agenttrace/__init__.py

@@ -0,0 +1,28 @@
+from agenttrace.contracts import Run, Span, SpanType, build_ingest_payload
+from agenttrace.langchain import AgentTraceCallbackHandler
+from agenttrace.trace import RunTraceContext, trace
+
+
+def __getattr__(name: str):
+    if name == "AgentTraceCrewAIHandler":
+        from agenttrace.crewai import AgentTraceCrewAIHandler
+
+        return AgentTraceCrewAIHandler
+    if name == "AgentTraceLlamaIndexHandler":
+        from agenttrace.llamaindex import AgentTraceLlamaIndexHandler
+
+        return AgentTraceLlamaIndexHandler
+    raise AttributeError(f"module 'agenttrace' has no attribute {name!r}")
+
+
+__all__ = [
+    "AgentTraceCallbackHandler",
+    "AgentTraceCrewAIHandler",
+    "AgentTraceLlamaIndexHandler",
+    "Run",
+    "RunTraceContext",
+    "Span",
+    "SpanType",
+    "build_ingest_payload",
+    "trace",
+]

agentshadow-0.1.0/agenttrace/client.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+from urllib import request
+
+
+class IngestClient:
+    def __init__(self, api_url: str, api_key: str | None = None, timeout_seconds: float = 5.0) -> None:
+        self.api_url = api_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout_seconds = timeout_seconds
+
+    @classmethod
+    def from_env(cls) -> IngestClient | None:
+        api_url = os.getenv("AGENTTRACE_API_URL")
+        if not api_url:
+            return None
+        api_key = os.getenv("AGENTTRACE_API_KEY")
+        return cls(api_url=api_url, api_key=api_key)
+
+    def ingest(self, payload: dict[str, Any]) -> None:
+        data = json.dumps(payload).encode("utf-8")
+        url = f"{self.api_url}/v1/ingest"
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        req = request.Request(url=url, data=data, headers=headers, method="POST")
+        with request.urlopen(req, timeout=self.timeout_seconds):
+            return
+
+    async def async_ingest(self, payload: dict[str, Any]) -> None:
+        import aiohttp
+
+        data = json.dumps(payload).encode("utf-8")
+        url = f"{self.api_url}/v1/ingest"
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        async with aiohttp.ClientSession() as session:
+            async with session.post(
+                url, data=data, headers=headers, timeout=aiohttp.ClientTimeout(total=self.timeout_seconds)
+            ):
+                return

agentshadow-0.1.0/agenttrace/contracts.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from datetime import datetime
+from typing import Any, Literal
+from uuid import UUID
+
+SpanType = Literal["llm", "tool", "retrieval", "chain", "agent"]
+
+
+def _ensure_json_serializable(value: Any, field_name: str) -> None:
+    try:
+        json.dumps(value)
+    except TypeError as exc:
+        raise ValueError(f"{field_name} must be JSON serializable") from exc
+
+
+@dataclass(slots=True)
+class Run:
+    run_id: UUID
+    name: str
+    created_at: datetime
+    metadata_json: dict[str, Any] = field(default_factory=dict)
+
+    def validate(self) -> None:
+        if not self.name:
+            raise ValueError("run.name must be non-empty")
+        _ensure_json_serializable(self.metadata_json, "run.metadata_json")
+
+    def to_dict(self) -> dict[str, Any]:
+        self.validate()
+        payload = asdict(self)
+        payload["run_id"] = str(self.run_id)
+        payload["created_at"] = self.created_at.isoformat()
+        return payload
+
+
+@dataclass(slots=True)
+class Span:
+    span_id: UUID
+    run_id: UUID
+    parent_span_id: UUID | None
+    span_type: SpanType
+    name: str
+    start_time: datetime
+    end_time: datetime
+    duration_ms: int
+    input_json: Any
+    output_json: Any
+    error: str | None
+    metadata_json: dict[str, Any] = field(default_factory=dict)
+
+    def validate(self) -> None:
+        if not self.name:
+            raise ValueError("span.name must be non-empty")
+        if self.duration_ms < 0:
+            raise ValueError("span.duration_ms must be >= 0")
+        _ensure_json_serializable(self.input_json, "span.input_json")
+        _ensure_json_serializable(self.output_json, "span.output_json")
+        _ensure_json_serializable(self.metadata_json, "span.metadata_json")
+        if self.start_time > self.end_time:
+            raise ValueError("span.start_time must be <= span.end_time")
+
+    def to_dict(self) -> dict[str, Any]:
+        self.validate()
+        payload = asdict(self)
+        payload["span_id"] = str(self.span_id)
+        payload["run_id"] = str(self.run_id)
+        payload["parent_span_id"] = str(self.parent_span_id) if self.parent_span_id else None
+        payload["start_time"] = self.start_time.isoformat()
+        payload["end_time"] = self.end_time.isoformat()
+        return payload
+
+
+def build_ingest_payload(runs: list[Run], spans: list[Span]) -> dict[str, Any]:
+    run_ids = {run.run_id for run in runs}
+    span_ids_by_run: dict[UUID, set[UUID]] = {}
+
+    for span in spans:
+        span.validate()
+        span_ids_by_run.setdefault(span.run_id, set()).add(span.span_id)
+
+    for span in spans:
+        if span.run_id not in run_ids:
+            raise ValueError(f"span {span.span_id} references unknown run_id {span.run_id}")
+        if span.parent_span_id and span.parent_span_id not in span_ids_by_run.get(span.run_id, set()):
+            raise ValueError(
+                f"span {span.span_id} has parent_span_id {span.parent_span_id} "
+                f"not found in run {span.run_id}"
+            )
+
+    payload = {
+        "runs": [run.to_dict() for run in runs],
+        "spans": [span.to_dict() for span in spans],
+    }
+    _ensure_json_serializable(payload, "ingest payload")
+    return payload

agentshadow-0.1.0/agenttrace/crewai.py

@@ -0,0 +1,80 @@
+"""CrewAI integration for AgentTrace.
+
+Usage::
+
+    from agenttrace.crewai import AgentTraceCrewAIHandler
+
+    handler = AgentTraceCrewAIHandler()
+    crew = Crew(
+        ...,
+        step_callback=handler.step_callback,
+        task_callback=handler.task_callback,
+    )
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+from uuid import uuid4
+
+from agenttrace.trace import trace
+
+
+def _now_utc() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _safe_str(value: Any) -> str:
+    try:
+        return str(value)
+    except Exception:  # noqa: BLE001
+        return "<unserializable>"
+
+
+class AgentTraceCrewAIHandler:
+    """Callback handler for CrewAI step_callback / task_callback hooks."""
+
+    def step_callback(self, step_output: Any) -> None:
+        """Called by CrewAI after each agent step."""
+        ctx = trace.current()
+        if ctx is None:
+            return
+
+        now = _now_utc()
+        text = _safe_str(step_output)
+
+        ctx.add_span(
+            span_type="agent",
+            name="crewai_step",
+            start_time=now,
+            end_time=now,
+            input_json={},
+            output_json={"step_output": text},
+            metadata_json={"source": "crewai"},
+        )
+
+    def task_callback(self, task_output: Any) -> None:
+        """Called by CrewAI after each task completes."""
+        ctx = trace.current()
+        if ctx is None:
+            return
+
+        now = _now_utc()
+        output_data: dict[str, Any] = {"task_output": _safe_str(task_output)}
+
+        # CrewAI TaskOutput objects may have structured attributes
+        for attr in ("description", "summary", "raw"):
+            val = getattr(task_output, attr, None)
+            if val is not None:
+                output_data[attr] = _safe_str(val)
+
+        ctx.add_span(
+            span_type="chain",
+            name="crewai_task",
+            start_time=now,
+            end_time=now,
+            input_json={},
+            output_json=output_data,
+            metadata_json={"source": "crewai"},
+        )

agentshadow-0.1.0/agenttrace/langchain.py

@@ -0,0 +1,287 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+import json
+from typing import Any
+from uuid import UUID, uuid4
+
+from agenttrace.trace import trace
+
+
+def _now_utc() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _to_run_key(value: UUID | str | None) -> str | None:
+    if value is None:
+        return None
+    return str(value)
+
+
+def _pick_name(serialized: dict[str, Any] | None, fallback: str) -> str:
+    if not serialized:
+        return fallback
+    value = serialized.get("name")
+    if isinstance(value, str) and value:
+        return value
+    return fallback
+
+
+def _safe_json(value: Any, seen: set[int] | None = None) -> Any:
+    if seen is None:
+        seen = set()
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+
+    value_id = id(value)
+    if value_id in seen:
+        return "<recursive>"
+
+    if isinstance(value, dict):
+        seen.add(value_id)
+        return {str(k): _safe_json(v, seen) for k, v in value.items()}
+    if isinstance(value, (list, tuple, set)):
+        seen.add(value_id)
+        return [_safe_json(v, seen) for v in value]
+    if isinstance(value, bytes):
+        return value.decode("utf-8", errors="replace")
+
+    for attr in ("model_dump", "dict"):
+        fn = getattr(value, attr, None)
+        if callable(fn):
+            try:
+                return _safe_json(fn(), seen)
+            except Exception:  # noqa: BLE001
+                pass
+
+    try:
+        json.dumps(value)
+        return value
+    except TypeError:
+        return repr(value)
+
+
+@dataclass(slots=True)
+class _PendingSpan:
+    span_id: str
+    span_type: str
+    name: str
+    start_time: datetime
+    input_json: Any
+    metadata_json: dict[str, Any]
+    parent_run_key: str | None
+
+
+class AgentTraceCallbackHandler:
+    def __init__(self) -> None:
+        # LangChain callback manager expects these handler attributes.
+        self.raise_error = False
+        self.run_inline = True
+        self.ignore_llm = False
+        self.ignore_chat_model = False
+        self.ignore_chain = False
+        self.ignore_agent = False
+        self.ignore_retriever = False
+        self.ignore_tool = False
+        self.ignore_custom_event = False
+        self.ignore_retry = False
+
+        self._pending: dict[str, _PendingSpan] = {}
+        self._span_id_by_run: dict[str, str] = {}
+
+    def _start(
+        self,
+        *,
+        span_type: str,
+        name: str,
+        input_json: Any,
+        run_id: UUID,
+        parent_run_id: UUID | None,
+        metadata_json: dict[str, Any] | None = None,
+    ) -> None:
+        run_key = _to_run_key(run_id)
+        span_id = str(uuid4())
+        self._pending[run_key] = _PendingSpan(
+            span_id=span_id,
+            span_type=span_type,
+            name=name,
+            start_time=_now_utc(),
+            input_json=_safe_json(input_json),
+            metadata_json=_safe_json(metadata_json or {}),
+            parent_run_key=_to_run_key(parent_run_id),
+        )
+        self._span_id_by_run[run_key] = span_id
+
+    def _end(self, *, run_id: UUID, output_json: Any, error: str | None = None) -> None:
+        ctx = trace.current()
+        if ctx is None:
+            return
+        run_key = _to_run_key(run_id)
+        pending = self._pending.pop(run_key, None)
+        end_time = _now_utc()
+        if pending is None:
+            pending = _PendingSpan(
+                span_id=str(uuid4()),
+                span_type="chain",
+                name="unknown",
+                start_time=end_time,
+                input_json={},
+                metadata_json={},
+                parent_run_key=None,
+            )
+
+        parent_span_id = None
+        if pending.parent_run_key:
+            parent_span_id = self._span_id_by_run.get(pending.parent_run_key)
+
+        span = ctx.add_span(
+            span_id=pending.span_id,
+            span_type=pending.span_type,  # type: ignore[arg-type]
+            name=pending.name,
+            start_time=pending.start_time,
+            end_time=end_time,
+            input_json=pending.input_json,
+            output_json=_safe_json(output_json),
+            error=error,
+            metadata_json=pending.metadata_json,
+            parent_span_id=parent_span_id,
+        )
+        self._span_id_by_run[run_key] = str(span.span_id)
+
+    def on_llm_start(
+        self,
+        serialized: dict[str, Any],
+        prompts: list[str],
+        *,
+        run_id: UUID,
+        parent_run_id: UUID | None = None,
+        **_: Any,
+    ) -> None:
+        self._start(
+            span_type="llm",
+            name=_pick_name(serialized, "llm"),
+            input_json={"prompts": prompts},
+            run_id=run_id,
+            parent_run_id=parent_run_id,
+            metadata_json={"serialized": serialized},
+        )
+
+    def on_llm_end(self, response: Any, *, run_id: UUID, **_: Any) -> None:
+        self._end(run_id=run_id, output_json={"response": response})
+
+    def on_chat_model_start(
+        self,
+        serialized: dict[str, Any],
+        messages: list[list[Any]],
+        *,
+        run_id: UUID,
+        parent_run_id: UUID | None = None,
+        **_: Any,
+    ) -> None:
+        self._start(
+            span_type="llm",
+            name=_pick_name(serialized, "chat_model"),
+            input_json={"messages": messages},
+            run_id=run_id,
+            parent_run_id=parent_run_id,
+            metadata_json={"serialized": serialized},
+        )
+
+    def on_chat_model_end(self, response: Any, *, run_id: UUID, **_: Any) -> None:
+        self._end(run_id=run_id, output_json={"response": response})
+
+    def on_llm_new_token(self, token: str, *, run_id: UUID, **_: Any) -> None:
+        # Token-level streaming is not persisted in v0.
+        return
+
+    def on_llm_error(self, error: BaseException, *, run_id: UUID, **_: Any) -> None:
+        self._end(
+            run_id=run_id,
+            output_json={},
+            error=f"{type(error).__name__}: {error}",
+        )
+
+    def on_tool_start(
+        self,
+        serialized: dict[str, Any],
+        input_str: str,
+        *,
+        run_id: UUID,
+        parent_run_id: UUID | None = None,
+        **_: Any,
+    ) -> None:
+        self._start(
+            span_type="tool",
+            name=_pick_name(serialized, "tool"),
+            input_json={"input": input_str},
+            run_id=run_id,
+            parent_run_id=parent_run_id,
+            metadata_json={"serialized": serialized},
+        )
+
+    def on_tool_end(self, output: Any, *, run_id: UUID, **_: Any) -> None:
+        self._end(run_id=run_id, output_json={"output": output})
+
+    def on_tool_error(self, error: BaseException, *, run_id: UUID, **_: Any) -> None:
+        self._end(
+            run_id=run_id,
+            output_json={},
+            error=f"{type(error).__name__}: {error}",
+        )
+
+    def on_retriever_start(
+        self,
+        serialized: dict[str, Any],
+        query: str,
+        *,
+        run_id: UUID,
+        parent_run_id: UUID | None = None,
+        **_: Any,
+    ) -> None:
+        self._start(
+            span_type="retrieval",
+            name=_pick_name(serialized, "retriever"),
+            input_json={"query": query},
+            run_id=run_id,
+            parent_run_id=parent_run_id,
+            metadata_json={"serialized": serialized},
+        )
+
+    def on_retriever_end(self, documents: Any, *, run_id: UUID, **_: Any) -> None:
+        self._end(run_id=run_id, output_json={"documents": documents})
+
+    def on_retriever_error(self, error: BaseException, *, run_id: UUID, **_: Any) -> None:
+        self._end(
+            run_id=run_id,
+            output_json={},
+            error=f"{type(error).__name__}: {error}",
+        )
+
+    def on_chain_start(
+        self,
+        serialized: dict[str, Any],
+        inputs: Any,
+        *,
+        run_id: UUID,
+        parent_run_id: UUID | None = None,
+        **_: Any,
+    ) -> None:
+        self._start(
+            span_type="chain",
+            name=_pick_name(serialized, "chain"),
+            input_json=inputs,
+            run_id=run_id,
+            parent_run_id=parent_run_id,
+            metadata_json={"serialized": serialized},
+        )
+
+    def on_chain_end(self, outputs: dict[str, Any], *, run_id: UUID, **_: Any) -> None:
+        self._end(run_id=run_id, output_json=outputs)
+
+    def on_chain_error(self, error: BaseException, *, run_id: UUID, **_: Any) -> None:
+        self._end(
+            run_id=run_id,
+            output_json={},
+            error=f"{type(error).__name__}: {error}",
+        )