myobs 0.1.0__py3-none-any.whl

myobs/__init__.py

@@ -0,0 +1,37 @@
+"""
+myobs — provider-agnostic AI observability SDK (explicit / function-based).
+
+Quick start
+-----------
+    import myobs
+    myobs.init(api_key="sk_obs_...", endpoint="http://localhost:8000")
+
+    resp = openai_client.chat.completions.create(...)   # your call, your key
+    myobs.log_llm("openai", response=resp, latency_ms=812, user_id="usr_1")
+
+The SDK never wraps your client and never sees your provider API key. It only
+records what you explicitly hand it.
+"""
+from .client import (
+    init,
+    log_llm,
+    trace,
+    span,
+    observe,
+    flush,
+    shutdown,
+)
+from .schema import Usage
+from .version import __version__
+
+__all__ = [
+    "init",
+    "log_llm",
+    "trace",
+    "span",
+    "observe",
+    "flush",
+    "shutdown",
+    "Usage",
+    "__version__",
+]

myobs/adapters.py

@@ -0,0 +1,135 @@
+"""
+Provider adapters — the *only* place provider-specific knowledge lives.
+
+An adapter is a pure function: provider response object -> (Usage, model).
+It runs inside the customer process (they passed us the response object), so it
+never needs network access or credentials. Anything without an adapter still
+works: the caller passes `usage=` manually.
+"""
+from typing import Any, Optional, Tuple
+
+from .schema import Usage
+
+
+def _get(obj: Any, *names, default=None):
+    """Read a field whether obj is a dict or an attribute-style object."""
+    for name in names:
+        if obj is None:
+            return default
+        if isinstance(obj, dict):
+            if name in obj and obj[name] is not None:
+                return obj[name]
+        else:
+            val = getattr(obj, name, None)
+            if val is not None:
+                return val
+    return default
+
+
+def _int(v) -> int:
+    try:
+        return int(v)
+    except (TypeError, ValueError):
+        return 0
+
+
+# ── Per-provider extractors ────────────────────────────────────────────────
+
+def extract_openai(resp: Any) -> Tuple[Usage, Optional[str]]:
+    usage = _get(resp, "usage")
+    model = _get(resp, "model")
+    u = Usage(
+        # Chat Completions API
+        input_tokens=_int(_get(usage, "prompt_tokens", "input_tokens")),
+        output_tokens=_int(_get(usage, "completion_tokens", "output_tokens")),
+        total_tokens=_int(_get(usage, "total_tokens")),
+    )
+    # cached prompt tokens (prompt_tokens_details.cached_tokens)
+    details = _get(usage, "prompt_tokens_details")
+    if details:
+        u.cache_read_tokens = _int(_get(details, "cached_tokens"))
+    return u.finalize(), model
+
+
+def extract_anthropic(resp: Any) -> Tuple[Usage, Optional[str]]:
+    usage = _get(resp, "usage")
+    model = _get(resp, "model")
+    u = Usage(
+        input_tokens=_int(_get(usage, "input_tokens")),
+        output_tokens=_int(_get(usage, "output_tokens")),
+        cache_read_tokens=_int(_get(usage, "cache_read_input_tokens")),
+        cache_write_tokens=_int(_get(usage, "cache_creation_input_tokens")),
+    )
+    return u.finalize(), model
+
+
+def extract_gemini(resp: Any) -> Tuple[Usage, Optional[str]]:
+    meta = _get(resp, "usage_metadata", "usageMetadata")
+    model = _get(resp, "model", "model_version")
+    u = Usage(
+        input_tokens=_int(_get(meta, "prompt_token_count", "promptTokenCount")),
+        output_tokens=_int(_get(meta, "candidates_token_count", "candidatesTokenCount")),
+        total_tokens=_int(_get(meta, "total_token_count", "totalTokenCount")),
+        reasoning_tokens=_int(_get(meta, "thoughts_token_count", "thoughtsTokenCount")),
+    )
+    return u.finalize(), model
+
+
+def extract_bedrock(resp: Any) -> Tuple[Usage, Optional[str]]:
+    """AWS Bedrock Converse API response (dict). For streaming invoke_agent,
+    mine the trace stream yourself and pass usage= manually."""
+    usage = _get(resp, "usage")
+    u = Usage(
+        input_tokens=_int(_get(usage, "inputTokens", "input_tokens")),
+        output_tokens=_int(_get(usage, "outputTokens", "output_tokens")),
+        total_tokens=_int(_get(usage, "totalTokens", "total_tokens")),
+    )
+    return u.finalize(), _get(resp, "modelId", "model")
+
+
+def extract_cohere(resp: Any) -> Tuple[Usage, Optional[str]]:
+    meta = _get(resp, "meta")
+    billed = _get(meta, "billed_units", "tokens") if meta else None
+    u = Usage(
+        input_tokens=_int(_get(billed, "input_tokens", "input")),
+        output_tokens=_int(_get(billed, "output_tokens", "output")),
+    )
+    return u.finalize(), _get(resp, "model")
+
+
+def extract_generic(resp: Any) -> Tuple[Usage, Optional[str]]:
+    """Best-effort: a plain dict/object already using normalized-ish names."""
+    usage = _get(resp, "usage") or resp
+    u = Usage(
+        input_tokens=_int(_get(usage, "input_tokens", "inputTokens", "prompt_tokens")),
+        output_tokens=_int(_get(usage, "output_tokens", "outputTokens", "completion_tokens")),
+        total_tokens=_int(_get(usage, "total_tokens", "totalTokens")),
+    )
+    return u.finalize(), _get(resp, "model")
+
+
+REGISTRY = {
+    "openai": extract_openai,
+    "azure_openai": extract_openai,
+    "azure-openai": extract_openai,
+    "anthropic": extract_anthropic,
+    "google": extract_gemini,
+    "gemini": extract_gemini,
+    "vertexai": extract_gemini,
+    "bedrock": extract_bedrock,
+    "aws": extract_bedrock,
+    "cohere": extract_cohere,
+}
+
+
+def extract(provider: Optional[str], response: Any) -> Tuple[Usage, Optional[str]]:
+    """Resolve the adapter for `provider` and extract (Usage, model).
+    Unknown providers fall back to a best-effort generic extractor."""
+    if response is None:
+        return Usage(), None
+    fn = REGISTRY.get((provider or "").lower().strip(), extract_generic)
+    try:
+        return fn(response)
+    except Exception:
+        # Never let extraction break the caller — return empty usage.
+        return Usage(), None

myobs/client.py

@@ -0,0 +1,407 @@
+"""
+Core client + the public capture primitives (log_llm / trace / span / observe).
+
+This is the *explicit, function-based* integration (Design A): the customer
+makes their own model calls and hands us the result. We never wrap their client
+and never see their provider API key.
+"""
+import atexit
+import functools
+import inspect
+import logging
+import random
+import time
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from typing import Any, Callable, Optional
+
+from . import adapters, context, ids
+from .privacy import apply_privacy
+from .schema import Usage
+from .transport import Transport
+from .version import SDK_NAME, __version__
+
+log = logging.getLogger("myobs")
+
+_client: Optional["Client"] = None
+_warned = False
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _iso(dt: datetime) -> str:
+    return dt.isoformat()
+
+
+class Client:
+    def __init__(self, api_key=None, endpoint=None, environment="production",
+                 release=None, capture_content=True, redact=None,
+                 max_content_length=4000, sample_rate=1.0, flush_interval=2.0,
+                 max_batch_size=100, timeout=5.0, debug=False, enabled=True):
+        self.environment = environment
+        self.release = release
+        self.capture_content = capture_content
+        self.redact = redact
+        self.max_content_length = max_content_length
+        self.sample_rate = sample_rate
+        self.debug = debug
+        self.enabled = enabled
+        self.transport = Transport(
+            endpoint=endpoint, api_key=api_key, max_batch_size=max_batch_size,
+            flush_interval=flush_interval, timeout=timeout, debug=debug,
+        )
+
+    def enqueue(self, span: dict) -> None:
+        if not self.enabled:
+            return
+        if self.sample_rate < 1.0 and random.random() > self.sample_rate:
+            return
+        self.transport.submit(span)
+
+    def flush(self, timeout: float = 5.0) -> None:
+        self.transport.flush(timeout)
+
+    def shutdown(self, timeout: float = 5.0) -> None:
+        self.transport.shutdown(timeout)
+
+
+# ── module-level lifecycle ──────────────────────────────────────────────────
+
+def init(api_key: Optional[str] = None, endpoint: Optional[str] = None,
+         environment: str = "production", release: Optional[str] = None,
+         capture_content: bool = True, redact: Optional[Callable] = None,
+         max_content_length: int = 4000, sample_rate: float = 1.0,
+         flush_interval: float = 2.0, max_batch_size: int = 100,
+         timeout: float = 5.0, debug: bool = False) -> Client:
+    """Initialize the SDK once at startup. Reads MYOBS_API_KEY / MYOBS_ENDPOINT
+    from the environment if not passed explicitly."""
+    import os
+    global _client
+    api_key = api_key or os.getenv("MYOBS_API_KEY")
+    endpoint = endpoint or os.getenv("MYOBS_ENDPOINT")
+    _client = Client(
+        api_key=api_key, endpoint=endpoint, environment=environment, release=release,
+        capture_content=capture_content, redact=redact,
+        max_content_length=max_content_length, sample_rate=sample_rate,
+        flush_interval=flush_interval, max_batch_size=max_batch_size,
+        timeout=timeout, debug=debug,
+    )
+    atexit.register(_client.shutdown)
+    if debug:
+        log.setLevel(logging.INFO)
+        if not log.handlers:
+            log.addHandler(logging.StreamHandler())
+    return _client
+
+
+def _get_client() -> Optional[Client]:
+    global _warned
+    if _client is None and not _warned:
+        _warned = True
+        log.warning("myobs: init() was not called — capture is a no-op. Call myobs.init(...).")
+    return _client
+
+
+def flush(timeout: float = 5.0) -> None:
+    if _client:
+        _client.flush(timeout)
+
+
+def shutdown(timeout: float = 5.0) -> None:
+    if _client:
+        _client.shutdown(timeout)
+
+
+# ── span construction ───────────────────────────────────────────────────────
+
+def _build_span(*, span_id, trace_id, parent_span_id, name, type, provider,
+                model, operation, input, output, model_params, usage: Usage,
+                cost, status, error, latency_ms, start_time, end_time,
+                user_id, session_id, tags, metadata) -> dict:
+    c = _client
+    attrs = context.get_attrs()
+
+    def pick(explicit, key, fallback=None):
+        if explicit is not None:
+            return explicit
+        if key in attrs and attrs[key] is not None:
+            return attrs[key]
+        return fallback
+
+    merged_tags = dict(attrs.get("tags") or {})
+    if tags:
+        merged_tags.update(tags)
+    merged_meta = dict(attrs.get("metadata") or {})
+    if metadata:
+        merged_meta.update(metadata)
+
+    capture = c.capture_content if c else True
+    redact = c.redact if c else None
+    max_len = c.max_content_length if c else 4000
+
+    return {
+        "span_id": span_id,
+        "trace_id": trace_id,
+        "parent_span_id": parent_span_id,
+        "name": name,
+        "type": type,
+        "start_time": _iso(start_time),
+        "end_time": _iso(end_time),
+        "latency_ms": round(latency_ms, 2) if latency_ms is not None else None,
+        "provider": provider,
+        "model": model,
+        "operation": operation,
+        "input": apply_privacy(input, capture, redact, max_len),
+        "output": apply_privacy(output, capture, redact, max_len),
+        "model_params": model_params or None,
+        "usage": usage.to_dict(),
+        "cost": cost,  # cost is computed server-side; left null here
+        "status": status,
+        "error": error,
+        "user_id": pick(user_id, "user_id"),
+        "session_id": pick(session_id, "session_id"),
+        "environment": pick(None, "environment", c.environment if c else None),
+        "release": pick(None, "release", c.release if c else None),
+        "tags": merged_tags or None,
+        "metadata": merged_meta or None,
+        "sdk_name": SDK_NAME,
+        "sdk_version": __version__,
+    }
+
+
+def _resolve_usage(provider, response, usage) -> tuple:
+    """Combine adapter-extracted usage with any explicit usage/model override."""
+    u, model = adapters.extract(provider, response) if response is not None else (Usage(), None)
+    if usage:
+        if isinstance(usage, Usage):
+            u.merge(usage)
+        elif isinstance(usage, dict):
+            override = Usage(
+                input_tokens=int(usage.get("input_tokens", usage.get("inputTokens", 0)) or 0),
+                output_tokens=int(usage.get("output_tokens", usage.get("outputTokens", 0)) or 0),
+                total_tokens=int(usage.get("total_tokens", usage.get("totalTokens", 0)) or 0),
+                cache_read_tokens=int(usage.get("cache_read_tokens", 0) or 0),
+                cache_write_tokens=int(usage.get("cache_write_tokens", 0) or 0),
+                reasoning_tokens=int(usage.get("reasoning_tokens", 0) or 0),
+            )
+            u.merge(override)
+    return u.finalize(), model
+
+
+# ── public: one-shot log ─────────────────────────────────────────────────────
+
+def log_llm(provider: Optional[str] = None, *, response: Any = None,
+            model: Optional[str] = None, usage=None, input: Any = None,
+            output: Any = None, latency_ms: Optional[float] = None,
+            name: Optional[str] = None, type: str = "llm", operation: str = "chat",
+            status: str = "ok", error: Any = None, user_id: Optional[str] = None,
+            session_id: Optional[str] = None, tags: Optional[dict] = None,
+            metadata: Optional[dict] = None, model_params: Optional[dict] = None) -> None:
+    """Log a single completed LLM/agent call. Out-of-band: call it *after* your
+    own model call. Reads usage/model from `response` via the provider adapter,
+    or accepts them explicitly (works for any provider)."""
+    c = _get_client()
+    if c is None:
+        return
+    try:
+        u, adapter_model = _resolve_usage(provider, response, usage)
+        model = model or adapter_model
+        # If the response carries content and the caller didn't pass output, keep None
+        end = _now()
+        lat = latency_ms
+        start = end
+        if lat is not None:
+            start = datetime.fromtimestamp(end.timestamp() - lat / 1000.0, tz=timezone.utc)
+        span = _build_span(
+            span_id=ids.span_id(),
+            trace_id=context.current_trace_id.get() or ids.trace_id(),
+            parent_span_id=context.current_span_id.get(),
+            name=name or f"{provider or 'llm'}.{operation}", type=type,
+            provider=provider, model=model, operation=operation,
+            input=input, output=output, model_params=model_params, usage=u,
+            cost=None, status=status, error=_as_error(error), latency_ms=lat,
+            start_time=start, end_time=end, user_id=user_id, session_id=session_id,
+            tags=tags, metadata=metadata,
+        )
+        c.enqueue(span)
+    except Exception as exc:  # capture must never break the host app
+        if c.debug:
+            log.warning("myobs.log_llm failed: %s", exc)
+
+
+def _as_error(error) -> Optional[dict]:
+    if error is None:
+        return None
+    if isinstance(error, dict):
+        return error
+    if isinstance(error, BaseException):
+        return {"type": type(error).__name__, "message": str(error)}
+    return {"type": "Error", "message": str(error)}
+
+
+# ── public: trace context ────────────────────────────────────────────────────
+
+class TraceHandle:
+    def __init__(self, trace_id: str):
+        self.trace_id = trace_id
+
+    def update(self, **attrs) -> None:
+        cur = dict(context.current_attrs.get() or {})
+        cur.update({k: v for k, v in attrs.items() if v is not None})
+        context.current_attrs.set(cur)
+
+
+@contextmanager
+def trace(name: Optional[str] = None, *, user_id: Optional[str] = None,
+          session_id: Optional[str] = None, tags: Optional[dict] = None,
+          metadata: Optional[dict] = None, environment: Optional[str] = None,
+          release: Optional[str] = None):
+    """Group everything logged inside this block under one trace_id, sharing
+    user/session/tags. Spans and log_llm calls inside attach automatically."""
+    tid = ids.trace_id()
+    attrs = dict(context.current_attrs.get() or {})
+    for k, v in dict(trace_name=name, user_id=user_id, session_id=session_id,
+                     environment=environment, release=release).items():
+        if v is not None:
+            attrs[k] = v
+    if tags:
+        attrs["tags"] = {**(attrs.get("tags") or {}), **tags}
+    if metadata:
+        attrs["metadata"] = {**(attrs.get("metadata") or {}), **metadata}
+
+    t1 = context.current_trace_id.set(tid)
+    t2 = context.current_attrs.set(attrs)
+    try:
+        yield TraceHandle(tid)
+    finally:
+        context.current_trace_id.reset(t1)
+        context.current_attrs.reset(t2)
+
+
+# ── public: span context ─────────────────────────────────────────────────────
+
+class SpanHandle:
+    def __init__(self, name, type, operation):
+        self.name = name
+        self.type = type
+        self.operation = operation
+        self.provider = None
+        self.model = None
+        self.input = None
+        self.output = None
+        self.model_params = None
+        self.usage = Usage()
+        self.status = "ok"
+        self.error = None
+        self.tags = None
+        self.metadata = None
+        self.user_id = None
+        self.session_id = None
+        self._latency_override = None
+
+    def log(self, response: Any = None, *, provider: Optional[str] = None,
+            model: Optional[str] = None, usage=None, input: Any = None,
+            output: Any = None) -> "SpanHandle":
+        if provider:
+            self.provider = provider
+        u, adapter_model = _resolve_usage(provider or self.provider, response, usage)
+        self.usage.merge(u)
+        self.model = model or adapter_model or self.model
+        if input is not None:
+            self.input = input
+        if output is not None:
+            self.output = output
+        return self
+
+    def set_input(self, v): self.input = v; return self
+    def set_output(self, v): self.output = v; return self
+    def set_model(self, v): self.model = v; return self
+    def set_provider(self, v): self.provider = v; return self
+    def set_params(self, v): self.model_params = v; return self
+    def set_tags(self, v): self.tags = v; return self
+    def set_usage(self, **kw):
+        self.usage.merge(Usage(**kw)); return self
+    def set_error(self, err):
+        self.status = "error"; self.error = _as_error(err); return self
+    def set_latency_ms(self, ms): self._latency_override = ms; return self
+
+
+@contextmanager
+def span(name: str, *, type: str = "span", operation: str = "chat",
+         provider: Optional[str] = None, user_id: Optional[str] = None,
+         session_id: Optional[str] = None, tags: Optional[dict] = None):
+    """Time and record a unit of work (an LLM call, tool call, retrieval, ...).
+    Auto-creates a trace if there isn't one, and nests under any parent span."""
+    c = _get_client()
+    handle = SpanHandle(name, type, operation)
+    handle.provider = provider
+    handle.user_id = user_id
+    handle.session_id = session_id
+    handle.tags = tags
+
+    # Capture the enclosing span/trace *before* we push our own scope.
+    parent_span = context.current_span_id.get()
+    tid = context.current_trace_id.get() or ids.trace_id()
+    sid = ids.span_id()
+
+    t1 = context.current_trace_id.set(tid)
+    s1 = context.current_span_id.set(sid)
+
+    start = _now()
+    perf = time.perf_counter()
+    try:
+        yield handle
+    except Exception as exc:
+        handle.set_error(exc)
+        raise
+    finally:
+        end = _now()
+        lat = handle._latency_override
+        if lat is None:
+            lat = (time.perf_counter() - perf) * 1000.0
+        context.current_span_id.reset(s1)
+        context.current_trace_id.reset(t1)
+        if c is not None:
+            try:
+                c.enqueue(_build_span(
+                    span_id=sid, trace_id=tid, parent_span_id=parent_span,
+                    name=handle.name, type=handle.type, provider=handle.provider,
+                    model=handle.model, operation=handle.operation, input=handle.input,
+                    output=handle.output, model_params=handle.model_params,
+                    usage=handle.usage.finalize(), cost=None, status=handle.status,
+                    error=handle.error, latency_ms=lat, start_time=start, end_time=end,
+                    user_id=handle.user_id, session_id=handle.session_id,
+                    tags=handle.tags, metadata=handle.metadata,
+                ))
+            except Exception as exc:
+                if c.debug:
+                    log.warning("myobs.span failed: %s", exc)
+
+
+# ── public: decorator ────────────────────────────────────────────────────────
+
+def observe(name: Optional[str] = None, *, type: str = "agent",
+            user_id: Optional[str] = None, session_id: Optional[str] = None,
+            tags: Optional[dict] = None):
+    """Decorator that traces a whole function/agent run as a root span; any
+    log_llm / span calls inside attach to it automatically."""
+    def decorator(fn: Callable):
+        span_name = name or fn.__name__
+
+        if inspect.iscoroutinefunction(fn):
+            @functools.wraps(fn)
+            async def awrapper(*args, **kwargs):
+                with trace(name=span_name, user_id=user_id, session_id=session_id, tags=tags):
+                    with span(span_name, type=type):
+                        return await fn(*args, **kwargs)
+            return awrapper
+
+        @functools.wraps(fn)
+        def wrapper(*args, **kwargs):
+            with trace(name=span_name, user_id=user_id, session_id=session_id, tags=tags):
+                with span(span_name, type=type):
+                    return fn(*args, **kwargs)
+        return wrapper
+    return decorator

myobs/context.py

@@ -0,0 +1,25 @@
+"""
+Context propagation via contextvars.
+
+Lets nested spans discover their enclosing trace and parent span without the
+customer threading IDs through every function call. Because it's contextvars,
+it is correct under threads and asyncio tasks.
+"""
+import contextvars
+from typing import Optional, Dict, Any
+
+current_trace_id: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
+    "myobs_trace_id", default=None
+)
+current_span_id: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
+    "myobs_span_id", default=None
+)
+# Shared trace attributes (user_id, session_id, tags, metadata, environment,
+# release, trace_name) inherited by spans created inside a trace().
+current_attrs: contextvars.ContextVar[Dict[str, Any]] = contextvars.ContextVar(
+    "myobs_attrs", default={}
+)
+
+
+def get_attrs() -> Dict[str, Any]:
+    return dict(current_attrs.get() or {})

myobs/ids.py

@@ -0,0 +1,14 @@
+"""ID generation. Runs inside the customer process, so uuid/time are fine."""
+import uuid
+
+
+def new_id(prefix: str) -> str:
+    return f"{prefix}_{uuid.uuid4().hex}"
+
+
+def trace_id() -> str:
+    return new_id("t")
+
+
+def span_id() -> str:
+    return new_id("sp")

myobs/privacy.py

@@ -0,0 +1,63 @@
+"""
+Privacy / serialization helpers.
+
+All content leaves the customer process only after passing through here, so this
+is where redaction, truncation, and JSON-safety are enforced.
+"""
+from typing import Any, Callable, Optional
+
+_MAX_ITEMS = 200
+
+
+def to_jsonable(value: Any, max_str: int = 4000, _depth: int = 0) -> Any:
+    """Convert anything into a JSON-serializable structure, truncating long
+    strings and bounding depth/width so we never ship a huge or cyclic blob."""
+    if _depth > 6:
+        return "<max-depth>"
+    if value is None or isinstance(value, (bool, int, float)):
+        return value
+    if isinstance(value, str):
+        if max_str and len(value) > max_str:
+            return value[:max_str] + f"...<+{len(value) - max_str} chars>"
+        return value
+    if isinstance(value, dict):
+        out = {}
+        for i, (k, v) in enumerate(value.items()):
+            if i >= _MAX_ITEMS:
+                out["<truncated>"] = f"+{len(value) - _MAX_ITEMS} keys"
+                break
+            out[str(k)] = to_jsonable(v, max_str, _depth + 1)
+        return out
+    if isinstance(value, (list, tuple, set)):
+        seq = list(value)
+        out = [to_jsonable(v, max_str, _depth + 1) for v in seq[:_MAX_ITEMS]]
+        if len(seq) > _MAX_ITEMS:
+            out.append(f"<+{len(seq) - _MAX_ITEMS} items>")
+        return out
+    # Rich objects: pydantic models, SDK response objects, dataclasses, ...
+    for attr in ("model_dump", "dict", "to_dict"):
+        fn = getattr(value, attr, None)
+        if callable(fn):
+            try:
+                return to_jsonable(fn(), max_str, _depth + 1)
+            except Exception:
+                pass
+    if hasattr(value, "__dict__"):
+        try:
+            return to_jsonable(vars(value), max_str, _depth + 1)
+        except Exception:
+            pass
+    return to_jsonable(str(value), max_str, _depth + 1)
+
+
+def apply_privacy(value: Any, capture_content: bool,
+                  redact: Optional[Callable[[Any], Any]], max_str: int) -> Any:
+    """Gate a payload (input/output) through capture + redaction + truncation."""
+    if not capture_content or value is None:
+        return None
+    if redact is not None:
+        try:
+            value = redact(value)
+        except Exception:
+            pass
+    return to_jsonable(value, max_str)

myobs/schema.py

@@ -0,0 +1,49 @@
+"""
+Normalized schema primitives shared by the whole SDK.
+
+Everything the SDK captures reduces to a *span* (one unit of work) that groups
+under a *trace* (one end-to-end operation). Token field names are normalized
+here so every provider looks the same downstream.
+"""
+from dataclasses import dataclass, field
+
+SPAN_TYPES = ("llm", "embedding", "tool", "retrieval", "agent", "span")
+
+
+@dataclass
+class Usage:
+    input_tokens: int = 0
+    output_tokens: int = 0
+    total_tokens: int = 0
+    cache_read_tokens: int = 0
+    cache_write_tokens: int = 0
+    reasoning_tokens: int = 0
+    estimated: bool = False
+
+    def finalize(self) -> "Usage":
+        """Fill total_tokens if the provider didn't give one."""
+        if not self.total_tokens:
+            self.total_tokens = (self.input_tokens or 0) + (self.output_tokens or 0)
+        return self
+
+    def to_dict(self) -> dict:
+        return {
+            "input_tokens": int(self.input_tokens or 0),
+            "output_tokens": int(self.output_tokens or 0),
+            "total_tokens": int(self.total_tokens or 0),
+            "cache_read_tokens": int(self.cache_read_tokens or 0),
+            "cache_write_tokens": int(self.cache_write_tokens or 0),
+            "reasoning_tokens": int(self.reasoning_tokens or 0),
+            "estimated": bool(self.estimated),
+        }
+
+    def merge(self, other: "Usage") -> "Usage":
+        """Overlay non-zero fields from `other` onto self."""
+        for f in ("input_tokens", "output_tokens", "total_tokens",
+                  "cache_read_tokens", "cache_write_tokens", "reasoning_tokens"):
+            v = getattr(other, f)
+            if v:
+                setattr(self, f, v)
+        if other.estimated:
+            self.estimated = True
+        return self

myobs/transport.py

@@ -0,0 +1,112 @@
+"""
+Async, batched, non-blocking transport.
+
+Spans are handed to an in-process queue and flushed by a single background
+thread in batches (by size or interval). The caller never blocks on network I/O
+and an ingestion outage never raises into the host application.
+"""
+import logging
+import queue
+import threading
+import time
+from typing import List, Optional
+
+log = logging.getLogger("myobs")
+
+_STOP = object()
+
+
+class _Flush:
+    __slots__ = ("event",)
+
+    def __init__(self):
+        self.event = threading.Event()
+
+
+class Transport:
+    def __init__(self, endpoint: Optional[str], api_key: Optional[str],
+                 max_batch_size: int = 100, flush_interval: float = 2.0,
+                 timeout: float = 5.0, debug: bool = False, max_queue: int = 10000):
+        self.endpoint = (endpoint.rstrip("/") + "/v1/events") if endpoint else None
+        self.api_key = api_key
+        self.max_batch_size = max_batch_size
+        self.flush_interval = flush_interval
+        self.timeout = timeout
+        self.debug = debug
+        self._q: "queue.Queue" = queue.Queue(maxsize=max_queue)
+        self._dropped = 0
+        self._session = None
+        self._thread = threading.Thread(target=self._run, name="myobs-transport", daemon=True)
+        self._thread.start()
+
+    # ── public ──────────────────────────────────────────────────────────
+    def submit(self, span: dict) -> None:
+        try:
+            self._q.put_nowait(span)
+        except queue.Full:
+            self._dropped += 1
+            if self.debug:
+                log.warning("myobs: queue full, dropped span (total dropped=%d)", self._dropped)
+
+    def flush(self, timeout: float = 5.0) -> None:
+        marker = _Flush()
+        try:
+            self._q.put_nowait(marker)
+        except queue.Full:
+            return
+        marker.event.wait(timeout)
+
+    def shutdown(self, timeout: float = 5.0) -> None:
+        self.flush(timeout)
+        try:
+            self._q.put_nowait(_STOP)
+        except queue.Full:
+            pass
+        self._thread.join(timeout)
+
+    # ── worker ──────────────────────────────────────────────────────────
+    def _run(self) -> None:
+        buffer: List[dict] = []
+        while True:
+            timeout = self.flush_interval if buffer else None
+            try:
+                item = self._q.get(timeout=timeout)
+            except queue.Empty:
+                self._send(buffer); buffer = []
+                continue
+
+            if item is _STOP:
+                self._send(buffer); buffer = []
+                return
+            if isinstance(item, _Flush):
+                self._send(buffer); buffer = []
+                item.event.set()
+                continue
+
+            buffer.append(item)
+            if len(buffer) >= self.max_batch_size:
+                self._send(buffer); buffer = []
+
+    def _send(self, batch: List[dict]) -> None:
+        if not batch:
+            return
+        if not self.endpoint:
+            if self.debug:
+                for span in batch:
+                    log.info("myobs[debug] span: %s", span)
+            return
+        try:
+            import requests  # imported lazily so import myobs stays cheap
+            if self._session is None:
+                self._session = requests.Session()
+            headers = {"Content-Type": "application/json"}
+            if self.api_key:
+                headers["Authorization"] = f"Bearer {self.api_key}"
+            resp = self._session.post(
+                self.endpoint, json={"events": batch}, headers=headers, timeout=self.timeout
+            )
+            if resp.status_code >= 300 and self.debug:
+                log.warning("myobs: ingest returned %s: %s", resp.status_code, resp.text[:300])
+        except Exception as exc:  # network down, DNS, timeout — never propagate
+            if self.debug:
+                log.warning("myobs: failed to send %d span(s): %s", len(batch), exc)

myobs/version.py

@@ -0,0 +1,2 @@
+__version__ = "0.1.0"
+SDK_NAME = "myobs-python"

myobs-0.1.0.dist-info/METADATA

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: myobs
+Version: 0.1.0
+Summary: Provider-agnostic AI observability SDK — explicit / function-based capture (Design A)
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31
+Provides-Extra: examples
+Requires-Dist: openai>=1.0; extra == "examples"
+
+# myobs — AI Observability SDK (function / out-of-band)
+
+Provider-agnostic observability for LLM and agent apps. You make your own model
+calls with your own client and API key; you hand the **result** to `myobs`.
+The SDK is never in the request path and never touches your provider key.
+
+## Install (local dev)
+```bash
+pip install -e .
+```
+
+## Use
+```python
+import myobs, time
+myobs.init(api_key="sk_obs_local_demo", endpoint="http://localhost:8000")
+
+# (a) one-liner after any call
+t0 = time.time()
+resp = client.chat.completions.create(model="gpt-4o", messages=msgs)
+myobs.log_llm("openai", response=resp, latency_ms=(time.time()-t0)*1000,
+              user_id="usr_1", session_id="s_9", tags={"feature": "chat"})
+
+# (b) unknown provider — pass numbers yourself
+myobs.log_llm("my-llm", model="llama-3-70b",
+              usage={"input_tokens": 900, "output_tokens": 300}, latency_ms=740)
+
+# (c) multi-step agent — a trace with spans
+with myobs.trace(name="support-agent", user_id="usr_1", session_id="s_9"):
+    with myobs.span("plan", type="llm") as s:
+        r = client.chat.completions.create(...); s.log(r, provider="openai")
+    with myobs.span("search_kb", type="tool") as s:
+        s.set_output(search(q))
+
+# (d) decorator for a whole run
+@myobs.observe(name="support-agent")
+def run_agent(q, *, user_id, session_id): ...
+```
+
+## Guarantees
+- **Non-blocking:** spans go to an in-process queue, flushed by a background
+  thread in batches. Your call returns immediately.
+- **Never throws:** any SDK/network error is swallowed (enable `debug=True` to log).
+- **Private:** `capture_content=False`, a `redact=fn` hook, `max_content_length`,
+  and `sample_rate` all apply before data leaves your process.
+- Call `myobs.flush()` before a short-lived process exits (an `atexit` hook also
+  flushes automatically).
+
+## Config (`myobs.init`)
+| arg | default | meaning |
+|---|---|---|
+| `api_key` | `MYOBS_API_KEY` env | observability service key (NOT your LLM key) |
+| `endpoint` | `MYOBS_ENDPOINT` env | ingestion base URL |
+| `environment` | `"production"` | tag every span |
+| `capture_content` | `True` | store prompt/response text |
+| `redact` | `None` | `fn(value) -> value` scrubber |
+| `sample_rate` | `1.0` | fraction of spans to keep |
+| `debug` | `False` | log drops/errors to stderr |

myobs-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+myobs/__init__.py,sha256=MLM79IHjKdAqT0rApmZiYdehrUIAy9Grx3bGxcfEWzw,778
+myobs/adapters.py,sha256=0HiBxXRCMatgDR-fr576dlrOMeCfWEQKC9mnVqM0vgc,5034
+myobs/client.py,sha256=Sw5xSQ8vOaAjoRj92V84K6ChxAJKtnrIA8MmgDwW90w,16469
+myobs/context.py,sha256=DR1cQDKWuecH_Yoc23WWrFm3NSJYcyoUoZ1a35b3RWk,880
+myobs/ids.py,sha256=3sYKzdV8v3Jw2UgENmW5HDIQGcdYeBynRAQc19TMp_U,262
+myobs/privacy.py,sha256=CnIsqsg5BwRJgWNmyGNO3Kp0i3u7JpINKWBI0BuU560,2324
+myobs/schema.py,sha256=dogGqFkX1DD0kfmCav4BBJ1g6X8vO_3GL6XT5yDtnuI,1759
+myobs/transport.py,sha256=YmOQHcNwaJD2xcWrWrADTWzPCitMVt_8VboNxDvuX-8,4146
+myobs/version.py,sha256=1fmGyAvExsR_v92QDwCNsWqzjXMjs7DklKQmrsYkgCg,48
+myobs-0.1.0.dist-info/METADATA,sha256=xicnw-S43GC3Z-zOliuXAoM5W-ti3M45WsgC2v_DYBM,2700
+myobs-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+myobs-0.1.0.dist-info/top_level.txt,sha256=Uywnk7te6BMu-jWRMLT-8pO42AlWRTca9QJqy4AZG1k,6
+myobs-0.1.0.dist-info/RECORD,,

myobs-0.1.0.dist-info/WHEEL

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

myobs-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+myobs