agentwatchx 0.1.0__tar.gz

agentwatchx-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,70 @@
+# 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/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-0.1.0/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-0.1.0/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-0.1.0/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()