oopstrace 0.1.0__tar.gz

oopstrace-0.1.0/.gitignore

@@ -0,0 +1,247 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# ===================
+# Editor
+# ===================
+*.swp
+*.swo
+*~
+
+# ===================
+# Python
+# ===================
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*__pycache__*
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.env
+.venv
+venv/
+ENV/
+env.bak/
+venv.bak/
+.conda
+
+# Testing
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+**/.pytest_cache
+cover/
+
+# Type checkers
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pytype/
+.pyre/
+
+# Linters
+.ruff_cache/
+
+# Jupyter
+.ipynb_checkpoints
+**/.ipynb_checkpoints/
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# pdm
+.pdm.toml
+.pdm-python
+.pdm-build/
+__pypackages__/
+
+# Cython debug symbols
+cython_debug/
+
+# PyPI
+.pypirc
+
+# ===================
+# Node.js / Next.js
+# ===================
+
+# Dependencies
+node_modules/
+**/node_modules
+/.pnp
+.pnp.js
+/.pnpm-store
+.pnpm-store
+
+# Next.js
+.next/
+**/.next/*
+/out/
+next-env.d.ts
+
+# Turbo
+.turbo
+**/.turbo/*
+
+# Build
+/build
+**/dist
+
+# Debug logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# Yarn
+.yarn
+
+# TypeScript
+*.tsbuildinfo
+
+# Vercel
+.vercel
+
+# Generated
+/generated
+
+# ===================
+# Environment Files
+# ===================
+
+# Local env files - do not commit any .env files except examples
+.env*
+!.env.example
+!.env.development
+!.env.test.example
+
+# Local config files
+*.local.*
+
+# ===================
+# IDE / Editors
+# ===================
+
+# JetBrains (IntelliJ, PyCharm, WebStorm)
+.idea/
+
+# VS Code (keep extensions.json if needed)
+# .vscode/
+
+# Cursor
+.cursorrules
+.cursorignore
+.cursorindexingignore
+
+# ===================
+# Database
+# ===================
+
+# SQLite
+*.sqlite
+*.sqlite-journal
+*.db
+*.db-journal
+traceroot.db
+
+# Prisma
+/prisma/db.sqlite
+/prisma/db.sqlite-journal
+
+
+# ===================
+# Testing / Coverage
+# ===================
+
+/coverage
+/certs/
+test-results/
+web/test-results/*
+
+# ===================
+# System Files
+# ===================
+
+.DS_Store
+**/.DS_Store
+*.pem
+
+# ===================
+# Claude / AI Tools
+# ===================
+
+.claude/tsc-cache
+**/.refactor/
+**/.playwright-mcp/
+
+# ===================
+# Project Specific
+# ===================
+
+# OpenAPI spec copied during build
+/public/openapi*.yml
+
+# Data files (keep test fixtures)
+*.csv
+!tests/**/fixtures/*.csv
+*.hdf
+*.hdf5
+*.parquet
+
+# Scratch/working directories
+/.scratch/
+/.worktrees/
+
+# References (third-party code for study)
+# Keep tracked but ignore generated content within
+references/**/venv/
+references/**/__pycache__/
+references/**/.venv/
+references/**/node_modules/
+
+# ===================
+# Terraform
+# ===================
+*.tfvars
+!*.tfvars.example
+.terraform/
+*.tfstate
+*.tfstate.backup
+.terraform.lock.hcl
+.worktrees/

oopstrace-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: oopstrace
+Version: 0.1.0
+Summary: Oopstrace Python SDK — LLM observability with automatic batching
+License: MIT
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# OopsTrace Python SDK
+
+LLM observability for Python. Trace every call, span, token count, and cost — visible instantly at [app.oopstrace.com](https://app.oopstrace.com).
+
+## Install
+
+```bash
+pip install oopstrace
+```
+
+## Quickstart
+
+```python
+import oopstrace
+
+oopstrace.init(
+    api_key="tr_...",       # from app.oopstrace.com → project → Access Keys
+    project_id="...",       # your project ID
+)
+
+@oopstrace.trace
+def run_agent(user_input: str) -> str:
+    with oopstrace.span("llm-call", span_kind="LLM") as s:
+        s.set_output("Hello from OopsTrace")
+        return "Hello from OopsTrace"
+
+run_agent("test")
+oopstrace.flush()
+```
+
+## Auto-instrument OpenAI / Anthropic
+
+```python
+oopstrace.init(api_key="tr_...", project_id="...", auto_instrument=True)
+
+# All openai.chat.completions.create() and anthropic.messages.create()
+# calls are now traced automatically — no decorators needed.
+```
+
+## Manual spans
+
+```python
+@oopstrace.trace
+def pipeline(query: str):
+    with oopstrace.span("retrieval", span_kind="TOOL") as s:
+        docs = retrieve(query)
+        s.set_input(query)
+        s.set_output(str(docs))
+
+    with oopstrace.span("generate", span_kind="LLM") as s:
+        answer = llm(query, docs)
+        s.set_model("gpt-4o")
+        s.set_tokens(input=100, output=50)
+        return answer
+```
+
+## Self-hosted
+
+```python
+oopstrace.init(
+    api_key="tr_...",
+    project_id="...",
+    endpoint="https://app.yourdomain.com",  # point at your own server
+)
+```

oopstrace-0.1.0/README.md

@@ -0,0 +1,65 @@
+# OopsTrace Python SDK
+
+LLM observability for Python. Trace every call, span, token count, and cost — visible instantly at [app.oopstrace.com](https://app.oopstrace.com).
+
+## Install
+
+```bash
+pip install oopstrace
+```
+
+## Quickstart
+
+```python
+import oopstrace
+
+oopstrace.init(
+    api_key="tr_...",       # from app.oopstrace.com → project → Access Keys
+    project_id="...",       # your project ID
+)
+
+@oopstrace.trace
+def run_agent(user_input: str) -> str:
+    with oopstrace.span("llm-call", span_kind="LLM") as s:
+        s.set_output("Hello from OopsTrace")
+        return "Hello from OopsTrace"
+
+run_agent("test")
+oopstrace.flush()
+```
+
+## Auto-instrument OpenAI / Anthropic
+
+```python
+oopstrace.init(api_key="tr_...", project_id="...", auto_instrument=True)
+
+# All openai.chat.completions.create() and anthropic.messages.create()
+# calls are now traced automatically — no decorators needed.
+```
+
+## Manual spans
+
+```python
+@oopstrace.trace
+def pipeline(query: str):
+    with oopstrace.span("retrieval", span_kind="TOOL") as s:
+        docs = retrieve(query)
+        s.set_input(query)
+        s.set_output(str(docs))
+
+    with oopstrace.span("generate", span_kind="LLM") as s:
+        answer = llm(query, docs)
+        s.set_model("gpt-4o")
+        s.set_tokens(input=100, output=50)
+        return answer
+```
+
+## Self-hosted
+
+```python
+oopstrace.init(
+    api_key="tr_...",
+    project_id="...",
+    endpoint="https://app.yourdomain.com",  # point at your own server
+)
+```

oopstrace-0.1.0/oopstrace/__init__.py

@@ -0,0 +1,21 @@
+from .client import (
+    OopstraceClient,
+    extract_context,
+    flush,
+    get_prompt,
+    init,
+    inject_headers,
+    span,
+    trace,
+)
+
+__all__ = [
+    "OopstraceClient",
+    "extract_context",
+    "flush",
+    "get_prompt",
+    "init",
+    "inject_headers",
+    "span",
+    "trace",
+]

oopstrace-0.1.0/oopstrace/client.py

@@ -0,0 +1,577 @@
+"""Oopstrace Python SDK — manual instrumentation with background batching.
+
+Usage:
+    import oopstrace
+
+    client = oopstrace.OopstraceClient(api_key="tr_...", project_id="my-project")
+
+    @client.trace
+    def my_agent(user_input: str) -> str:
+        with client.span("call-llm", span_kind="LLM"):
+            ...
+
+    # Or use module-level helpers after init:
+    oopstrace.init(api_key="tr_...", project_id="my-project")
+
+    @oopstrace.trace
+    def my_fn(): ...
+"""
+
+from __future__ import annotations
+
+import base64
+import contextlib
+import functools
+import inspect
+import json
+import logging
+import os
+import queue
+import threading
+import time
+import uuid
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any, Callable, Generator
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_ENDPOINT = "https://api.oopstrace.dev"
+_FLUSH_INTERVAL = 2.0  # seconds
+_MAX_BATCH = 100
+
+
+@dataclass
+class _SpanData:
+    span_id: str
+    trace_id: str
+    parent_span_id: str | None
+    name: str
+    span_kind: str
+    start_ns: int
+    end_ns: int | None = None
+    status: str = "OK"
+    status_message: str | None = None
+    input: str | None = None
+    output: str | None = None
+    metadata: dict | None = None
+    model_name: str | None = None
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    user_id: str | None = None
+    session_id: str | None = None
+    attributes: dict = field(default_factory=dict)
+
+
+@dataclass
+class _TraceContext:
+    trace_id: str
+    root_span_id: str
+    current_span_id: str
+    user_id: str | None = None
+    session_id: str | None = None
+
+
+_ctx_var: ContextVar[_TraceContext | None] = ContextVar("oopstrace_ctx", default=None)
+
+
+def _to_b64(hex_str: str) -> str:
+    return base64.b64encode(bytes.fromhex(hex_str)).decode()
+
+
+def _ns_to_str(ns: int) -> str:
+    return str(ns)
+
+
+def _build_span_otel(span: _SpanData, project_id: str) -> dict:
+    attrs: list[dict] = []
+
+    def _add(key: str, val: Any) -> None:
+        if val is None:
+            return
+        if isinstance(val, str):
+            attrs.append({"key": key, "value": {"stringValue": val}})
+        elif isinstance(val, bool):
+            attrs.append({"key": key, "value": {"boolValue": val}})
+        elif isinstance(val, int):
+            attrs.append({"key": key, "value": {"intValue": val}})
+        elif isinstance(val, float):
+            attrs.append({"key": key, "value": {"doubleValue": val}})
+
+    _add("oopstrace.span.type", span.span_kind)
+    if span.input is not None:
+        _add("oopstrace.span.input", span.input)
+    if span.output is not None:
+        _add("oopstrace.span.output", span.output)
+    if span.model_name:
+        _add("oopstrace.llm.model", span.model_name)
+    if span.input_tokens is not None:
+        _add("gen_ai.usage.input_tokens", span.input_tokens)
+    if span.output_tokens is not None:
+        _add("gen_ai.usage.output_tokens", span.output_tokens)
+    if span.user_id:
+        _add("user.id", span.user_id)
+    if span.session_id:
+        _add("session.id", span.session_id)
+    if span.metadata:
+        _add("oopstrace.span.metadata", json.dumps(span.metadata))
+    for k, v in span.attributes.items():
+        _add(k, v)
+
+    otel_span: dict = {
+        "traceId": _to_b64(span.trace_id),
+        "spanId": _to_b64(span.span_id),
+        "name": span.name,
+        "kind": "SPAN_KIND_INTERNAL",
+        "startTimeUnixNano": _ns_to_str(span.start_ns),
+        "endTimeUnixNano": _ns_to_str(span.end_ns or span.start_ns),
+        "attributes": attrs,
+        "status": {"code": "STATUS_CODE_ERROR" if span.status == "ERROR" else "STATUS_CODE_OK"},
+    }
+    if span.parent_span_id:
+        otel_span["parentSpanId"] = _to_b64(span.parent_span_id)
+    if span.status_message:
+        otel_span["status"]["message"] = span.status_message
+
+    return otel_span
+
+
+class _BatchExporter:
+    """Background daemon thread that drains a queue and ships batches every 2 s."""
+
+    def __init__(self, endpoint: str, api_key: str, project_id: str) -> None:
+        self._endpoint = endpoint.rstrip("/")
+        self._api_key = api_key
+        self._project_id = project_id
+        self._q: queue.Queue[_SpanData] = queue.Queue()
+        self._stop = threading.Event()
+        self._t = threading.Thread(target=self._run, daemon=True, name="oopstrace-exporter")
+        self._t.start()
+
+    def enqueue(self, span: _SpanData) -> None:
+        self._q.put_nowait(span)
+
+    def flush(self, timeout: float = 5.0) -> None:
+        """Drain queue and send synchronously. Blocks up to *timeout* seconds."""
+        deadline = time.monotonic() + timeout
+        pending: list[_SpanData] = []
+        while time.monotonic() < deadline:
+            try:
+                pending.append(self._q.get_nowait())
+            except queue.Empty:
+                break
+        if pending:
+            self._send(pending)
+
+    def shutdown(self) -> None:
+        self._stop.set()
+        self.flush()
+        self._t.join(timeout=3.0)
+
+    def _run(self) -> None:
+        while not self._stop.is_set():
+            time.sleep(_FLUSH_INTERVAL)
+            batch: list[_SpanData] = []
+            while len(batch) < _MAX_BATCH:
+                try:
+                    batch.append(self._q.get_nowait())
+                except queue.Empty:
+                    break
+            if batch:
+                self._send(batch)
+
+    def _send(self, spans: list[_SpanData]) -> None:
+        # Group spans by trace_id
+        by_trace: dict[str, list[_SpanData]] = {}
+        for s in spans:
+            by_trace.setdefault(s.trace_id, []).append(s)
+
+        scope_spans = [
+            {
+                "scope": {"name": "oopstrace-sdk", "version": "0.1.0"},
+                "spans": [_build_span_otel(s, self._project_id) for s in trace_spans],
+            }
+            for trace_spans in by_trace.values()
+        ]
+
+        payload = {
+            "resourceSpans": [
+                {
+                    "resource": {
+                        "attributes": [
+                            {"key": "service.name", "value": {"stringValue": self._project_id}}
+                        ]
+                    },
+                    "scopeSpans": scope_spans,
+                }
+            ]
+        }
+
+        try:
+            with httpx.Client(timeout=10.0) as client:
+                resp = client.post(
+                    f"{self._endpoint}/api/v1/public/traces",
+                    json=payload,
+                    headers={
+                        "Authorization": f"Bearer {self._api_key}",
+                        "Content-Type": "application/json",
+                    },
+                )
+            if resp.status_code >= 400:
+                logger.warning("Oopstrace export failed %s: %s", resp.status_code, resp.text[:200])
+        except Exception as exc:
+            logger.warning("Oopstrace export error: %s", exc)
+
+
+def _new_id(bytes_len: int = 16) -> str:
+    return uuid.uuid4().bytes[:bytes_len].hex()
+
+
+class OopstraceClient:
+    """Main SDK client. Create one instance per application."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        project_id: str | None = None,
+        endpoint: str | None = None,
+        enabled: bool = True,
+        auto_instrument: bool = False,
+    ) -> None:
+        self._api_key = api_key or os.environ.get("OOPSTRACE_API_KEY", "")
+        self._project_id = project_id or os.environ.get("OOPSTRACE_PROJECT_ID", "default")
+        self._endpoint = endpoint or os.environ.get("OOPSTRACE_ENDPOINT", _DEFAULT_ENDPOINT)
+        self._enabled = enabled and bool(self._api_key)
+        if self._enabled:
+            self._exporter = _BatchExporter(self._endpoint, self._api_key, self._project_id)
+        else:
+            self._exporter = None
+        if auto_instrument:
+            from oopstrace.patches import apply_all
+            apply_all(self)
+
+    # ------------------------------------------------------------------
+    # Context managers
+    # ------------------------------------------------------------------
+
+    @contextmanager
+    def start_trace(
+        self,
+        name: str,
+        *,
+        user_id: str | None = None,
+        session_id: str | None = None,
+        input: Any = None,
+        metadata: dict | None = None,
+        remote_context: dict | None = None,
+    ) -> Generator[_SpanData, None, None]:
+        """Open a root span that defines a new trace.
+
+        Pass *remote_context* (from :meth:`extract_context`) to continue a
+        distributed trace started by another agent process.  The local root
+        span will be inserted as a child of the remote span while sharing the
+        same ``trace_id``, so all agents appear in one unified causal graph.
+        """
+        if remote_context:
+            trace_id = remote_context["trace_id"]
+            parent_span_id: str | None = remote_context.get("parent_span_id")
+        else:
+            trace_id = _new_id(16)
+            parent_span_id = None
+
+        span_id = _new_id(8)
+        start_ns = time.time_ns()
+        ctx = _TraceContext(
+            trace_id=trace_id,
+            root_span_id=span_id,
+            current_span_id=span_id,
+            user_id=user_id,
+            session_id=session_id,
+        )
+        tok = _ctx_var.set(ctx)
+        span = _SpanData(
+            span_id=span_id,
+            trace_id=trace_id,
+            parent_span_id=parent_span_id,
+            name=name,
+            span_kind="SPAN",
+            start_ns=start_ns,
+            user_id=user_id,
+            session_id=session_id,
+            input=json.dumps(input) if input is not None and not isinstance(input, str) else input,
+            metadata=metadata,
+        )
+        try:
+            yield span
+        except Exception as exc:
+            span.status = "ERROR"
+            span.status_message = str(exc)
+            raise
+        finally:
+            span.end_ns = time.time_ns()
+            _ctx_var.reset(tok)
+            if self._exporter:
+                self._exporter.enqueue(span)
+
+    @contextmanager
+    def start_span(
+        self,
+        name: str,
+        *,
+        span_kind: str = "SPAN",
+        input: Any = None,
+        output: Any = None,
+        model_name: str | None = None,
+        input_tokens: int | None = None,
+        output_tokens: int | None = None,
+        metadata: dict | None = None,
+        attributes: dict | None = None,
+    ) -> Generator[_SpanData, None, None]:
+        """Open a child span within the current trace."""
+        ctx = _ctx_var.get()
+        if ctx is None:
+            # Auto-create a trace if called outside a trace context
+            with self.start_trace(name) as root_span:
+                yield root_span
+            return
+
+        span_id = _new_id(8)
+        parent_id = ctx.current_span_id
+        old_current = ctx.current_span_id
+        ctx.current_span_id = span_id
+        start_ns = time.time_ns()
+
+        def _enc(v: Any) -> str | None:
+            if v is None:
+                return None
+            return json.dumps(v) if not isinstance(v, str) else v
+
+        span = _SpanData(
+            span_id=span_id,
+            trace_id=ctx.trace_id,
+            parent_span_id=parent_id,
+            name=name,
+            span_kind=span_kind.upper(),
+            start_ns=start_ns,
+            input=_enc(input),
+            output=_enc(output),
+            model_name=model_name,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            metadata=metadata,
+            attributes=attributes or {},
+            user_id=ctx.user_id,
+            session_id=ctx.session_id,
+        )
+        try:
+            yield span
+        except Exception as exc:
+            span.status = "ERROR"
+            span.status_message = str(exc)
+            raise
+        finally:
+            span.end_ns = time.time_ns()
+            ctx.current_span_id = old_current
+            if self._exporter:
+                self._exporter.enqueue(span)
+
+    # ------------------------------------------------------------------
+    # Decorators
+    # ------------------------------------------------------------------
+
+    def trace(
+        self,
+        fn: Callable | None = None,
+        *,
+        name: str | None = None,
+        user_id: str | None = None,
+        session_id: str | None = None,
+    ):
+        """Decorator: wrap the function in a root trace span."""
+
+        def _decorator(f: Callable) -> Callable:
+            trace_name = name or f.__name__
+
+            @functools.wraps(f)
+            def _sync_wrapper(*args, **kwargs):
+                with self.start_trace(trace_name, user_id=user_id, session_id=session_id) as s:
+                    result = f(*args, **kwargs)
+                    if isinstance(result, str):
+                        s.output = result
+                    return result
+
+            @functools.wraps(f)
+            async def _async_wrapper(*args, **kwargs):
+                with self.start_trace(trace_name, user_id=user_id, session_id=session_id) as s:
+                    result = await f(*args, **kwargs)
+                    if isinstance(result, str):
+                        s.output = result
+                    return result
+
+            return _async_wrapper if inspect.iscoroutinefunction(f) else _sync_wrapper
+
+        return _decorator(fn) if fn is not None else _decorator
+
+    def span(
+        self,
+        fn: Callable | None = None,
+        *,
+        name: str | None = None,
+        span_kind: str = "SPAN",
+    ):
+        """Decorator: wrap the function in a child span."""
+
+        def _decorator(f: Callable) -> Callable:
+            span_name = name or f.__name__
+
+            @functools.wraps(f)
+            def _sync_wrapper(*args, **kwargs):
+                with self.start_span(span_name, span_kind=span_kind) as s:
+                    result = f(*args, **kwargs)
+                    if isinstance(result, str):
+                        s.output = result
+                    return result
+
+            @functools.wraps(f)
+            async def _async_wrapper(*args, **kwargs):
+                with self.start_span(span_name, span_kind=span_kind) as s:
+                    result = await f(*args, **kwargs)
+                    if isinstance(result, str):
+                        s.output = result
+                    return result
+
+            return _async_wrapper if inspect.iscoroutinefunction(f) else _sync_wrapper
+
+        return _decorator(fn) if fn is not None else _decorator
+
+    # ------------------------------------------------------------------
+    # Distributed trace propagation (W3C traceparent)
+    # ------------------------------------------------------------------
+
+    def inject_headers(self, headers: dict | None = None) -> dict:
+        """Inject W3C ``traceparent`` header into *headers* for an outgoing call.
+
+        Use this before making an HTTP request to another agent so the remote
+        process can link its spans into the same causal graph::
+
+            headers = client.inject_headers({"Content-Type": "application/json"})
+            httpx.post(agent_url, json=payload, headers=headers)
+        """
+        headers = dict(headers) if headers else {}
+        ctx = _ctx_var.get()
+        if ctx:
+            headers["traceparent"] = f"00-{ctx.trace_id}-{ctx.current_span_id}-01"
+        return headers
+
+    def extract_context(self, headers: dict) -> dict | None:
+        """Parse a W3C ``traceparent`` header from an incoming request.
+
+        Returns a ``remote_context`` dict ready to pass to :meth:`start_trace`,
+        or ``None`` if no valid header is present::
+
+            ctx = client.extract_context(request.headers)
+            with client.start_trace("AgentB", remote_context=ctx) as span:
+                ...
+        """
+        tp = headers.get("traceparent") or headers.get("Traceparent")
+        if not tp:
+            return None
+        parts = tp.split("-")
+        if len(parts) != 4:
+            return None
+        return {"trace_id": parts[1], "parent_span_id": parts[2]}
+
+    # ------------------------------------------------------------------
+    # Prompt management
+    # ------------------------------------------------------------------
+
+    def get_prompt(self, slug: str, version: int | None = None) -> str | None:
+        """Fetch a prompt template from the Prompt CMS."""
+        params = {} if version is None else {"version": version}
+        try:
+            with httpx.Client(timeout=5.0) as client:
+                resp = client.get(
+                    f"{self._endpoint}/api/v1/public/prompts/{slug}",
+                    params=params,
+                    headers={"Authorization": f"Bearer {self._api_key}"},
+                )
+            if resp.status_code == 200:
+                return resp.json().get("template")
+            if resp.status_code == 404:
+                return None
+        except Exception as exc:
+            logger.warning("Oopstrace get_prompt error: %s", exc)
+        return None
+
+    def flush(self, timeout: float = 5.0) -> None:
+        """Block until all pending spans are exported."""
+        if self._exporter:
+            self._exporter.flush(timeout=timeout)
+
+    def shutdown(self) -> None:
+        """Flush and stop the background exporter thread."""
+        if self._exporter:
+            self._exporter.shutdown()
+
+
+# ---------------------------------------------------------------------------
+# Module-level convenience API
+# ---------------------------------------------------------------------------
+
+_default_client: OopstraceClient | None = None
+
+
+def init(
+    api_key: str | None = None,
+    project_id: str | None = None,
+    endpoint: str | None = None,
+    auto_instrument: bool = False,
+) -> OopstraceClient:
+    """Initialize the module-level default client.
+
+    Set ``auto_instrument=True`` to automatically patch OpenAI and Anthropic
+    SDK calls — no decorators needed for basic LLM tracing.
+    """
+    global _default_client
+    _default_client = OopstraceClient(
+        api_key=api_key,
+        project_id=project_id,
+        endpoint=endpoint,
+        auto_instrument=auto_instrument,
+    )
+    return _default_client
+
+
+def _get_client() -> OopstraceClient:
+    global _default_client
+    if _default_client is None:
+        _default_client = OopstraceClient()
+    return _default_client
+
+
+def trace(fn: Callable | None = None, *, name: str | None = None, user_id: str | None = None, session_id: str | None = None):
+    return _get_client().trace(fn, name=name, user_id=user_id, session_id=session_id)
+
+
+def span(fn: Callable | None = None, *, name: str | None = None, span_kind: str = "SPAN"):
+    return _get_client().span(fn, name=name, span_kind=span_kind)
+
+
+def get_prompt(slug: str, version: int | None = None) -> str | None:
+    return _get_client().get_prompt(slug, version=version)
+
+
+def flush(timeout: float = 5.0) -> None:
+    _get_client().flush(timeout=timeout)
+
+
+def inject_headers(headers: dict | None = None) -> dict:
+    return _get_client().inject_headers(headers)
+
+
+def extract_context(headers: dict) -> dict | None:
+    return _get_client().extract_context(headers)

oopstrace-0.1.0/oopstrace/patches/__init__.py

@@ -0,0 +1,21 @@
+"""Monkey-patching registry for auto-instrumentation.
+
+Call apply_all(client) to patch every SDK that is installed.
+Individual patch functions are safe to call when the target library is absent.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from oopstrace.client import OopstraceClient
+
+
+def apply_all(client: "OopstraceClient") -> None:
+    """Apply all available patches against *client*."""
+    from oopstrace.patches._anthropic import patch_anthropic
+    from oopstrace.patches._openai import patch_openai
+
+    patch_openai(client)
+    patch_anthropic(client)

oopstrace-0.1.0/oopstrace/patches/_anthropic.py

@@ -0,0 +1,81 @@
+"""Auto-instrumentation patch for the anthropic SDK.
+
+Wraps `Messages.create` and `AsyncMessages.create` so that every Anthropic
+call is automatically captured as a child LLM span — no decorators required.
+
+The patch is idempotent: calling patch_anthropic() twice is safe.
+"""
+
+from __future__ import annotations
+
+import functools
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from oopstrace.client import OopstraceClient
+
+
+def _extract_last_user_text(messages: list[dict]) -> str:
+    """Pull the text content out of the last user message."""
+    for msg in reversed(messages):
+        if msg.get("role") == "user":
+            content = msg.get("content", "")
+            if isinstance(content, str):
+                return content
+            if isinstance(content, list):
+                for block in content:
+                    if isinstance(block, dict) and block.get("type") == "text":
+                        return block.get("text", "")
+    return ""
+
+
+def patch_anthropic(client: "OopstraceClient") -> None:
+    """Monkey-patch anthropic SDK classes to emit LLM spans automatically."""
+    try:
+        from anthropic.resources.messages import AsyncMessages, Messages
+    except ImportError:
+        return
+
+    if getattr(Messages, "_oopstrace_patched", False):
+        return
+
+    _orig_sync = Messages.create
+    _orig_async = AsyncMessages.create
+
+    @functools.wraps(_orig_sync)
+    def _sync_create(self_m, *args: Any, **kwargs: Any):
+        model = kwargs.get("model") or ""
+        messages = kwargs.get("messages") or []
+        inp = _extract_last_user_text(messages)
+
+        with client.start_span("anthropic.messages", span_kind="LLM", input=inp, model_name=model) as s:
+            result = _orig_sync(self_m, *args, **kwargs)
+            if hasattr(result, "usage") and result.usage:
+                s.input_tokens = result.usage.input_tokens
+                s.output_tokens = result.usage.output_tokens
+            if hasattr(result, "content") and result.content:
+                first = result.content[0]
+                if hasattr(first, "text"):
+                    s.output = first.text
+            return result
+
+    @functools.wraps(_orig_async)
+    async def _async_create(self_m, *args: Any, **kwargs: Any):
+        model = kwargs.get("model") or ""
+        messages = kwargs.get("messages") or []
+        inp = _extract_last_user_text(messages)
+
+        with client.start_span("anthropic.messages", span_kind="LLM", input=inp, model_name=model) as s:
+            result = await _orig_async(self_m, *args, **kwargs)
+            if hasattr(result, "usage") and result.usage:
+                s.input_tokens = result.usage.input_tokens
+                s.output_tokens = result.usage.output_tokens
+            if hasattr(result, "content") and result.content:
+                first = result.content[0]
+                if hasattr(first, "text"):
+                    s.output = first.text
+            return result
+
+    Messages.create = _sync_create
+    AsyncMessages.create = _async_create
+    Messages._oopstrace_patched = True

oopstrace-0.1.0/oopstrace/patches/_openai.py

@@ -0,0 +1,67 @@
+"""Auto-instrumentation patch for the openai SDK (>= 1.0).
+
+Wraps `Completions.create` and `AsyncCompletions.create` so that every chat
+call is automatically captured as a child LLM span — no decorators required.
+
+The patch is idempotent: calling patch_openai() twice is safe.
+"""
+
+from __future__ import annotations
+
+import functools
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from oopstrace.client import OopstraceClient
+
+
+def patch_openai(client: "OopstraceClient") -> None:
+    """Monkey-patch openai SDK classes to emit LLM spans automatically."""
+    try:
+        from openai.resources.chat.completions import AsyncCompletions, Completions
+    except ImportError:
+        return
+
+    if getattr(Completions, "_oopstrace_patched", False):
+        return
+
+    _orig_sync = Completions.create
+    _orig_async = AsyncCompletions.create
+
+    @functools.wraps(_orig_sync)
+    def _sync_create(self_c, *args: Any, **kwargs: Any):
+        model = kwargs.get("model") or ""
+        messages = kwargs.get("messages") or []
+        inp = (messages[-1].get("content") or "") if messages else ""
+
+        with client.start_span("openai.chat", span_kind="LLM", input=inp, model_name=model) as s:
+            result = _orig_sync(self_c, *args, **kwargs)
+            if hasattr(result, "usage") and result.usage:
+                s.input_tokens = result.usage.prompt_tokens
+                s.output_tokens = result.usage.completion_tokens
+            if hasattr(result, "choices") and result.choices:
+                content = result.choices[0].message.content
+                if content:
+                    s.output = content
+            return result
+
+    @functools.wraps(_orig_async)
+    async def _async_create(self_c, *args: Any, **kwargs: Any):
+        model = kwargs.get("model") or ""
+        messages = kwargs.get("messages") or []
+        inp = (messages[-1].get("content") or "") if messages else ""
+
+        with client.start_span("openai.chat", span_kind="LLM", input=inp, model_name=model) as s:
+            result = await _orig_async(self_c, *args, **kwargs)
+            if hasattr(result, "usage") and result.usage:
+                s.input_tokens = result.usage.prompt_tokens
+                s.output_tokens = result.usage.completion_tokens
+            if hasattr(result, "choices") and result.choices:
+                content = result.choices[0].message.content
+                if content:
+                    s.output = content
+            return result
+
+    Completions.create = _sync_create
+    AsyncCompletions.create = _async_create
+    Completions._oopstrace_patched = True

oopstrace-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "oopstrace"
+version = "0.1.0"
+description = "Oopstrace Python SDK — LLM observability with automatic batching"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+dependencies = [
+    "httpx>=0.24.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-asyncio"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["oopstrace"]