eden-sdk 0.1.0__py3-none-any.whl

eden/__init__.py

@@ -0,0 +1,77 @@
+"""Eden — top-level import.
+
+This module is the canonical user-facing entry point. It re-exports
+the public API from :mod:`eden_sdk` so that ``import eden`` works
+the way the README and examples show.
+
+We keep the implementation in ``eden_sdk`` so the PyPI distribution
+name stays ``eden-sdk`` (which is unique) while the import path is
+the short, memorable ``eden`` (which is what users actually type).
+"""
+
+from __future__ import annotations
+
+from eden_sdk import (  # noqa: F401,F403
+    EdenClient,
+    EdenConfig,
+    Span,
+    TraceContext,
+    __version__,
+    configure,
+    current_span,
+    current_trace,
+    get_config,
+    get_default_client,
+    instrument,
+    reset_config,
+    trace,
+    trace_agent,
+    uninstrument,
+)
+from eden_sdk.filters import FilterConfig, PIIConfig  # noqa: F401
+from eden_sdk.gateway_session import chat_completion, openai_client  # noqa: F401
+from eden_sdk.model_advisor import (  # noqa: F401
+    ModelAdvisor,
+    ModelAdvisorError,
+    ModelComparison,
+    ModelSpec,
+    Recommendation,
+    RunnerUp,
+    SwitchProjection,
+)
+
+__all__ = [
+    # Configuration
+    "EdenConfig",
+    "configure",
+    "get_config",
+    "reset_config",
+    # Public client
+    "EdenClient",
+    "get_default_client",
+    # Tracing API
+    "trace",
+    "trace_agent",
+    "Span",
+    "TraceContext",
+    "current_span",
+    "current_trace",
+    # Auto-instrumentation
+    "instrument",
+    "uninstrument",
+    # Per-filter configuration for the gateway
+    "FilterConfig",
+    "PIIConfig",
+    # High-level gateway helpers (mirrors TypeScript SDK)
+    "openai_client",
+    "chat_completion",
+    # Model comparison + recommendation (mirrors TypeScript SDK)
+    "ModelAdvisor",
+    "ModelAdvisorError",
+    "ModelComparison",
+    "ModelSpec",
+    "Recommendation",
+    "RunnerUp",
+    "SwitchProjection",
+    "__version__",
+]

eden_sdk/__init__.py

@@ -0,0 +1,144 @@
+"""Eden Python Runtime SDK.
+
+A lightweight, fire-and-forget observability SDK for LLM applications.
+
+Highlights
+----------
+- ``@trace_agent`` decorator — trace any Python function (sync or async).
+- ``with eden.trace(...)`` — manual span context manager.
+- One-line auto-instrumentation for OpenAI, Anthropic, LangChain, LlamaIndex,
+  CrewAI, AutoGen, Mastra.
+- Async, batched, non-blocking HTTP sender (target p99 overhead ≤ 5 ms).
+- Zero required dependencies beyond ``httpx`` (the only required runtime dep).
+
+Example
+-------
+>>> import eden
+>>> eden.configure(org_id="org_123", api_key="sk-...")
+>>> eden.instrument()  # patches OpenAI, Anthropic, LangChain, etc.
+>>>
+>>> @eden.trace_agent(name="my-agent")
+... async def run(q: str) -> str:
+...     from openai import AsyncOpenAI
+...     client = AsyncOpenAI()
+...     resp = await client.chat.completions.create(
+...         model="gpt-4o-mini", messages=[{"role": "user", "content": q}]
+...     )
+...     return resp.choices[0].message.content
+"""
+
+from __future__ import annotations
+
+from eden_sdk.client import EdenClient, get_default_client
+from eden_sdk.config import EdenConfig, configure, get_config, reset_config
+from eden_sdk.filters import FilterConfig, PIIConfig
+from eden_sdk.gateway_session import chat_completion, openai_client
+from eden_sdk.model_advisor import (
+    ModelAdvisor,
+    ModelAdvisorError,
+    ModelComparison,
+    ModelSpec,
+    Recommendation,
+    RunnerUp,
+    SwitchProjection,
+)
+from eden_sdk.trace import (
+    Span,
+    TraceContext,
+    current_span,
+    current_trace,
+    trace,
+    trace_agent,
+)
+
+__all__ = [
+    # Configuration
+    "EdenConfig",
+    "configure",
+    "get_config",
+    "reset_config",
+    # Public client
+    "EdenClient",
+    "get_default_client",
+    # Tracing API
+    "trace",
+    "trace_agent",
+    "Span",
+    "TraceContext",
+    "current_span",
+    "current_trace",
+    # Auto-instrumentation
+    "instrument",
+    "uninstrument",
+    # Per-filter configuration for the gateway
+    "FilterConfig",
+    "PIIConfig",
+    # High-level gateway helpers
+    "openai_client",
+    "chat_completion",
+    # Model comparison + recommendation
+    "ModelAdvisor",
+    "ModelAdvisorError",
+    "ModelComparison",
+    "ModelSpec",
+    "Recommendation",
+    "RunnerUp",
+    "SwitchProjection",
+]
+
+__version__ = "0.1.0"
+
+
+# Lazy instrumentation registry — the per-framework modules are
+# imported on demand so the SDK works for users that only need a subset.
+INSTRUMENTED: set[str] = set()
+
+
+def instrument(*frameworks: str) -> None:
+    """Auto-instrument one or more LLM framework SDKs in place.
+
+    Parameters
+    ----------
+    *frameworks
+        Names of frameworks to instrument. Allowed values:
+        ``"openai"``, ``"anthropic"``, ``"langchain"``, ``"llama_index"``,
+        ``"crewai"``, ``"autogen"``, ``"mastra"``. If no name is given,
+        all currently-importable frameworks are instrumented.
+    """
+    from eden_sdk import instrumentations  # local import to avoid cycles
+
+    targets = frameworks or tuple(instrumentations.__all__)
+    for name in targets:
+        if name in INSTRUMENTED:
+            continue
+        module = getattr(instrumentations, name, None)
+        if module is None:
+            continue
+        try:
+            module.install()
+        except Exception as exc:  # noqa: BLE001
+            # Don't let a missing optional dep break the whole SDK.
+            import logging
+
+            logging.getLogger("eden_sdk").debug(
+                "instrumentation %s skipped: %s", name, exc
+            )
+            continue
+        INSTRUMENTED.add(name)
+
+
+def uninstrument(*frameworks: str) -> None:
+    """Reverse the patches applied by :func:`instrument`."""
+    from eden_sdk import instrumentations
+
+    targets = frameworks or tuple(INSTRUMENTED)
+    for name in targets:
+        if name not in INSTRUMENTED:
+            continue
+        module = getattr(instrumentations, name, None)
+        if module is not None:
+            try:
+                module.uninstall()
+            except Exception:  # noqa: BLE001
+                pass
+        INSTRUMENTED.discard(name)

eden_sdk/client.py

@@ -0,0 +1,478 @@
+"""Batched, async, fire-and-forget HTTP sender.
+
+The :class:`EdenClient` is the SDK's only network surface. Events from
+auto-instrumentation or the :func:`eden.trace` context manager are
+enqueued, then flushed either when the batch fills or when a timer
+fires. The hot path is *non-blocking*: callers never wait on the
+network — they just append to an in-memory queue and return.
+
+Threading
+---------
+- A single background thread runs the async event loop with an
+  ``httpx.AsyncClient`` connection pool.
+- Producer threads (the user's main code, callback handlers, etc.)
+  call :meth:`enqueue` which is just a ``queue.put_nowait`` plus
+  a ``threading.Event.set`` to wake the loop.
+- The loop pops events, builds a batch, and ``await``s the HTTP POST.
+- On a full queue (back-pressure) the oldest event is dropped with
+  a warning — the SDK must never block user code.
+
+Shutdown
+--------
+Call :func:`shutdown` (or use the SDK as a context manager via
+:func:`get_default_client` returning a singleton) to flush and stop
+the worker. ``atexit`` registers a best-effort flush.
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import logging
+import queue as _queue
+import threading
+import time
+from collections import deque
+from typing import Any
+
+import httpx
+
+from eden_sdk.config import EdenConfig, get_config
+
+logger = logging.getLogger("eden_sdk.client")
+
+
+# ── Public types ──────────────────────────────────────────────────────
+
+
+class TraceEvent:
+    """A single telemetry event ready for the wire.
+
+    The SDK only ships JSON-safe dicts — this is a thin convenience
+    wrapper that records the source format and the dict payload so
+    the sender can route to the right ingestion endpoint.
+    """
+
+    __slots__ = ("source_format", "payload")
+
+    def __init__(
+        self,
+        payload: dict[str, Any],
+        source_format: str = "openai",
+    ) -> None:
+        self.source_format = source_format
+        self.payload = payload
+
+    def to_json_bytes(self) -> bytes:
+        return json.dumps(self.payload, default=str).encode("utf-8")
+
+
+# ── Sender ────────────────────────────────────────────────────────────
+
+
+class EdenClient:
+    """Batched, async HTTP sender.
+
+    Most users never instantiate this directly — :func:`get_default_client`
+    returns a process-wide singleton. Tests can build their own
+    :class:`EdenClient` with a custom config.
+    """
+
+    # Per-batch endpoint format: we POST one event at a time, but the
+    # ingestion route also accepts a JSON array. The default decoder
+    # accepts both shapes. We use array form to halve the number of
+    # round-trips for bursts of activity.
+    _BATCH_AS_ARRAY = True
+
+    def __init__(
+        self,
+        config: EdenConfig | None = None,
+        *,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        """Build a sender.
+
+        Parameters
+        ----------
+        config
+            Runtime configuration. Defaults to the process-wide
+            config singleton.
+        transport
+            Optional httpx async transport to install on the
+            internal AsyncClient. Use this to inject a
+            MockTransport in tests or a custom transport in
+            production (e.g. for custom TLS / metrics).
+        """
+        self.config = config or get_config()
+        self._queue: _queue.Queue[TraceEvent] = _queue.Queue(
+            maxsize=self.config.max_queue
+        )
+        # Streaming chunks accumulate here and are flushed on the
+        # same worker tick (or via :meth:`flush_chunks`). Distinct
+        # from the regular queue because they go to ``/ingest/chunks``
+        # with a smaller payload shape.
+        self._chunk_buffer: list[dict[str, Any]] = []
+        self._chunk_wake = threading.Event()
+        self._chunk_generation = 0
+        self._chunk_processed_generation = 0
+        self._chunk_idle = threading.Event()
+        self._chunk_idle.set()
+        self._wake = threading.Event()
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._http: httpx.AsyncClient | None = None
+        # Transport precedence: explicit kwarg > config.transport > None.
+        # The config field is what :func:`configure` threads through
+        # the singleton, so users can set ``configure(transport=...)``
+        # to mock the gateway in tests.
+        cfg_transport = getattr(self.config, "transport", None)
+        self._transport: httpx.AsyncBaseTransport | None = (
+            transport if transport is not None else cfg_transport
+        )
+        self._loop_started = threading.Event()
+        self._dropped_total = 0
+        self._sent_total = 0
+        self._failed_total = 0
+        self._latency_window: deque[float] = deque(maxlen=1024)
+        # Generation counter: incremented at the end of each
+        # send_batch. ``flush()`` waits until the queue is empty
+        # AND the generation is stable for one tick — that way
+        # we know the in-flight HTTP has finished.
+        self._generation = 0
+        self._processed_generation = 0
+        self._generation_idle = threading.Event()
+        self._generation_idle.set()
+
+    # ── Lifecycle ────────────────────────────────────────────────────
+
+    def start(self) -> None:
+        """Start the background sender thread (idempotent)."""
+        if self._thread is not None and self._thread.is_alive():
+            return
+        if not self.config.enabled:
+            logger.debug("eden client disabled; not starting sender")
+            return
+        self._stop.clear()
+        self._thread = threading.Thread(
+            target=self._run_loop, name="eden-sdk-sender", daemon=True
+        )
+        self._thread.start()
+        # Wait until the loop has its asyncio loop ready so that
+        # shutdown() can join immediately.
+        self._loop_started.wait(timeout=1.0)
+
+    def shutdown(self, timeout: float = 5.0) -> None:
+        """Stop the sender, draining the queue first."""
+        if self._thread is None:
+            return
+        self._stop.set()
+        self._wake.set()
+        self._thread.join(timeout=timeout)
+        self._thread = None
+
+    # ── Producer API ─────────────────────────────────────────────────
+
+    def enqueue(self, event: TraceEvent) -> None:
+        """Non-blocking enqueue. Drops oldest on overflow.
+
+        Designed to be called from any thread — including the
+        framework callbacks running on the user's event loop.
+        """
+        if not self.config.enabled:
+            return
+        if self.config.dry_run:
+            self._sent_total += 1
+            logger.debug(
+                "eden[dry-run] fmt=%s keys=%s",
+                event.source_format,
+                sorted(event.payload.keys()),
+            )
+            return
+        try:
+            self._queue.put_nowait(event)
+        except _queue.Full:
+            # Drop the oldest to make room.
+            try:
+                self._queue.get_nowait()
+            except _queue.Empty:
+                pass
+            try:
+                self._queue.put_nowait(event)
+            except _queue.Full:
+                self._dropped_total += 1
+                logger.warning("eden sdk: queue full, dropped event")
+        self._wake.set()
+        # Wake the worker when a streaming chunk lands so it flushes
+        # without waiting for the full batch window. The producer
+        # pays only the ``Event.set`` cost.
+        if self._chunk_buffer:
+            self._chunk_wake.set()
+
+    def flush(self, timeout: float = 2.0) -> None:
+        """Block until the current queue + in-flight HTTP is drained.
+
+        Waits up to ``timeout`` seconds. Returns early as soon as
+        the queue is empty AND the in-flight batch completes. Used
+        by the test-suite and by the ``atexit`` hook for a clean
+        shutdown.
+        """
+        if not self.config.enabled:
+            return
+        # Force the worker to drain on the next loop tick.
+        self._wake.set()
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            if self._queue.empty() and self._processed_generation >= self._generation:
+                return
+            # Block on the idle event with a small timeout so we
+            # can re-check the queue state.
+            self._generation_idle.wait(timeout=0.01)
+            self._generation_idle.clear()
+
+    # ── Internal loop ────────────────────────────────────────────────
+
+    def _run_loop(self) -> None:
+        import asyncio
+
+        asyncio.run(self._async_loop())
+
+    async def _async_loop(self) -> None:
+
+        self._http = httpx.AsyncClient(
+            timeout=httpx.Timeout(self.config.timeout_s),
+            limits=httpx.Limits(
+                max_connections=16, max_keepalive_connections=8
+            ),
+            transport=self._transport,
+        )
+        self._loop_started.set()
+        flush_interval = self.config.flush_interval_ms / 1000.0
+        try:
+            while not self._stop.is_set():
+                # Wait for the next event or the flush interval.
+                self._wake.wait(timeout=flush_interval)
+                self._wake.clear()
+                if self._stop.is_set() and self._queue.empty():
+                    break
+                batch = self._drain(self.config.batch_size)
+                if batch:
+                    self._generation += 1
+                    try:
+                        await self._send_batch(batch)
+                    finally:
+                        self._processed_generation = self._generation
+                        self._generation_idle.set()
+                else:
+                    # Queue is empty: tell flush() it can return.
+                    self._generation_idle.set()
+                # Drain streaming chunks on the same loop tick.
+                if self._chunk_buffer:
+                    self._chunk_generation += 1
+                    try:
+                        await self._send_chunks()
+                    finally:
+                        self._chunk_processed_generation = self._chunk_generation
+                        self._chunk_idle.set()
+                else:
+                    self._chunk_idle.set()
+        finally:
+            # Final drain on shutdown.
+            tail = self._drain(self.config.batch_size)
+            if tail:
+                self._generation += 1
+                await self._send_batch(tail)
+                self._processed_generation = self._generation
+            if self._chunk_buffer:
+                self._chunk_generation += 1
+                await self._send_chunks()
+                self._chunk_processed_generation = self._chunk_generation
+            self._generation_idle.set()
+            self._chunk_idle.set()
+            if self._http is not None:
+                await self._http.aclose()
+                self._http = None
+
+    def _drain(self, max_items: int) -> list[TraceEvent]:
+        items: list[TraceEvent] = []
+        for _ in range(max_items):
+            try:
+                items.append(self._queue.get_nowait())
+            except _queue.Empty:
+                break
+        return items
+
+    def flush_chunks(self, timeout: float = 2.0) -> None:
+        """Block until buffered streaming chunks are flushed.
+
+        Mirrors :meth:`flush` but for the streaming chunks buffer.
+        No-op when there are no buffered chunks.
+        """
+        if not self.config.enabled:
+            return
+        self._chunk_wake.set()
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            if (
+                not self._chunk_buffer
+                and self._chunk_processed_generation >= self._chunk_generation
+            ):
+                return
+            self._chunk_idle.wait(timeout=0.01)
+            self._chunk_idle.clear()
+
+    def ingest_chunks_url(self) -> str | None:
+        """Return the canonical streaming chunks URL, or ``None`` when
+        the org id is not configured."""
+        if not self.config.org_id:
+            return None
+        base = self.config.base_url.rstrip("/")
+        return f"{base}/orgs/{self.config.org_id}/ingest/chunks"
+
+    async def _send_chunks(self) -> None:
+        """POST buffered streaming chunks to ``/ingest/chunks``.
+
+        Best-effort: a transport failure logs a warning and counts
+        the chunks as failed, but does not raise (the user's stream
+        already returned to them).
+        """
+        assert self._http is not None
+        if not self._chunk_buffer:
+            return
+        url = self.ingest_chunks_url()
+        if url is None:
+            # No org id — drop silently.
+            self._chunk_buffer.clear()
+            return
+        chunks = self._chunk_buffer
+        self._chunk_buffer = []
+        try:
+            body = json.dumps({"chunks": chunks}, default=str).encode("utf-8")
+            headers = self.config.auth_headers()
+            headers.setdefault("Content-Type", "application/json")
+            t0 = time.perf_counter()
+            resp = await self._http.post(url, content=body, headers=headers)
+            dt = (time.perf_counter() - t0) * 1000.0
+            self._latency_window.append(dt)
+            if 200 <= resp.status_code < 300:
+                self._sent_total += len(chunks)
+            else:
+                self._failed_total += len(chunks)
+                logger.warning(
+                    "eden ingest chunks returned %s: %s",
+                    resp.status_code,
+                    resp.text[:200],
+                )
+        except Exception as exc:  # noqa: BLE001
+            self._failed_total += len(chunks)
+            logger.warning("eden ingest chunks failed: %s", exc)
+
+    async def _send_batch(self, batch: list[TraceEvent]) -> None:
+        assert self._http is not None
+        # Group by source_format so each ingestion route gets its
+        # own request. Routes are 1:1 with decoder names.
+        groups: dict[str, list[dict[str, Any]]] = {}
+        for ev in batch:
+            groups.setdefault(ev.source_format, []).append(ev.payload)
+        for source_format, payloads in groups.items():
+            try:
+                url = self.config.ingest_url(source_format)
+                headers = self.config.auth_headers()
+                headers.setdefault("Content-Type", "application/json")
+                if self._BATCH_AS_ARRAY:
+                    body = json.dumps(payloads, default=str).encode("utf-8")
+                    count = len(payloads)
+                else:
+                    body = json.dumps(payloads[0], default=str).encode("utf-8")
+                    # Single-event mode: we send one event per request,
+                    # so each request only counts one event regardless of
+                    # the size of the drained batch.
+                    count = 1
+                t0 = time.perf_counter()
+                resp = await self._http.post(
+                    url, content=body, headers=headers
+                )
+                dt = (time.perf_counter() - t0) * 1000.0
+                self._latency_window.append(dt)
+                # 2xx = accepted; 4xx = rejected by the server (auth,
+                # validation) and should be counted as failed so operators
+                # notice a misconfigured org_id / api_key. 5xx is a
+                # server error; either way the event did not land.
+                if 200 <= resp.status_code < 300:
+                    self._sent_total += count
+                else:
+                    self._failed_total += count
+                    logger.warning(
+                        "eden ingest %s returned %s: %s",
+                        source_format,
+                        resp.status_code,
+                        resp.text[:200],
+                    )
+            except Exception as exc:  # noqa: BLE001
+                self._failed_total += count
+                logger.warning("eden ingest %s failed: %s", source_format, exc)
+
+    # ── Stats / introspection ─────────────────────────────────────────
+
+    @property
+    def sent(self) -> int:
+        return self._sent_total
+
+    @property
+    def dropped(self) -> int:
+        return self._dropped_total
+
+    @property
+    def failed(self) -> int:
+        return self._failed_total
+
+    def p99_latency_ms(self) -> float:
+        """99th percentile of recent send latencies in milliseconds."""
+        if not self._latency_window:
+            return 0.0
+        ordered = sorted(self._latency_window)
+        idx = max(0, int(round(0.99 * (len(ordered) - 1))))
+        return ordered[idx]
+
+
+# ── Singleton ────────────────────────────────────────────────────────
+
+_lock = threading.Lock()
+_default: EdenClient | None = None
+_atexit_registered = False
+
+
+def get_default_client() -> EdenClient:
+    """Return the process-wide :class:`EdenClient` singleton.
+
+    The first call also starts the sender thread and registers an
+    :mod:`atexit` hook for a best-effort final flush.
+    """
+    global _default, _atexit_registered
+    with _lock:
+        if _default is None:
+            _default = EdenClient()
+            _default.start()
+            if not _atexit_registered:
+                atexit.register(_atexit_shutdown)
+                _atexit_registered = True
+    return _default
+
+
+def _atexit_shutdown() -> None:
+    global _default
+    if _default is None:
+        return
+    try:
+        _default.flush(timeout=2.0)
+    finally:
+        _default.shutdown(timeout=2.0)
+        _default = None
+
+
+def reset_default_client() -> None:
+    """Test helper: drop the singleton (synchronously)."""
+    global _default
+    with _lock:
+        if _default is not None:
+            _default.shutdown(timeout=2.0)
+            _default = None