peekr 0.1.0__tar.gz

peekr-0.1.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: peekr
+Version: 0.1.0
+Summary: Zero-config observability for AI agents
+License: MIT
+Project-URL: Homepage, https://ashwanijha04.github.io/peekr
+Project-URL: Repository, https://github.com/ashwanijha04/peekr
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.20; extra == "anthropic"
+Provides-Extra: all
+Requires-Dist: openai>=1.0; extra == "all"
+Requires-Dist: anthropic>=0.20; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+# peekr
+
+[![PyPI](https://img.shields.io/pypi/v/peekr)](https://pypi.org/project/peekr/)
+[![CI](https://github.com/ashwanijha04/peekr/actions/workflows/ci.yml/badge.svg)](https://github.com/ashwanijha04/peekr/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
+
+Zero-config observability for AI agents. Auto-instruments OpenAI and Anthropic SDKs — no code changes needed.
+
+```
+pip install peekr
+```
+
+---
+
+## Quickstart
+
+```python
+import peekr
+peekr.instrument()
+
+# Your existing agent code — zero changes
+import openai
+openai.chat.completions.create(model="gpt-4o", messages=[...])
+```
+
+Every LLM call is automatically captured. View your traces:
+
+```bash
+peekr view traces.jsonl
+```
+
+```
+Trace a3f2b1c0  1243ms  891tok
+────────────────────────────────────────────────
+agent.run  1243ms
+   └─ openai.chat.completions [gpt-4o]  821ms  312tok
+   └─ tool.search_web  12ms
+   └─ openai.chat.completions [gpt-4o]  410ms  579tok
+```
+
+---
+
+## Installation
+
+```bash
+# Base (no LLM SDK required)
+pip install peekr
+
+# With OpenAI
+pip install "peekr[openai]"
+
+# With Anthropic
+pip install "peekr[anthropic]"
+
+# Both
+pip install "peekr[all]"
+```
+
+---
+
+## Usage
+
+### Auto-instrument LLM SDKs
+
+```python
+import peekr
+
+peekr.instrument()
+# That's it. All OpenAI and Anthropic calls are now traced.
+```
+
+Options:
+
+```python
+peekr.instrument(
+    console=True,               # print spans as they happen (default: True)
+    jsonl_path="traces.jsonl",  # write to file (default: traces.jsonl)
+    jsonl_path=None,            # disable file output
+)
+```
+
+### Trace your own functions
+
+```python
+from peekr import trace
+
+@trace
+def search_web(query: str) -> list[str]:
+    ...
+
+@trace(name="tool.calculator")
+def calculate(expression: str) -> float:
+    ...
+
+# Async works too
+@trace
+async def fetch_data(url: str) -> dict:
+    ...
+```
+
+Decorated functions automatically become child spans of whatever called them.
+
+### Capture or hide inputs/outputs
+
+```python
+@trace                        # captures args and return value by default
+def search_web(query): ...
+
+@trace(capture_io=False)      # opt out for sensitive data
+def get_api_key(): ...
+```
+
+### Manual spans
+
+For cases where a decorator doesn't fit:
+
+```python
+from peekr import start_span, end_span
+
+span, token = start_span("my.operation")
+span.attributes["custom_key"] = "custom_value"
+try:
+    do_work()
+    span.status = "ok"
+except Exception as e:
+    span.status = "error"
+    span.attributes["error"] = str(e)
+    raise
+finally:
+    end_span(span, token)
+```
+
+### Viewing traces
+
+```bash
+# Basic tree view
+peekr view traces.jsonl
+
+# Show inputs and outputs
+peekr view --io traces.jsonl
+```
+
+---
+
+## What gets captured
+
+| Field | Description |
+|---|---|
+| `name` | Span name (function name or custom) |
+| `duration_ms` | Wall-clock time |
+| `status` | `ok` or `error` |
+| `model` | LLM model name (auto) |
+| `tokens_input` | Prompt tokens (auto) |
+| `tokens_output` | Completion tokens (auto) |
+| `tokens_total` | Total tokens (auto) |
+| `input` | Serialized function args (truncated) |
+| `output` | Serialized return value (truncated) |
+| `error` | Exception message if status is `error` |
+
+---
+
+## Custom exporters
+
+```python
+from peekr.exporters import add_exporter
+
+class MyExporter:
+    def export(self, span):
+        # send to your backend
+        requests.post("https://my-backend.com/spans", json=span.to_dict())
+
+peekr.instrument()
+add_exporter(MyExporter())
+```
+
+---
+
+## How it works
+
+`instrument()` monkey-patches the OpenAI and Anthropic SDK methods before your code runs. Python looks up function references at call time, so every subsequent call hits the wrapper instead of the original — with zero changes to your code.
+
+Span context (parent/child relationships) is tracked via Python's `contextvars.ContextVar`, which propagates correctly across `async/await` without any manual passing.
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/ashwanijha04/peekr
+cd peekr
+pip install -e ".[dev]"
+pytest
+```
+
+PRs welcome. Open an issue first for large changes.
+
+---
+
+## License
+
+MIT

peekr-0.1.0/README.md

@@ -0,0 +1,202 @@
+# peekr
+
+[![PyPI](https://img.shields.io/pypi/v/peekr)](https://pypi.org/project/peekr/)
+[![CI](https://github.com/ashwanijha04/peekr/actions/workflows/ci.yml/badge.svg)](https://github.com/ashwanijha04/peekr/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
+
+Zero-config observability for AI agents. Auto-instruments OpenAI and Anthropic SDKs — no code changes needed.
+
+```
+pip install peekr
+```
+
+---
+
+## Quickstart
+
+```python
+import peekr
+peekr.instrument()
+
+# Your existing agent code — zero changes
+import openai
+openai.chat.completions.create(model="gpt-4o", messages=[...])
+```
+
+Every LLM call is automatically captured. View your traces:
+
+```bash
+peekr view traces.jsonl
+```
+
+```
+Trace a3f2b1c0  1243ms  891tok
+────────────────────────────────────────────────
+agent.run  1243ms
+   └─ openai.chat.completions [gpt-4o]  821ms  312tok
+   └─ tool.search_web  12ms
+   └─ openai.chat.completions [gpt-4o]  410ms  579tok
+```
+
+---
+
+## Installation
+
+```bash
+# Base (no LLM SDK required)
+pip install peekr
+
+# With OpenAI
+pip install "peekr[openai]"
+
+# With Anthropic
+pip install "peekr[anthropic]"
+
+# Both
+pip install "peekr[all]"
+```
+
+---
+
+## Usage
+
+### Auto-instrument LLM SDKs
+
+```python
+import peekr
+
+peekr.instrument()
+# That's it. All OpenAI and Anthropic calls are now traced.
+```
+
+Options:
+
+```python
+peekr.instrument(
+    console=True,               # print spans as they happen (default: True)
+    jsonl_path="traces.jsonl",  # write to file (default: traces.jsonl)
+    jsonl_path=None,            # disable file output
+)
+```
+
+### Trace your own functions
+
+```python
+from peekr import trace
+
+@trace
+def search_web(query: str) -> list[str]:
+    ...
+
+@trace(name="tool.calculator")
+def calculate(expression: str) -> float:
+    ...
+
+# Async works too
+@trace
+async def fetch_data(url: str) -> dict:
+    ...
+```
+
+Decorated functions automatically become child spans of whatever called them.
+
+### Capture or hide inputs/outputs
+
+```python
+@trace                        # captures args and return value by default
+def search_web(query): ...
+
+@trace(capture_io=False)      # opt out for sensitive data
+def get_api_key(): ...
+```
+
+### Manual spans
+
+For cases where a decorator doesn't fit:
+
+```python
+from peekr import start_span, end_span
+
+span, token = start_span("my.operation")
+span.attributes["custom_key"] = "custom_value"
+try:
+    do_work()
+    span.status = "ok"
+except Exception as e:
+    span.status = "error"
+    span.attributes["error"] = str(e)
+    raise
+finally:
+    end_span(span, token)
+```
+
+### Viewing traces
+
+```bash
+# Basic tree view
+peekr view traces.jsonl
+
+# Show inputs and outputs
+peekr view --io traces.jsonl
+```
+
+---
+
+## What gets captured
+
+| Field | Description |
+|---|---|
+| `name` | Span name (function name or custom) |
+| `duration_ms` | Wall-clock time |
+| `status` | `ok` or `error` |
+| `model` | LLM model name (auto) |
+| `tokens_input` | Prompt tokens (auto) |
+| `tokens_output` | Completion tokens (auto) |
+| `tokens_total` | Total tokens (auto) |
+| `input` | Serialized function args (truncated) |
+| `output` | Serialized return value (truncated) |
+| `error` | Exception message if status is `error` |
+
+---
+
+## Custom exporters
+
+```python
+from peekr.exporters import add_exporter
+
+class MyExporter:
+    def export(self, span):
+        # send to your backend
+        requests.post("https://my-backend.com/spans", json=span.to_dict())
+
+peekr.instrument()
+add_exporter(MyExporter())
+```
+
+---
+
+## How it works
+
+`instrument()` monkey-patches the OpenAI and Anthropic SDK methods before your code runs. Python looks up function references at call time, so every subsequent call hits the wrapper instead of the original — with zero changes to your code.
+
+Span context (parent/child relationships) is tracked via Python's `contextvars.ContextVar`, which propagates correctly across `async/await` without any manual passing.
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/ashwanijha04/peekr
+cd peekr
+pip install -e ".[dev]"
+pytest
+```
+
+PRs welcome. Open an issue first for large changes.
+
+---
+
+## License
+
+MIT

peekr-0.1.0/peekr/__init__.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+from .exporters import add_exporter, JSONLExporter, ConsoleExporter
+from .context import start_span, end_span, get_current_span
+from .decorators import trace
+from .patches.openai_patch import patch_openai
+from .patches.anthropic_patch import patch_anthropic
+
+
+def instrument(exporter=None, console: bool = True, jsonl_path: str | None = "traces.jsonl"):
+    """
+    Auto-instrument OpenAI and Anthropic SDKs.
+    Call this once before any LLM calls.
+    """
+    if exporter:
+        add_exporter(exporter)
+    else:
+        if console:
+            add_exporter(ConsoleExporter())
+        if jsonl_path:
+            add_exporter(JSONLExporter(jsonl_path))
+
+    patch_openai()
+    patch_anthropic()
+
+
+__all__ = ["instrument", "trace", "start_span", "end_span", "get_current_span", "JSONLExporter", "ConsoleExporter"]

peekr-0.1.0/peekr/cli.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+import json
+import sys
+from collections import defaultdict
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: peekr view [--io] <traces.jsonl>")
+        sys.exit(1)
+
+    cmd = sys.argv[1]
+    if cmd == "view":
+        args = sys.argv[2:]
+        show_io = "--io" in args
+        args = [a for a in args if not a.startswith("--")]
+        path = args[0] if args else "traces.jsonl"
+        view_traces(path, show_io=show_io)
+    else:
+        print(f"Unknown command: {cmd}")
+        sys.exit(1)
+
+
+def view_traces(path: str, show_io: bool = False):
+    try:
+        with open(path) as f:
+            spans = [json.loads(line) for line in f if line.strip()]
+    except FileNotFoundError:
+        print(f"No traces file at {path}")
+        return
+
+    traces = defaultdict(list)
+    for span in spans:
+        traces[span["trace_id"]].append(span)
+
+    for i, (trace_id, trace_spans) in enumerate(traces.items()):
+        if i > 0:
+            print()
+        total_ms = sum(s.get("duration_ms") or 0 for s in trace_spans if s["parent_id"] is None)
+        total_tokens = sum(s.get("attributes", {}).get("tokens_total", 0) for s in trace_spans)
+        token_str = f"  {total_tokens} tokens" if total_tokens else ""
+        print(f"Trace {trace_id[:8]}  {total_ms:.0f}ms{token_str}")
+        print("─" * 48)
+        roots = [s for s in trace_spans if s["parent_id"] is None]
+        for root in roots:
+            _print_span(root, trace_spans, indent=0, show_io=show_io)
+
+
+def _print_span(span, all_spans, indent, show_io):
+    duration = f"{span['duration_ms']:.0f}ms" if span.get("duration_ms") else "  ?"
+    attrs = span.get("attributes", {})
+    model = f" [{attrs['model']}]" if "model" in attrs else ""
+    tokens = f" {attrs['tokens_total']}tok" if "tokens_total" in attrs else ""
+    error = " \033[31mERROR\033[0m" if span["status"] == "error" else ""
+
+    connector = "└─ " if indent > 0 else ""
+    prefix = "   " * indent + connector
+    print(f"{prefix}\033[1m{span['name']}\033[0m{model}  {duration}{tokens}{error}")
+
+    if show_io:
+        io_prefix = "   " * (indent + 1)
+        if "input" in attrs:
+            print(f"{io_prefix}\033[2min:  {attrs['input'][:120]}\033[0m")
+        if "output" in attrs:
+            print(f"{io_prefix}\033[2mout: {attrs['output'][:120]}\033[0m")
+        if "error" in attrs and span["status"] == "error":
+            print(f"{io_prefix}\033[31merr: {attrs['error']}\033[0m")
+
+    children = [s for s in all_spans if s.get("parent_id") == span["span_id"]]
+    for child in children:
+        _print_span(child, all_spans, indent + 1, show_io)

peekr-0.1.0/peekr/context.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+import uuid
+from contextvars import ContextVar
+from typing import Optional
+
+from .span import Span
+
+_current_span: ContextVar[Optional[Span]] = ContextVar("current_span", default=None)
+_current_trace_id: ContextVar[Optional[str]] = ContextVar("current_trace_id", default=None)
+
+
+def get_current_span() -> Optional[Span]:
+    return _current_span.get()
+
+
+def get_or_create_trace_id() -> str:
+    trace_id = _current_trace_id.get()
+    if trace_id is None:
+        trace_id = uuid.uuid4().hex
+        _current_trace_id.set(trace_id)
+    return trace_id
+
+
+def start_span(name: str) -> tuple[Span, object, object]:
+    trace_id = get_or_create_trace_id()
+    parent = get_current_span()
+    span = Span(
+        name=name,
+        trace_id=trace_id,
+        parent_id=parent.span_id if parent else None,
+    )
+    span_token = _current_span.set(span)
+    return span, span_token
+
+
+def end_span(span: Span, span_token: object) -> None:
+    span.finish()
+    _current_span.reset(span_token)

peekr-0.1.0/peekr/decorators.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+import asyncio
+import functools
+import json
+from typing import Callable
+
+from .context import start_span, end_span
+from .exporters import export_span
+
+_TRUNCATE = 500
+
+
+def _serialize(value) -> str:
+    try:
+        s = json.dumps(value, default=str)
+    except Exception:
+        s = str(value)
+    return s if len(s) <= _TRUNCATE else s[:_TRUNCATE] + "…"
+
+
+def trace(_func=None, *, name: str | None = None, capture_io: bool = True):
+    """
+    Decorator to trace any function as a span.
+
+    Usage:
+        @trace
+        def my_tool(query): ...
+
+        @trace(name="tool.search")
+        def search(query): ...
+
+        @trace(name="tool.search", capture_io=False)
+        def search(query): ...
+    """
+    def decorator(func: Callable) -> Callable:
+        span_name = name or f"{func.__module__}.{func.__qualname__}"
+
+        if asyncio.iscoroutinefunction(func):
+            @functools.wraps(func)
+            async def async_wrapper(*args, **kwargs):
+                span, token = start_span(span_name)
+                if capture_io:
+                    span.attributes["input"] = _serialize({"args": args, "kwargs": kwargs})
+                try:
+                    result = await func(*args, **kwargs)
+                    span.status = "ok"
+                    if capture_io:
+                        span.attributes["output"] = _serialize(result)
+                    return result
+                except Exception as e:
+                    span.status = "error"
+                    span.attributes["error"] = str(e)
+                    raise
+                finally:
+                    end_span(span, token)
+                    export_span(span)
+            return async_wrapper
+        else:
+            @functools.wraps(func)
+            def sync_wrapper(*args, **kwargs):
+                span, token = start_span(span_name)
+                if capture_io:
+                    span.attributes["input"] = _serialize({"args": args, "kwargs": kwargs})
+                try:
+                    result = func(*args, **kwargs)
+                    span.status = "ok"
+                    if capture_io:
+                        span.attributes["output"] = _serialize(result)
+                    return result
+                except Exception as e:
+                    span.status = "error"
+                    span.attributes["error"] = str(e)
+                    raise
+                finally:
+                    end_span(span, token)
+                    export_span(span)
+            return sync_wrapper
+
+    if _func is not None:
+        return decorator(_func)
+    return decorator

peekr-0.1.0/peekr/exporters.py

@@ -0,0 +1,36 @@
+import json
+import os
+from .span import Span
+
+
+class JSONLExporter:
+    def __init__(self, path: str = "traces.jsonl"):
+        self.path = path
+
+    def export(self, span: Span) -> None:
+        with open(self.path, "a") as f:
+            f.write(json.dumps(span.to_dict()) + "\n")
+
+
+class ConsoleExporter:
+    def export(self, span: Span) -> None:
+        duration = f"{span.duration_ms:.1f}ms" if span.duration_ms else "?"
+        indent = "  " if span.parent_id else ""
+        attrs = ""
+        if "model" in span.attributes:
+            attrs += f" model={span.attributes['model']}"
+        if "tokens_total" in span.attributes:
+            attrs += f" tokens={span.attributes['tokens_total']}"
+        print(f"{indent}[{span.name}] {duration}{attrs}")
+
+
+_exporters: list = []
+
+
+def add_exporter(exporter) -> None:
+    _exporters.append(exporter)
+
+
+def export_span(span: Span) -> None:
+    for exporter in _exporters:
+        exporter.export(span)