nova-agentops 1.3.0__py3-none-any.whl

agent_ops/__init__.py

@@ -0,0 +1,291 @@
+"""AgentOps SDK – observability client for AI agents."""
+
+import asyncio
+import functools
+import json
+import os
+import random
+import uuid
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+import httpx
+from dotenv import load_dotenv
+
+load_dotenv()
+
+__version__ = "1.3.0"
+__all__ = ["AgentOps", "AgentOpsSync", "AgentOpsError"]
+
+
+class AgentOpsError(Exception):
+    """Raised when the AgentOps backend returns an error."""
+
+
+def _redact(obj: Any, keys: List[str]) -> Any:
+    if isinstance(obj, dict):
+        return {k: ("[REDACTED]" if k in keys else _redact(v, keys)) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_redact(x, keys) for x in obj]
+    return obj
+
+
+class AgentOps:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        api_url: Optional[str] = None,
+        timeout: float = 10.0,
+        max_retries: int = 3,
+        transport: Optional[Any] = None,
+        sample_rate: float = 1.0,
+        redact_keys: Optional[List[str]] = None,
+        offline_path: Optional[str] = None,
+    ):
+        self.api_key = api_key or os.getenv("AGENT_OPS_API_KEY")
+        self.api_url = (api_url or os.getenv("AGENT_OPS_URL", "http://127.0.0.1:8001")).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.transport = transport
+        self.sample_rate = max(0.0, min(1.0, sample_rate))
+        self.redact_keys = redact_keys or []
+        self.offline_path = Path(offline_path or os.getenv("AGENT_OPS_OFFLINE_PATH", str(Path.home() / ".agentops" / "queue.jsonl")))
+        self.current_trace_id: Optional[str] = None
+
+    def _headers(self) -> Dict[str, str]:
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["X-API-Key"] = self.api_key
+        return headers
+
+    async def _request(self, method: str, path: str, **kwargs) -> httpx.Response:
+        url = f"{self.api_url}{path}"
+        last_exc: Optional[Exception] = None
+        for attempt in range(1, self.max_retries + 1):
+            try:
+                async with httpx.AsyncClient(timeout=self.timeout, transport=self.transport) as client:
+                    response = await client.request(method, url, headers=self._headers(), **kwargs)
+                if response.status_code >= 500:
+                    last_exc = AgentOpsError(f"Server error {response.status_code}: {response.text}")
+                    await asyncio.sleep((0.2 * attempt) + random.random() * 0.1)
+                    continue
+                return response
+            except (httpx.TimeoutException, httpx.ConnectError, httpx.NetworkError) as exc:
+                last_exc = exc
+                await asyncio.sleep((0.2 * attempt) + random.random() * 0.1)
+        if last_exc is not None:
+            raise AgentOpsError(str(last_exc))
+        raise AgentOpsError("Request failed")
+
+    def _enqueue_offline(self, method: str, path: str, payload: Any):
+        self.offline_path.parent.mkdir(parents=True, exist_ok=True)
+        with self.offline_path.open("a") as f:
+            f.write(json.dumps({"method": method, "path": path, "payload": payload}) + "\n")
+
+    async def _send_or_queue(self, method: str, path: str, **kwargs) -> Optional[httpx.Response]:
+        try:
+            return await self._request(method, path, **kwargs)
+        except AgentOpsError:
+            payload = kwargs.get("json", kwargs.get("params"))
+            self._enqueue_offline(method, path, payload)
+            return None
+
+    async def flush(self) -> int:
+        """Replay queued offline events. Returns number flushed."""
+        if not self.offline_path.exists():
+            return 0
+        lines = self.offline_path.read_text().splitlines()
+        if not lines:
+            return 0
+        flushed = 0
+        remaining = []
+        for line in lines:
+            try:
+                ev = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            try:
+                resp = await self._request(ev["method"], ev["path"], json=ev["payload"])
+                if resp.status_code < 300:
+                    flushed += 1
+                else:
+                    remaining.append(line)
+            except AgentOpsError:
+                remaining.append(line)
+        self.offline_path.write_text("\n".join(remaining) + ("\n" if remaining else ""))
+        return flushed
+
+    async def start_trace(self, session_name: str, metadata: Optional[Dict[str, Any]] = None) -> str:
+        response = await self._send_or_queue("POST", "/api/trace", json={"session_name": session_name, "metadata": metadata or {}})
+        if response is None:
+            raise AgentOpsError("Backend unavailable; trace queued offline")
+        if response.status_code not in (200, 201):
+            raise AgentOpsError(f"Error starting trace: {response.text}")
+        data = response.json()
+        self.current_trace_id = data["id"]
+        return self.current_trace_id
+
+    async def log_step(
+        self,
+        thought: Optional[str] = None,
+        action: Optional[str] = None,
+        observation: Optional[str] = None,
+        state_snapshot: Optional[Dict[str, Any]] = None,
+        trace_id: Optional[str] = None,
+        prompt_tokens: int = 0,
+        completion_tokens: int = 0,
+        model: Optional[str] = None,
+        cost_usd: float = 0.0,
+        usage: Optional[Dict[str, Any]] = None,
+    ) -> Optional[Dict[str, Any]]:
+        if random.random() > self.sample_rate:
+            return None
+        tid = trace_id or self.current_trace_id
+        if not tid:
+            raise AgentOpsError("No active trace found. Call start_trace() first.")
+        if usage:
+            prompt_tokens = usage.get("prompt_tokens", prompt_tokens)
+            completion_tokens = usage.get("completion_tokens", completion_tokens)
+            model = usage.get("model", model)
+            cost_usd = usage.get("cost_usd", cost_usd)
+        snapshot = _redact(state_snapshot or {}, self.redact_keys)
+        payload = {
+            "trace_id": tid,
+            "thought": thought,
+            "action": action,
+            "observation": observation,
+            "state_snapshot": snapshot,
+            "prompt_tokens": prompt_tokens,
+            "completion_tokens": completion_tokens,
+            "model": model,
+            "cost_usd": cost_usd,
+        }
+        response = await self._send_or_queue("POST", "/api/log", json=payload)
+        if response is None:
+            return None
+        if response.status_code not in (200, 201):
+            raise AgentOpsError(f"Error logging step: {response.text}")
+        return response.json()
+
+    async def log_steps_batch(self, items: List[Dict[str, Any]]) -> Optional[List[Dict[str, Any]]]:
+        redacted = []
+        for it in items:
+            redacted.append({
+                "trace_id": it["trace_id"],
+                "thought": it.get("thought"),
+                "action": it.get("action"),
+                "observation": it.get("observation"),
+                "state_snapshot": _redact(it.get("state_snapshot") or {}, self.redact_keys),
+            })
+        response = await self._send_or_queue("POST", "/api/logs/batch", json={"steps": redacted})
+        if response is None:
+            return None
+        if response.status_code not in (200, 201):
+            raise AgentOpsError(f"Error logging batch: {response.text}")
+        return response.json()
+
+    async def end_trace(self, trace_id: Optional[str] = None, status: str = "completed") -> Optional[Dict[str, Any]]:
+        tid = trace_id or self.current_trace_id
+        if not tid:
+            raise AgentOpsError("No active trace found.")
+        response = await self._send_or_queue("POST", f"/api/trace/{tid}/end", json={"status": status})
+        if response is None:
+            return None
+        if response.status_code not in (200, 201):
+            raise AgentOpsError(f"Error ending trace: {response.text}")
+        if tid == self.current_trace_id:
+            self.current_trace_id = None
+        return response.json()
+
+    async def get_trace(self, trace_id: str) -> Dict[str, Any]:
+        response = await self._request("GET", f"/api/traces/{trace_id}")
+        if response.status_code != 200:
+            raise AgentOpsError(f"Error fetching trace: {response.text}")
+        return response.json()
+
+    async def list_traces(self, limit: int = 50, offset: int = 0) -> List[Dict[str, Any]]:
+        response = await self._request("GET", "/api/traces", params={"limit": limit, "offset": offset})
+        if response.status_code != 200:
+            raise AgentOpsError(f"Error listing traces: {response.text}")
+        return response.json()
+
+    def trace(self, session_name: str, metadata: Optional[Dict[str, Any]] = None):
+        return _TraceContext(self, session_name, metadata)
+
+    def track(self, func: Optional[Callable] = None):
+        def decorator(f: Callable):
+            @functools.wraps(f)
+            async def wrapper(*args, **kwargs):
+                args_repr = [repr(a) for a in args]
+                kwargs_repr = [f"{k}={v!r}" for k, v in kwargs.items()]
+                input_str = ", ".join(args_repr + kwargs_repr)
+                try:
+                    await self.log_step(
+                        thought=f"Executing function {f.__name__} with inputs: {input_str}",
+                        action=f.__name__,
+                    )
+                except Exception as e:  # noqa: BLE001
+                    print(f"AgentOps Logging Error (Intent): {e}")
+
+                try:
+                    result = await f(*args, **kwargs)
+                    await self.log_step(action=f.__name__, observation=str(result))
+                    return result
+                except Exception as e:  # noqa: BLE001
+                    try:
+                        await self.log_step(action=f.__name__, observation=f"ERROR: {str(e)}")
+                    except Exception as log_e:  # noqa: BLE001
+                        print(f"AgentOps Logging Error (Error): {log_e}")
+                    raise
+
+            return wrapper
+
+        if func is None:
+            return decorator
+        return decorator(func)
+
+
+class _TraceContext:
+    def __init__(self, ops: AgentOps, session_name: str, metadata: Optional[Dict[str, Any]]):
+        self.ops = ops
+        self.session_name = session_name
+        self.metadata = metadata
+        self.trace_id: Optional[str] = None
+
+    async def __aenter__(self) -> str:
+        self.trace_id = await self.ops.start_trace(self.session_name, self.metadata)
+        self.ops.current_trace_id = self.trace_id
+        return self.trace_id
+
+    async def __aexit__(self, exc_type, exc, tb) -> bool:
+        try:
+            await self.ops.end_trace(self.trace_id, status="error" if exc else "completed")
+            await self.ops.flush()
+        except Exception:  # noqa: BLE001
+            pass
+        return False
+
+
+class AgentOpsSync:
+    """Synchronous wrapper around AgentOps."""
+
+    def __init__(self, *args, **kwargs):
+        self._async = AgentOps(*args, **kwargs)
+
+    def start_trace(self, *a, **kw):
+        return asyncio.run(self._async.start_trace(*a, **kw))
+
+    def log_step(self, *a, **kw):
+        return asyncio.run(self._async.log_step(*a, **kw))
+
+    def end_trace(self, *a, **kw):
+        return asyncio.run(self._async.end_trace(*a, **kw))
+
+    def flush(self):
+        return asyncio.run(self._async.flush())
+
+    def trace(self, *a, **kw):
+        return self._async.trace(*a, **kw)
+
+    def track(self, *a, **kw):
+        return self._async.track(*a, **kw)

agent_ops/integrations.py

@@ -0,0 +1,61 @@
+"""Optional framework integrations for AgentOps."""
+
+try:
+    from langchain_core.callbacks import BaseCallbackHandler as _LCBase
+except Exception:  # pragma: no cover - optional dependency
+    _LCBase = object
+
+
+class LangChainCallbackHandler(_LCBase):
+    """LangChain callback handler that forwards tool events to AgentOps.
+
+    Usage:
+        from agent_ops.integrations import LangChainCallbackHandler
+        handler = LangChainCallbackHandler(ops)
+        agent.invoke({...}, config={"callbacks": [handler]})
+    """
+
+    def __init__(self, ops, trace_name: str = "langchain-run"):
+        self.ops = ops
+        self.trace_name = trace_name
+        self._trace_started = False
+
+    def on_chain_start(self, *args, **kwargs):
+        if not self._trace_started:
+            import asyncio
+            asyncio.get_event_loop().create_task(self.ops.start_trace(self.trace_name))
+            self._trace_started = True
+
+    def on_tool_start(self, serialized, input_str, **kwargs):
+        import asyncio
+        asyncio.get_event_loop().create_task(
+            self.ops.log_step(thought=f"Tool {serialized.get('name')} started", action=serialized.get("name"), state_snapshot={"input": input_str})
+        )
+
+    def on_tool_end(self, output, **kwargs):
+        import asyncio
+        asyncio.get_event_loop().create_task(
+            self.ops.log_step(observation=str(output))
+        )
+
+    def on_chain_end(self, *args, **kwargs):
+        import asyncio
+        asyncio.get_event_loop().create_task(self.ops.end_trace())
+
+
+def openai_tool_wrapper(ops, func):
+    """Wrap an OpenAI tool function so its calls are traced."""
+    import asyncio
+    import functools
+
+    @functools.wraps(func)
+    async def wrapped(*args, **kwargs):
+        await ops.log_step(thought=f"Calling {func.__name__}", action=func.__name__, state_snapshot={"args": args, "kwargs": kwargs})
+        if asyncio.iscoroutinefunction(func):
+            result = await func(*args, **kwargs)
+        else:
+            result = func(*args, **kwargs)
+        await ops.log_step(action=func.__name__, observation=str(result))
+        return result
+
+    return wrapped

nova_agentops-1.3.0.dist-info/METADATA

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: nova-agentops
+Version: 1.3.0
+Summary: Professional observability SDK for AI Agents
+Author-email: Terry <terry@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Nova799/agent-ops-sdk
+Keywords: ai,observability,agents,tracing,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2; extra == "langchain"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+
+# 🚀 AgentOps SDK
+
+**AgentOps** is a professional observability platform designed specifically for AI Agents. It acts as the "Chrome DevTools" for your LLM-powered applications, allowing you to monitor, debug, and optimize your agent's reasoning process in real-time.
+
+## 🌟 Why AgentOps?
+
+When building AI agents, the biggest challenge is the "Black Box" effect: you see the input and the output, but you don't know *why* the agent made a specific decision or where it got stuck.
+
+AgentOps solves this by capturing:
+- **The Internal Monologue**: See the exact reasoning (Thought) before an action.
+- **Tool Execution**: Track exactly which tool was called and with what parameters.
+- **State Snapshots**: Inspect the internal memory of your agent at any given step.
+- **Visual Tracing**: A dynamic graph visualization of the agent's logic flow.
+
+## 🛠️ Quick Start
+
+### 1. Installation
+
+You can install the SDK directly from this GitHub repository:
+
+```bash
+pip install git+https://github.com/Nova799/agent-ops-sdk.git
+```
+
+### 2. Configuration
+Create a `.env` file in your project root:
+```env
+AGENT_OPS_API_KEY=your_secret_key
+AGENT_OPS_URL=https://api.agentops.io
+```
+
+### 3. Basic Usage
+```python
+import asyncio
+from agent_ops import AgentOps
+
+ops = AgentOps()
+
+async def main():
+    # Context manager handles start/end automatically
+    async with ops.trace(session_name="User Inquiry #123", metadata={"user": "alice"}):
+        await ops.log_step(
+            thought="The user is asking for the weather, I should use the weather tool",
+            action="get_weather",
+            observation="Sunny, 25°C",
+            state_snapshot={"location": "Paris"},
+        )
+
+    # Automatic tracker
+    @ops.track()
+    async def my_tool(param):
+        return f"Processed {param}"
+
+    await ops.start_trace(session_name="tool run")
+    await my_tool("hello")
+    await ops.end_trace()
+
+asyncio.run(main())
+```
+
+### 4. Inspect traces
+```python
+traces = await ops.list_traces(limit=10)
+detail = await ops.get_trace(traces[0]["id"])
+```
+
+### 5. Sync client
+```python
+from agent_ops import AgentOpsSync
+ops = AgentOpsSync()
+ops.start_trace("demo")
+ops.log_step(thought="hi")
+ops.end_trace()
+```
+
+### 6. Sampling & redaction
+```python
+ops = AgentOps(sample_rate=0.1, redact_keys=["password", "token"])
+```
+
+## 📊 The Dashboard
+Once integrated, open the AgentOps Dashboard to:
+- **Visualize** the execution flow as an interactive node graph.
+- **Inspect** detailed logs of every step.
+- **Share** traces with your team for collaborative debugging.
+
+---
+© 2026 AgentOps Team. Built for the future of AI Agents.

nova_agentops-1.3.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+agent_ops/__init__.py,sha256=kEr_yJbns-s0PzTpsPa6YTbvenJD5Aeh-PIG-tm0xuI,11614
+agent_ops/integrations.py,sha256=MMySWdevgo1PO9ZtdO_zlbLgyXVGITPEXw5weXJWyGw,2140
+agent_ops/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nova_agentops-1.3.0.dist-info/METADATA,sha256=oYl9zLLxikBR0LjvTFO6kpgxiR3U1yvcz2YDUTBAKn4,3558
+nova_agentops-1.3.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+nova_agentops-1.3.0.dist-info/top_level.txt,sha256=_7kmbmMSEKvT9fYv98vQE1Cq3Qc7kDz3oiCJ1BMWpOM,10
+nova_agentops-1.3.0.dist-info/RECORD,,

nova_agentops-1.3.0.dist-info/WHEEL

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

nova_agentops-1.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agent_ops