agentwatchx 0.1.0__py3-none-any.whl

agentwatchx/__init__.py

@@ -0,0 +1,106 @@
+"""AgentWatchX — Observability SDK for AI Agent Execution."""
+
+from agentwatchx.client import AgentWatchXClient
+from agentwatchx.decorators import trace
+from agentwatchx.schemas import TraceData, ToolCallData
+
+# Module-level client instance
+_client: AgentWatchXClient | None = None
+
+
+def init(api_key: str, endpoint: str = "https://api.agentwatchx.com", auto_instrument: bool = True, **kwargs):
+    """Initialize the AgentWatchX SDK.
+
+    After calling init(), tracing begins automatically for supported libraries
+    (OpenAI, Anthropic, LangChain, LlamaIndex) if they are installed.
+
+    Set auto_instrument=False to disable auto-patching and use manual
+    capture/wrap/trace only.
+    """
+    global _client
+    _client = AgentWatchXClient(api_key=api_key, endpoint=endpoint, **kwargs)
+
+    if auto_instrument:
+        from agentwatchx.integrations import auto_instrument as _auto
+        _auto(_client)
+
+    return _client
+
+
+def get_client() -> AgentWatchXClient:
+    if _client is None:
+        raise RuntimeError("AgentWatchX SDK not initialized. Call agentwatchx.init() first.")
+    return _client
+
+
+def wrap(llm_client):
+    """Wrap an LLM client instance for explicit trace capture.
+
+    This is optional when auto-instrumentation is active. Use it when you
+    want to trace a specific client instance without global patching.
+
+    Supported: OpenAI, Anthropic client instances.
+    """
+    if _client is None:
+        raise RuntimeError("AgentWatchX SDK not initialized. Call agentwatchx.init() first.")
+
+    # Detect client type and apply instance-level wrapping
+    client_type = type(llm_client).__module__
+
+    if "openai" in client_type:
+        from agentwatchx.integrations.openai_patch import patch
+        patch(_client)
+    elif "anthropic" in client_type:
+        from agentwatchx.integrations.anthropic_patch import patch
+        patch(_client)
+
+    return llm_client
+
+
+def log(data: dict):
+    """Manually log a trace from a dict. Convenience for custom events."""
+    if _client is None:
+        raise RuntimeError("AgentWatchX SDK not initialized. Call agentwatchx.init() first.")
+
+    tool_calls = []
+    for tc in data.get("tool_calls", []):
+        tool_calls.append(ToolCallData(**tc) if isinstance(tc, dict) else tc)
+
+    trace_data = TraceData(
+        service=data.get("service", data.get("type", "custom")),
+        input_text=str(data.get("input", data.get("input_text", ""))),
+        output_text=str(data.get("output", data.get("output_text", ""))) if data.get("output") or data.get("output_text") else None,
+        llm_model=data.get("llm_model", data.get("model")),
+        duration_ms=data.get("duration_ms"),
+        tool_calls=tool_calls,
+        metadata={k: v for k, v in data.items() if k not in {
+            "service", "type", "input", "input_text", "output", "output_text",
+            "llm_model", "model", "duration_ms", "tool_calls",
+        }},
+    )
+    _client.capture(trace_data)
+
+
+def shutdown():
+    """Flush pending traces and close the client."""
+    if _client:
+        from agentwatchx.integrations import unpatch_all
+        unpatch_all()
+        _client.flush()
+        _client.close()
+
+
+def status() -> dict:
+    """Return SDK connection status."""
+    if _client is None:
+        return {"initialized": False}
+    info = _client.status()
+    from agentwatchx.integrations import get_instrumented
+    info["instrumented"] = get_instrumented()
+    return info
+
+
+__all__ = [
+    "init", "trace", "wrap", "log", "shutdown", "status",
+    "get_client", "TraceData", "ToolCallData",
+]

agentwatchx/client.py

@@ -0,0 +1,90 @@
+import threading
+import time
+import atexit
+
+import httpx
+
+from agentwatchx.schemas import TraceData
+
+
+class AgentWatchXClient:
+    """Core SDK client. Buffers traces and flushes in batches."""
+
+    def __init__(
+        self,
+        api_key: str,
+        endpoint: str = "https://api.agentwatchx.com",
+        flush_interval: float = 5.0,
+        batch_size: int = 100,
+        service: str = "default",
+    ):
+        self.api_key = api_key
+        self.endpoint = endpoint.rstrip("/")
+        self.flush_interval = flush_interval
+        self.batch_size = batch_size
+        self.default_service = service
+
+        self._buffer: list[dict] = []
+        self._lock = threading.Lock()
+        self._http = httpx.Client(
+            base_url=self.endpoint,
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=10.0,
+        )
+
+        # Background flush thread
+        self._running = True
+        self._flush_thread = threading.Thread(target=self._flush_loop, daemon=True)
+        self._flush_thread.start()
+        atexit.register(self.shutdown)
+
+    def capture(self, trace: TraceData):
+        """Add a trace to the buffer."""
+        data = trace.model_dump()
+        if data["service"] == "default":
+            data["service"] = self.default_service
+        with self._lock:
+            self._buffer.append(data)
+            if len(self._buffer) >= self.batch_size:
+                self._send_batch()
+
+    def flush(self):
+        """Force flush all buffered traces."""
+        with self._lock:
+            self._send_batch()
+
+    def close(self):
+        """Stop the flush thread and close HTTP client."""
+        self._running = False
+        self.flush()
+        self._http.close()
+
+    def shutdown(self):
+        """Alias for close — used by atexit."""
+        self.close()
+
+    def status(self) -> dict:
+        with self._lock:
+            buffered = len(self._buffer)
+        return {
+            "initialized": True,
+            "endpoint": self.endpoint,
+            "buffered_traces": buffered,
+        }
+
+    def _flush_loop(self):
+        while self._running:
+            time.sleep(self.flush_interval)
+            self.flush()
+
+    def _send_batch(self):
+        """Send buffered traces. Must be called with self._lock held."""
+        if not self._buffer:
+            return
+        batch = self._buffer[:self.batch_size]
+        self._buffer = self._buffer[self.batch_size:]
+        try:
+            self._http.post("/v1/traces/batch", json={"traces": batch})
+        except Exception:
+            # Re-add to buffer on failure (best effort)
+            self._buffer = batch + self._buffer

agentwatchx/decorators.py

@@ -0,0 +1,63 @@
+import functools
+import time
+from typing import Callable
+
+from agentwatchx.schemas import TraceData
+
+
+def trace(
+    func: Callable | None = None,
+    *,
+    service: str = "default",
+    llm_model: str | None = None,
+):
+    """
+    Decorator to trace a function execution.
+
+    Usage:
+        @agentwatchx.trace
+        def my_agent(input_text):
+            ...
+
+        @agentwatchx.trace(service="order-agent", llm_model="gpt-4")
+        def my_agent(input_text):
+            ...
+    """
+    def decorator(fn: Callable) -> Callable:
+        @functools.wraps(fn)
+        def wrapper(*args, **kwargs):
+            import agentwatchx
+
+            input_text = str(args[0]) if args else str(kwargs) if kwargs else None
+            start = time.perf_counter()
+            error = None
+
+            try:
+                result = fn(*args, **kwargs)
+                return result
+            except Exception as e:
+                error = e
+                raise
+            finally:
+                duration_ms = (time.perf_counter() - start) * 1000
+                output_text = None if error else str(result) if 'result' in dir() else None
+
+                trace_data = TraceData(
+                    service=service,
+                    input_text=input_text,
+                    output_text=output_text,
+                    llm_model=llm_model,
+                    duration_ms=round(duration_ms, 2),
+                )
+
+                try:
+                    client = agentwatchx.get_client()
+                    client.capture(trace_data)
+                except RuntimeError:
+                    pass  # SDK not initialized, silently skip
+
+        return wrapper
+
+    if func is not None:
+        return decorator(func)
+    return decorator

agentwatchx/integrations/__init__.py

@@ -0,0 +1,59 @@
+"""
+Auto-instrumentation registry.
+
+Detects installed LLM libraries and patches them to capture traces
+automatically after agentwatchx.init() is called.
+"""
+
+import importlib
+import logging
+
+logger = logging.getLogger("agentwatchx.integrations")
+
+_PATCHES = {
+    "openai": "agentwatchx.integrations.openai_patch",
+    "anthropic": "agentwatchx.integrations.anthropic_patch",
+    "langchain_core": "agentwatchx.integrations.langchain_cb",
+    "llama_index": "agentwatchx.integrations.llamaindex_cb",
+}
+
+_applied: list[str] = []
+
+
+def auto_instrument(client):
+    """Detect installed libraries and apply patches. Called by init()."""
+    for lib_name, patch_module in _PATCHES.items():
+        if lib_name in _applied:
+            continue  # already patched, skip
+
+        try:
+            importlib.import_module(lib_name)
+        except ImportError:
+            continue  # library not installed, skip
+
+        try:
+            mod = importlib.import_module(patch_module)
+            mod.patch(client)
+            _applied.append(lib_name)
+            logger.info("Instrumented %s", lib_name)
+        except Exception as exc:
+            logger.warning("Failed to instrument %s: %s", lib_name, exc)
+
+
+def get_instrumented() -> list[str]:
+    """Return list of libraries that were successfully instrumented."""
+    return list(_applied)
+
+
+def unpatch_all():
+    """Remove all patches (for testing / shutdown)."""
+    for lib_name, patch_module in _PATCHES.items():
+        if lib_name not in _applied:
+            continue
+        try:
+            mod = importlib.import_module(patch_module)
+            if hasattr(mod, "unpatch"):
+                mod.unpatch()
+        except Exception:
+            pass
+    _applied.clear()

agentwatchx/integrations/anthropic_patch.py

@@ -0,0 +1,247 @@
+"""
+Auto-instrumentation for the Anthropic Python SDK.
+
+Patches:
+  - messages.create (sync + async)
+  - Handles both regular and streaming responses
+
+After agentwatchx.init(), every Anthropic call is traced automatically.
+"""
+
+import time
+import functools
+import logging
+
+logger = logging.getLogger("agentwatchx.integrations.anthropic")
+
+_original_create = None
+_original_async_create = None
+_client_ref = None
+_patched = False
+
+
+def patch(awx_client):
+    """Monkey-patch anthropic messages.create."""
+    global _original_create, _original_async_create, _client_ref, _patched
+    if _patched:
+        return
+    _client_ref = awx_client
+
+    try:
+        from anthropic.resources.messages import Messages
+    except ImportError:
+        logger.debug("anthropic messages module not found, skipping")
+        return
+
+    _original_create = Messages.create
+
+    @functools.wraps(_original_create)
+    def patched_create(self, *args, **kwargs):
+        stream = kwargs.get("stream", False)
+        start = time.perf_counter()
+
+        if stream:
+            result = _original_create(self, *args, **kwargs)
+            return _wrap_stream(result, kwargs, start)
+
+        error = None
+        result = None
+        try:
+            result = _original_create(self, *args, **kwargs)
+            return result
+        except Exception as exc:
+            error = exc
+            raise
+        finally:
+            duration_ms = (time.perf_counter() - start) * 1000
+            _capture_trace(kwargs, result, error, duration_ms)
+
+    Messages.create = patched_create
+
+    # Patch async
+    try:
+        from anthropic.resources.messages import AsyncMessages
+        _original_async_create = AsyncMessages.create
+
+        @functools.wraps(_original_async_create)
+        async def patched_async_create(self, *args, **kwargs):
+            stream = kwargs.get("stream", False)
+            start = time.perf_counter()
+
+            if stream:
+                result = await _original_async_create(self, *args, **kwargs)
+                return _wrap_async_stream(result, kwargs, start)
+
+            error = None
+            result = None
+            try:
+                result = await _original_async_create(self, *args, **kwargs)
+                return result
+            except Exception as exc:
+                error = exc
+                raise
+            finally:
+                duration_ms = (time.perf_counter() - start) * 1000
+                _capture_trace(kwargs, result, error, duration_ms)
+
+        AsyncMessages.create = patched_async_create
+    except ImportError:
+        pass
+
+    _patched = True
+    logger.info("Anthropic auto-instrumentation applied")
+
+
+def unpatch():
+    """Restore original methods."""
+    global _original_create, _original_async_create, _patched
+    if _original_create:
+        from anthropic.resources.messages import Messages
+        Messages.create = _original_create
+        _original_create = None
+    if _original_async_create:
+        from anthropic.resources.messages import AsyncMessages
+        AsyncMessages.create = _original_async_create
+        _original_async_create = None
+    _patched = False
+
+
+def _wrap_stream(stream, kwargs, start):
+    """Wrap a sync Anthropic stream to capture events."""
+    content_parts = []
+    input_tokens = 0
+    output_tokens = 0
+    try:
+        for event in stream:
+            # Collect text deltas
+            if hasattr(event, "type"):
+                if event.type == "content_block_delta" and hasattr(event, "delta"):
+                    if hasattr(event.delta, "text"):
+                        content_parts.append(event.delta.text)
+                elif event.type == "message_delta" and hasattr(event, "usage"):
+                    output_tokens = getattr(event.usage, "output_tokens", 0)
+                elif event.type == "message_start" and hasattr(event, "message"):
+                    usage = getattr(event.message, "usage", None)
+                    if usage:
+                        input_tokens = getattr(usage, "input_tokens", 0)
+            yield event
+    finally:
+        duration_ms = (time.perf_counter() - start) * 1000
+        _capture_stream_trace(kwargs, content_parts, input_tokens, output_tokens, duration_ms)
+
+
+async def _wrap_async_stream(stream, kwargs, start):
+    """Wrap an async Anthropic stream."""
+    content_parts = []
+    input_tokens = 0
+    output_tokens = 0
+    try:
+        async for event in stream:
+            if hasattr(event, "type"):
+                if event.type == "content_block_delta" and hasattr(event, "delta"):
+                    if hasattr(event.delta, "text"):
+                        content_parts.append(event.delta.text)
+                elif event.type == "message_delta" and hasattr(event, "usage"):
+                    output_tokens = getattr(event.usage, "output_tokens", 0)
+                elif event.type == "message_start" and hasattr(event, "message"):
+                    usage = getattr(event.message, "usage", None)
+                    if usage:
+                        input_tokens = getattr(usage, "input_tokens", 0)
+            yield event
+    finally:
+        duration_ms = (time.perf_counter() - start) * 1000
+        _capture_stream_trace(kwargs, content_parts, input_tokens, output_tokens, duration_ms)
+
+
+def _capture_stream_trace(kwargs, content_parts, input_tokens, output_tokens, duration_ms):
+    """Build trace from collected stream data."""
+    if _client_ref is None:
+        return
+
+    from agentwatchx.schemas import TraceData
+
+    model = kwargs.get("model", "unknown")
+    messages = kwargs.get("messages", [])
+    input_text = _extract_input(messages)
+    output_text = "".join(content_parts)
+
+    metadata = {"provider": "anthropic", "streamed": True}
+    if input_tokens or output_tokens:
+        metadata["input_tokens"] = input_tokens
+        metadata["output_tokens"] = output_tokens
+
+    try:
+        _client_ref.capture(TraceData(
+            service="anthropic",
+            input_text=input_text,
+            output_text=output_text or None,
+            llm_model=model,
+            duration_ms=round(duration_ms, 2),
+            metadata=metadata,
+        ))
+    except Exception as exc:
+        logger.debug("Failed to capture Anthropic stream trace: %s", exc)
+
+
+def _extract_input(messages):
+    """Pull input text from the last message."""
+    if not messages:
+        return ""
+    last = messages[-1]
+    if isinstance(last, dict):
+        content = last.get("content", "")
+        return content if isinstance(content, str) else str(content)
+    return str(last)
+
+
+def _capture_trace(kwargs, result, error, duration_ms):
+    """Extract trace data from a non-streaming Anthropic call."""
+    if _client_ref is None:
+        return
+
+    from agentwatchx.schemas import TraceData
+
+    model = kwargs.get("model", "unknown")
+    messages = kwargs.get("messages", [])
+    input_text = _extract_input(messages)
+
+    output_text = None
+    tool_calls = []
+    metadata = {"provider": "anthropic"}
+
+    if error:
+        metadata["error"] = str(error)
+    elif result:
+        try:
+            blocks = result.content
+            text_parts = []
+            for b in blocks:
+                if hasattr(b, "text"):
+                    text_parts.append(b.text)
+                elif hasattr(b, "type") and b.type == "tool_use":
+                    from agentwatchx.schemas import ToolCallData
+                    tool_calls.append(ToolCallData(
+                        name=b.name,
+                        input=b.input if hasattr(b, "input") else None,
+                        status="success",
+                    ))
+            output_text = " ".join(text_parts)
+
+            if hasattr(result, "usage") and result.usage:
+                metadata["input_tokens"] = result.usage.input_tokens
+                metadata["output_tokens"] = result.usage.output_tokens
+        except (AttributeError, TypeError):
+            output_text = str(result)
+
+    try:
+        _client_ref.capture(TraceData(
+            service="anthropic",
+            input_text=input_text,
+            output_text=output_text,
+            llm_model=model,
+            duration_ms=round(duration_ms, 2),
+            tool_calls=tool_calls,
+            metadata=metadata,
+        ))
+    except Exception as exc:
+        logger.debug("Failed to capture Anthropic trace: %s", exc)

agentwatchx/integrations/langchain_cb.py

@@ -0,0 +1,191 @@
+"""
+Auto-instrumentation for LangChain via callback handler.
+
+Registers an AgentWatchX callback handler globally so all LangChain
+LLM/chain/chat model invocations are traced automatically.
+
+Works with langchain-core >= 0.1.0 (the modern package structure).
+"""
+
+import time
+import logging
+from typing import Any
+from uuid import UUID
+
+logger = logging.getLogger("agentwatchx.integrations.langchain")
+
+_client_ref = None
+_handler_instance = None
+_patched = False
+
+
+def patch(awx_client):
+    """Create and globally register a LangChain callback handler."""
+    global _client_ref, _handler_instance, _patched
+    if _patched:
+        return
+    _client_ref = awx_client
+
+    try:
+        from langchain_core.callbacks import BaseCallbackHandler
+    except ImportError:
+        logger.debug("langchain_core not available, skipping")
+        return
+
+    class AWXCallbackHandler(BaseCallbackHandler):
+        """Captures LLM start/end events and sends them as traces."""
+
+        def __init__(self):
+            self._runs: dict[UUID, dict] = {}
+
+        @property
+        def always_verbose(self) -> bool:
+            return True
+
+        def on_llm_start(
+            self,
+            serialized: dict[str, Any],
+            prompts: list[str],
+            *,
+            run_id: UUID,
+            **kwargs: Any,
+        ) -> None:
+            model = (
+                kwargs.get("invocation_params", {}).get("model_name")
+                or kwargs.get("invocation_params", {}).get("model")
+                or serialized.get("kwargs", {}).get("model_name")
+                or serialized.get("kwargs", {}).get("model")
+                or "unknown"
+            )
+            self._runs[run_id] = {
+                "start": time.perf_counter(),
+                "input_text": prompts[0] if prompts else "",
+                "model": model,
+                "metadata": {"provider": "langchain"},
+            }
+
+        def on_chat_model_start(
+            self,
+            serialized: dict[str, Any],
+            messages: list[list],
+            *,
+            run_id: UUID,
+            **kwargs: Any,
+        ) -> None:
+            input_text = ""
+            if messages and messages[0]:
+                last_msg = messages[0][-1]
+                if hasattr(last_msg, "content"):
+                    input_text = str(last_msg.content)
+                else:
+                    input_text = str(last_msg)
+
+            model = (
+                kwargs.get("invocation_params", {}).get("model_name")
+                or kwargs.get("invocation_params", {}).get("model")
+                or serialized.get("kwargs", {}).get("model_name")
+                or serialized.get("kwargs", {}).get("model")
+                or "unknown"
+            )
+            self._runs[run_id] = {
+                "start": time.perf_counter(),
+                "input_text": input_text,
+                "model": model,
+                "metadata": {"provider": "langchain"},
+            }
+
+        def on_llm_end(self, response, *, run_id: UUID, **kwargs: Any) -> None:
+            run = self._runs.pop(run_id, None)
+            if not run or _client_ref is None:
+                return
+            duration_ms = (time.perf_counter() - run["start"]) * 1000
+
+            output_text = ""
+            try:
+                gen = response.generations[0][0]
+                output_text = gen.text if hasattr(gen, "text") else str(gen)
+                # Capture token usage if available
+                if hasattr(response, "llm_output") and response.llm_output:
+                    usage = response.llm_output.get("token_usage", {})
+                    if usage:
+                        run["metadata"]["tokens"] = usage
+            except (IndexError, AttributeError):
+                output_text = str(response)
+
+            from agentwatchx.schemas import TraceData
+            try:
+                _client_ref.capture(TraceData(
+                    service="langchain",
+                    input_text=run["input_text"],
+                    output_text=output_text,
+                    llm_model=run["model"],
+                    duration_ms=round(duration_ms, 2),
+                    metadata=run["metadata"],
+                ))
+            except Exception as exc:
+                logger.debug("Failed to capture LangChain trace: %s", exc)
+
+        def on_llm_error(self, error, *, run_id: UUID, **kwargs: Any) -> None:
+            run = self._runs.pop(run_id, None)
+            if not run or _client_ref is None:
+                return
+            duration_ms = (time.perf_counter() - run["start"]) * 1000
+            run["metadata"]["error"] = str(error)
+
+            from agentwatchx.schemas import TraceData
+            try:
+                _client_ref.capture(TraceData(
+                    service="langchain",
+                    input_text=run["input_text"],
+                    output_text=None,
+                    llm_model=run["model"],
+                    duration_ms=round(duration_ms, 2),
+                    metadata=run["metadata"],
+                ))
+            except Exception as exc:
+                logger.debug("Failed to capture LangChain error trace: %s", exc)
+
+    _handler_instance = AWXCallbackHandler()
+
+    # Register globally by patching the callback manager's configure function.
+    # This ensures our handler is included in every LLM/chain invocation
+    # without requiring users to pass callbacks= manually.
+    try:
+        from langchain_core.callbacks.manager import CallbackManager
+
+        _original_configure = CallbackManager.configure
+
+        @classmethod
+        def patched_configure(cls, *args, **kwargs):
+            manager = _original_configure.__func__(cls, *args, **kwargs)
+            if manager is not None and _handler_instance is not None:
+                # Avoid duplicates
+                handler_types = {type(h) for h in manager.handlers}
+                if type(_handler_instance) not in handler_types:
+                    manager.add_handler(_handler_instance)
+            return manager
+
+        CallbackManager.configure = patched_configure
+        logger.info("LangChain global callback handler registered via CallbackManager.configure")
+    except Exception as exc:
+        logger.warning("Could not register LangChain handler globally: %s. "
+                       "Use get_callback_handler() manually.", exc)
+
+    _patched = True
+
+
+def get_callback_handler():
+    """Return the AWX callback handler for manual use.
+
+    Usage with LangChain:
+        from agentwatchx.integrations.langchain_cb import get_callback_handler
+        llm.invoke("prompt", config={"callbacks": [get_callback_handler()]})
+    """
+    return _handler_instance
+
+
+def unpatch():
+    """Remove the global callback handler."""
+    global _handler_instance, _patched
+    _handler_instance = None
+    _patched = False

agentwatchx/integrations/llamaindex_cb.py

@@ -0,0 +1,175 @@
+"""
+Auto-instrumentation for LlamaIndex via its callback system.
+
+Registers an AgentWatchX handler that captures LLM call events automatically.
+Supports both llama-index >= 0.10 (llama_index.core) and legacy paths.
+"""
+
+import time
+import logging
+from typing import Any
+
+logger = logging.getLogger("agentwatchx.integrations.llamaindex")
+
+_client_ref = None
+_handler_instance = None
+_patched = False
+
+# Resolved at patch time
+_CBEventType = None
+_CallbackManager = None
+_BaseCallbackHandler = None
+_Settings = None
+
+
+def patch(awx_client):
+    """Register a LlamaIndex callback handler globally."""
+    global _client_ref, _handler_instance, _patched
+    global _CBEventType, _CallbackManager, _BaseCallbackHandler, _Settings
+
+    if _patched:
+        return
+    _client_ref = awx_client
+
+    # Try modern import path first (llama-index >= 0.10)
+    try:
+        from llama_index.core.callbacks import CallbackManager, CBEventType
+        from llama_index.core.callbacks.base_handler import BaseCallbackHandler
+        from llama_index.core import Settings
+    except ImportError:
+        # Legacy import path
+        try:
+            from llama_index.callbacks import CallbackManager, CBEventType
+            from llama_index.callbacks.base_handler import BaseCallbackHandler
+            from llama_index import Settings
+        except ImportError:
+            logger.debug("llama_index callback modules not found, skipping")
+            return
+
+    _CBEventType = CBEventType
+    _CallbackManager = CallbackManager
+    _BaseCallbackHandler = BaseCallbackHandler
+    _Settings = Settings
+
+    class AWXLlamaHandler(BaseCallbackHandler):
+        """Captures LlamaIndex LLM events and sends them as traces."""
+
+        def __init__(self):
+            super().__init__(
+                event_starts_to_trace=[CBEventType.LLM],
+                event_ends_to_trace=[CBEventType.LLM],
+            )
+            self._events: dict[str, dict] = {}
+
+        def on_event_start(
+            self,
+            event_type: CBEventType,
+            payload: dict | None = None,
+            event_id: str = "",
+            **kwargs: Any,
+        ) -> str:
+            if event_type == CBEventType.LLM:
+                input_text = ""
+                model = "unknown"
+                if payload:
+                    # Try to extract from messages
+                    messages = payload.get("messages", [])
+                    if messages:
+                        last = messages[-1]
+                        input_text = str(last.content) if hasattr(last, "content") else str(last)
+                    elif "prompt" in payload:
+                        input_text = str(payload["prompt"])
+
+                    model = (
+                        payload.get("model_name")
+                        or payload.get("model")
+                        or "unknown"
+                    )
+                self._events[event_id] = {
+                    "start": time.perf_counter(),
+                    "input_text": input_text,
+                    "model": model,
+                    "metadata": {"provider": "llamaindex"},
+                }
+            return event_id
+
+        def on_event_end(
+            self,
+            event_type: CBEventType,
+            payload: dict | None = None,
+            event_id: str = "",
+            **kwargs: Any,
+        ) -> None:
+            if event_type != CBEventType.LLM:
+                return
+            ev = self._events.pop(event_id, None)
+            if not ev or _client_ref is None:
+                return
+
+            duration_ms = (time.perf_counter() - ev["start"]) * 1000
+            output_text = ""
+            if payload:
+                response = payload.get("response", payload.get("completion", ""))
+                output_text = str(response)
+                # Token usage
+                tokens = payload.get("token_usage") or payload.get("usage")
+                if tokens:
+                    ev["metadata"]["tokens"] = (
+                        tokens if isinstance(tokens, dict) else str(tokens)
+                    )
+
+            from agentwatchx.schemas import TraceData
+            try:
+                _client_ref.capture(TraceData(
+                    service="llamaindex",
+                    input_text=ev["input_text"],
+                    output_text=output_text or None,
+                    llm_model=ev["model"],
+                    duration_ms=round(duration_ms, 2),
+                    metadata=ev["metadata"],
+                ))
+            except Exception as exc:
+                logger.debug("Failed to capture LlamaIndex trace: %s", exc)
+
+        def start_trace(self, trace_id: str | None = None) -> None:
+            pass
+
+        def end_trace(
+            self,
+            trace_id: str | None = None,
+            trace_map: dict[str, list[str]] | None = None,
+        ) -> None:
+            pass
+
+    _handler_instance = AWXLlamaHandler()
+
+    # Register globally via Settings.callback_manager
+    try:
+        if Settings.callback_manager is None:
+            Settings.callback_manager = CallbackManager([_handler_instance])
+        else:
+            Settings.callback_manager.add_handler(_handler_instance)
+        logger.info("LlamaIndex callback handler registered globally")
+    except Exception as exc:
+        logger.warning("Could not register LlamaIndex handler globally: %s. "
+                       "Use get_callback_handler() manually.", exc)
+
+    _patched = True
+
+
+def get_callback_handler():
+    """Return the AWX handler for manual use with LlamaIndex.
+
+    Usage:
+        from agentwatchx.integrations.llamaindex_cb import get_callback_handler
+        from llama_index.core import Settings
+        Settings.callback_manager.add_handler(get_callback_handler())
+    """
+    return _handler_instance
+
+
+def unpatch():
+    """Remove the handler."""
+    global _handler_instance, _patched
+    _handler_instance = None
+    _patched = False

agentwatchx/integrations/openai_patch.py

@@ -0,0 +1,231 @@
+"""
+Auto-instrumentation for the OpenAI Python SDK (v1+).
+
+Patches:
+  - chat.completions.create (sync + async)
+  - Handles both regular and streaming responses
+
+After agentwatchx.init(), every OpenAI call is traced automatically.
+"""
+
+import time
+import functools
+import logging
+
+logger = logging.getLogger("agentwatchx.integrations.openai")
+
+_original_create = None
+_original_async_create = None
+_client_ref = None
+_patched = False
+
+
+def patch(awx_client):
+    """Monkey-patch openai chat completions."""
+    global _original_create, _original_async_create, _client_ref, _patched
+    if _patched:
+        return
+    _client_ref = awx_client
+
+    try:
+        from openai.resources.chat.completions import Completions
+    except ImportError:
+        logger.debug("openai chat completions module not found, skipping")
+        return
+
+    _original_create = Completions.create
+
+    @functools.wraps(_original_create)
+    def patched_create(self, *args, **kwargs):
+        stream = kwargs.get("stream", False)
+        start = time.perf_counter()
+
+        if stream:
+            # For streaming, wrap the iterator to capture chunks
+            result = _original_create(self, *args, **kwargs)
+            return _wrap_stream(result, kwargs, start)
+
+        error = None
+        result = None
+        try:
+            result = _original_create(self, *args, **kwargs)
+            return result
+        except Exception as exc:
+            error = exc
+            raise
+        finally:
+            duration_ms = (time.perf_counter() - start) * 1000
+            _capture_trace(kwargs, result, error, duration_ms)
+
+    Completions.create = patched_create
+
+    # Patch async
+    try:
+        from openai.resources.chat.completions import AsyncCompletions
+        _original_async_create = AsyncCompletions.create
+
+        @functools.wraps(_original_async_create)
+        async def patched_async_create(self, *args, **kwargs):
+            stream = kwargs.get("stream", False)
+            start = time.perf_counter()
+
+            if stream:
+                result = await _original_async_create(self, *args, **kwargs)
+                return _wrap_async_stream(result, kwargs, start)
+
+            error = None
+            result = None
+            try:
+                result = await _original_async_create(self, *args, **kwargs)
+                return result
+            except Exception as exc:
+                error = exc
+                raise
+            finally:
+                duration_ms = (time.perf_counter() - start) * 1000
+                _capture_trace(kwargs, result, error, duration_ms)
+
+        AsyncCompletions.create = patched_async_create
+    except ImportError:
+        pass
+
+    _patched = True
+    logger.info("OpenAI auto-instrumentation applied")
+
+
+def unpatch():
+    """Restore original methods."""
+    global _original_create, _original_async_create, _patched
+    if _original_create:
+        from openai.resources.chat.completions import Completions
+        Completions.create = _original_create
+        _original_create = None
+    if _original_async_create:
+        from openai.resources.chat.completions import AsyncCompletions
+        AsyncCompletions.create = _original_async_create
+        _original_async_create = None
+    _patched = False
+
+
+def _wrap_stream(stream, kwargs, start):
+    """Wrap a sync streaming response to capture the full output."""
+    chunks = []
+    try:
+        for chunk in stream:
+            chunks.append(chunk)
+            yield chunk
+    finally:
+        duration_ms = (time.perf_counter() - start) * 1000
+        _capture_stream_trace(kwargs, chunks, duration_ms)
+
+
+async def _wrap_async_stream(stream, kwargs, start):
+    """Wrap an async streaming response to capture the full output."""
+    chunks = []
+    try:
+        async for chunk in stream:
+            chunks.append(chunk)
+            yield chunk
+    finally:
+        duration_ms = (time.perf_counter() - start) * 1000
+        _capture_stream_trace(kwargs, chunks, duration_ms)
+
+
+def _capture_stream_trace(kwargs, chunks, duration_ms):
+    """Build a trace from collected stream chunks."""
+    if _client_ref is None or not chunks:
+        return
+
+    from agentwatchx.schemas import TraceData
+
+    model = kwargs.get("model", "unknown")
+    messages = kwargs.get("messages", [])
+    input_text = messages[-1].get("content", "") if messages else ""
+
+    # Reassemble streamed content
+    content_parts = []
+    for chunk in chunks:
+        try:
+            delta = chunk.choices[0].delta
+            if delta and delta.content:
+                content_parts.append(delta.content)
+        except (IndexError, AttributeError):
+            pass
+
+    output_text = "".join(content_parts)
+    metadata = {"provider": "openai", "streamed": True}
+
+    # Try to get usage from the last chunk (OpenAI includes it there)
+    try:
+        last = chunks[-1]
+        if hasattr(last, "usage") and last.usage:
+            metadata["prompt_tokens"] = last.usage.prompt_tokens
+            metadata["completion_tokens"] = last.usage.completion_tokens
+            metadata["total_tokens"] = last.usage.total_tokens
+    except (AttributeError, TypeError):
+        pass
+
+    try:
+        _client_ref.capture(TraceData(
+            service="openai",
+            input_text=input_text,
+            output_text=output_text or None,
+            llm_model=model,
+            duration_ms=round(duration_ms, 2),
+            metadata=metadata,
+        ))
+    except Exception as exc:
+        logger.debug("Failed to capture OpenAI stream trace: %s", exc)
+
+
+def _capture_trace(kwargs, result, error, duration_ms):
+    """Extract trace data from a non-streaming OpenAI chat completion call."""
+    if _client_ref is None:
+        return
+
+    from agentwatchx.schemas import TraceData
+
+    model = kwargs.get("model", "unknown")
+    messages = kwargs.get("messages", [])
+    input_text = messages[-1].get("content", "") if messages else ""
+
+    output_text = None
+    tool_calls = []
+    metadata = {"provider": "openai"}
+
+    if error:
+        metadata["error"] = str(error)
+    elif result:
+        try:
+            choice = result.choices[0]
+            output_text = choice.message.content or ""
+
+            # Capture tool calls if the model made any
+            if hasattr(choice.message, "tool_calls") and choice.message.tool_calls:
+                from agentwatchx.schemas import ToolCallData
+                for tc in choice.message.tool_calls:
+                    tool_calls.append(ToolCallData(
+                        name=tc.function.name,
+                        input=tc.function.arguments,
+                        status="success",
+                    ))
+
+            if hasattr(result, "usage") and result.usage:
+                metadata["prompt_tokens"] = result.usage.prompt_tokens
+                metadata["completion_tokens"] = result.usage.completion_tokens
+                metadata["total_tokens"] = result.usage.total_tokens
+        except (IndexError, AttributeError):
+            output_text = str(result)
+
+    try:
+        _client_ref.capture(TraceData(
+            service="openai",
+            input_text=input_text,
+            output_text=output_text,
+            llm_model=model,
+            duration_ms=round(duration_ms, 2),
+            tool_calls=tool_calls,
+            metadata=metadata,
+        ))
+    except Exception as exc:
+        logger.debug("Failed to capture OpenAI trace: %s", exc)

agentwatchx/schemas.py

@@ -0,0 +1,19 @@
+from pydantic import BaseModel
+
+
+class ToolCallData(BaseModel):
+    name: str
+    input: dict | str | None = None
+    output: dict | str | None = None
+    status: str = "success"
+    duration_ms: float | None = None
+
+
+class TraceData(BaseModel):
+    service: str = "default"
+    input_text: str | None = None
+    output_text: str | None = None
+    llm_model: str | None = None
+    duration_ms: float | None = None
+    tool_calls: list[ToolCallData] = []
+    metadata: dict = {}

agentwatchx-0.1.0.dist-info/METADATA

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: agentwatchx
+Version: 0.1.0
+Summary: Observability SDK for AI Agent Execution — catches hallucinations, silent failures, and missing executions
+License: MIT
+Project-URL: Homepage, https://agentwatchx.com
+Project-URL: Documentation, https://agentwatchx.com/docs
+Keywords: ai,agents,observability,llm,tracing,openai,anthropic,langchain
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.18.0; extra == "anthropic"
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.10.0; extra == "llamaindex"
+Provides-Extra: all
+Requires-Dist: openai>=1.0.0; extra == "all"
+Requires-Dist: anthropic>=0.18.0; extra == "all"
+Requires-Dist: langchain-core>=0.1.0; extra == "all"
+Requires-Dist: llama-index-core>=0.10.0; extra == "all"
+Dynamic: license-file
+
+# AgentWatchX Python SDK
+
+Observability for AI agents. Catches hallucinations, silent failures, and missing executions automatically.
+
+## Install
+
+```bash
+pip install agentwatchx
+```
+
+## 2-Line Integration
+
+```python
+import agentwatchx
+agentwatchx.init(api_key="your_api_key")
+
+# That's it. Every OpenAI/Anthropic/LangChain/LlamaIndex call is now traced.
+# No decorators, no wrappers, no code changes needed.
+```
+
+## What it captures
+
+- Model, input, output, token usage, latency — automatically
+- Tool calls made by the LLM (function calling)
+- Hallucination detection — agent claims actions it never performed
+- Failure masking — tool errors the agent hides from users
+- Missing execution — user asks for action, agent just talks
+
+## Supported Libraries
+
+| Library | Auto-instrumented |
+|---|---|
+| OpenAI | ✅ |
+| Anthropic | ✅ |
+| LangChain | ✅ |
+| LlamaIndex | ✅ |
+
+## Configuration
+
+```python
+agentwatchx.init(
+    api_key="your_api_key",
+    endpoint="https://api.agentwatchx.com",  # or self-hosted
+    service="my-agent",
+    flush_interval=5.0,
+    batch_size=100,
+    auto_instrument=True,  # set False to disable auto-patching
+)
+```
+
+## Advanced Usage
+
+```python
+# Manual trace decorator
+@agentwatchx.trace
+def my_agent(query: str):
+    return client.chat.completions.create(...)
+
+# Manual logging
+agentwatchx.log({"service": "my-agent", "input": "hello", "output": "world"})
+
+# Check status
+print(agentwatchx.status())
+# → {"initialized": True, "instrumented": ["openai"], "buffered_traces": 0}
+```
+
+## Links
+
+- [Documentation](https://agentwatchx.com/docs)
+- [Dashboard](https://agentwatchx.com/dashboard)

agentwatchx-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+agentwatchx/__init__.py,sha256=kFMrM1QDujlVE40h7eLyAwS1isIx8zKDR9qgaI9g_hI,3547
+agentwatchx/client.py,sha256=Ne-LViVPL0bxTFxHcJ_PIa9Rw3MzT2nOXOywAKj_kP8,2643
+agentwatchx/decorators.py,sha256=VfXJFhHNWqeIbhhcHAunf85DtTpbv0WP8YXhPrvoy38,1744
+agentwatchx/schemas.py,sha256=Z2-iIw_KgzsmmLNDtt86wgOdrT-hARO3vfVo6AiTbvg,478
+agentwatchx/integrations/__init__.py,sha256=TA-vaORvKhvDuw2H2NAdOjG8GD33dMb7PXFlsZb-FPk,1727
+agentwatchx/integrations/anthropic_patch.py,sha256=t1CGK5cmfNhm77JJgc5RwpYH8DAc_XE0OKZ1tTn4yss,8328
+agentwatchx/integrations/langchain_cb.py,sha256=RJJnYiB0_OJ5u2SfwAhUrUYx2kecniHQD-AUHuBJ-YE,6826
+agentwatchx/integrations/llamaindex_cb.py,sha256=vIT0JqZVH6Ax2ZLBVhjJnN1OOiMMG_EzbVXyjmq2kX8,5915
+agentwatchx/integrations/openai_patch.py,sha256=7vCAoUMz1YlESCvOPcSmLBbPd3keTr8QBmG5Jclk7lE,7408
+agentwatchx-0.1.0.dist-info/licenses/LICENSE,sha256=ayCgDXVU9p_G32jQoiRdGKnzuvUVX9Nd6DOphbLT2lI,1068
+agentwatchx-0.1.0.dist-info/METADATA,sha256=evvx63TTUIyG_G6u9rNSH_OVizUHOx3q6DQR0FbKqC8,2959
+agentwatchx-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+agentwatchx-0.1.0.dist-info/top_level.txt,sha256=3viPcduYhcOK5h4rybvsYiZzjIzYTk4OLz8LEPlzS0Q,12
+agentwatchx-0.1.0.dist-info/RECORD,,

agentwatchx-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agentwatchx-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentWatchX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentwatchx-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agentwatchx