orbitrage 0.2.0__py3-none-any.whl

orbitrage/__init__.py

@@ -0,0 +1,31 @@
+"""orbitrage — one-line observability + intelligent routing for Python agents.
+
+Usage:
+    import orbitrage
+    orbitrage.init("orb_xxx_yyy")
+"""
+from __future__ import annotations
+
+from ._client import (
+    init,
+    flush,
+    shutdown,
+    workflow,
+    task,
+    tool,
+    agent,
+    set_association_properties,
+)
+
+__all__ = [
+    "init",
+    "flush",
+    "shutdown",
+    "workflow",
+    "task",
+    "tool",
+    "agent",
+    "set_association_properties",
+]
+
+__version__ = "0.2.0"

orbitrage/_client.py

@@ -0,0 +1,391 @@
+"""orbitrage client. Thin wrapper over Traceloop / OpenLLMetry with
+hot-path-safe defaults so users pay close to zero overhead per LLM call.
+
+Design goals:
+  - **One-line init**: `orbitrage.init("orb_xxx")` — no other config needed.
+  - **Zero blocking on the hot path**: spans are queued to a daemon-thread
+    BatchSpanProcessor; OTLP exports never run inline with the user's call.
+  - **Fail-open**: if the Orbitrage backend is unreachable, the user's
+    workflow MUST still succeed. Export errors are swallowed silently.
+  - **No surprises**: never call `os._exit`, never install global hooks
+    that the user didn't ask for, never print to stdout on success.
+
+What we override vs. raw Traceloop:
+  - `disable_batch=False` — Traceloop's default is fine, but raw users
+    sometimes pass `disable_batch=True` (the docs show it), which makes
+    every span export a synchronous HTTPS POST. We force-disable that.
+  - Aggressive BatchSpanProcessor tuning via env vars for snappier flush.
+  - Default endpoint -> orbitrage.xyz, default headers from the api_key,
+    and a metadata-collector function so we don't have to ask the user
+    for app_name / workflow_id.
+  - `traceloop_sync_enabled=False` — we don't talk to Traceloop's prompt
+    sync API ever; users get prompts via Orbitrage's own /v1/prompts.
+"""
+from __future__ import annotations
+
+import atexit
+import logging
+import os
+import re
+import sys
+from typing import Any, Callable, Optional, Set
+
+logger = logging.getLogger("orbitrage")
+
+# Lazy imports — keep `import orbitrage` itself sub-millisecond.
+_initialized = False
+_client = None
+_tracer_wrapper = None
+
+
+# ── public env config ─────────────────────────────────────────────────────
+# Endpoint defaults to production. Override via ORBITRAGE_ENDPOINT for
+# self-hosted / staging tests.
+_DEFAULT_ENDPOINT = "https://orbitrage.xyz/api/telemetry"
+
+
+# Map import names → Traceloop Instruments enum value names. Detection looks
+# at sys.modules first, then falls back to importlib.util.find_spec for
+# packages that are installed but not yet imported. Keeping this list tight:
+# only LLM / agent libraries — vector DBs / loggers / generic HTTP are opt-in.
+_AUTO_INSTRUMENT_MAP: list[tuple[tuple[str, ...], str]] = [
+    (("openai",),                                        "OPENAI"),
+    (("anthropic",),                                     "ANTHROPIC"),
+    (("langchain", "langchain_core", "langchain_openai",
+      "langchain_anthropic"),                            "LANGCHAIN"),
+    (("llama_index", "llama_index.core"),                "LLAMA_INDEX"),
+    (("cohere",),                                        "COHERE"),
+    (("groq",),                                          "GROQ"),
+    (("mistralai",),                                     "MISTRAL"),
+    (("google.generativeai", "google_generativeai"),     "GOOGLE_GENERATIVEAI"),
+    (("ollama",),                                        "OLLAMA"),
+    (("together",),                                      "TOGETHER"),
+    (("replicate",),                                     "REPLICATE"),
+    (("crewai",),                                        "CREWAI"),
+    (("haystack",),                                      "HAYSTACK"),
+    (("agno",),                                          "AGNO"),
+    (("openai_agents",),                                 "OPENAI_AGENTS"),
+    (("mcp",),                                           "MCP"),
+]
+
+
+def _autodetect_instruments() -> Optional[set]:
+    """Return the Instruments set Traceloop should load.
+
+    Strategy — only enable instruments for libraries the user is actually
+    using (sys.modules), PLUS the two raw LLM clients (openai, anthropic)
+    even if not yet imported. This handles the common pattern where
+    `orbitrage.init()` is called at the very top of the file BEFORE the
+    LLM client import — we still want the openai call to be traced.
+
+    We deliberately exclude heavy/fragile instrumentors (langchain,
+    llama_index, transformers) from the always-on set: their
+    instrumentation typically wraps the underlying openai/anthropic
+    client anyway, so the raw-client instrumentor catches the same span.
+
+    Returns None if Traceloop isn't importable (caller will skip init).
+    """
+    try:
+        from traceloop.sdk.instruments import Instruments
+    except Exception:
+        return None
+    out = set()
+    # Always-on raw LLM clients — safe, fast, near-zero startup cost.
+    for enum_name in ("OPENAI", "ANTHROPIC"):
+        v = getattr(Instruments, enum_name, None)
+        if v is not None:
+            out.add(v)
+    # Modules already imported by the user — definitely in use.
+    for modules, enum_name in _AUTO_INSTRUMENT_MAP:
+        if any(m in sys.modules for m in modules):
+            v = getattr(Instruments, enum_name, None)
+            if v is not None:
+                out.add(v)
+    return out
+
+
+def _resolve_endpoint(explicit: Optional[str]) -> str:
+    """Resolve endpoint. Order: explicit arg > env var > default."""
+    return (
+        explicit
+        or os.environ.get("ORBITRAGE_ENDPOINT")
+        or os.environ.get("TRACELOOP_BASE_URL")  # for migrators
+        or _DEFAULT_ENDPOINT
+    )
+
+
+def _resolve_api_key(explicit: Optional[str]) -> Optional[str]:
+    return (
+        explicit
+        or os.environ.get("ORBITRAGE_API_KEY")
+        or os.environ.get("TRACELOOP_API_KEY")
+    )
+
+
+def _silence_otel_exporter_noise() -> None:
+    """Stop OTel from printing 'Failed to export span batch ...' on every retry.
+
+    Export failures (auth, quota, network) are recoverable: the BSP keeps
+    spans in its in-memory queue and retries on the next interval. Users
+    shouldn't see scary stack traces in their normal console output —
+    that's the equivalent of Sentry printing red errors every time the
+    Sentry backend is down. Errors are still logged at DEBUG level so
+    operators can opt in with ORBITRAGE_DEBUG=1.
+    """
+    level = logging.WARNING if os.environ.get("ORBITRAGE_DEBUG") else logging.CRITICAL
+    for name in (
+        "opentelemetry.exporter.otlp.proto.http.trace_exporter",
+        "opentelemetry.exporter.otlp.proto.http._log_exporter",
+        "opentelemetry.exporter.otlp.proto.http.metric_exporter",
+        "opentelemetry.sdk.trace.export",
+    ):
+        logging.getLogger(name).setLevel(level)
+
+
+def _set_bsp_env_defaults() -> None:
+    """Tune OTel's BatchSpanProcessor for low-latency export.
+
+    Env vars are read by BatchSpanProcessor at instantiation time. We only
+    set them if the user didn't already — never override their intent.
+
+    - SCHEDULE_DELAY=500ms: flush twice per second instead of every 5s, so
+      short-lived scripts get data flushed without leaning on shutdown.
+    - MAX_QUEUE_SIZE=4096: roomy enough for chatty agents (each LLM call
+      can emit a dozen spans across http, langchain, openai, tool levels).
+    - MAX_EXPORT_BATCH_SIZE=512: bigger batches = fewer HTTP RTTs.
+    """
+    defaults = {
+        "OTEL_BSP_SCHEDULE_DELAY": "500",
+        "OTEL_BSP_MAX_QUEUE_SIZE": "4096",
+        "OTEL_BSP_MAX_EXPORT_BATCH_SIZE": "512",
+        "OTEL_BSP_EXPORT_TIMEOUT": "10000",
+    }
+    for k, v in defaults.items():
+        os.environ.setdefault(k, v)
+
+
+_API_KEY_RE = re.compile(r"^orb_[A-Za-z0-9_\-]{10,200}$")
+
+
+# ── init ──────────────────────────────────────────────────────────────────
+def init(
+    api_key: Optional[str] = None,
+    *,
+    app_name: Optional[str] = None,
+    endpoint: Optional[str] = None,
+    enabled: bool = True,
+    disable_batch: bool = False,
+    capture_content: bool = True,
+    instruments: Optional[Set[Any]] = None,
+    block_instruments: Optional[Set[Any]] = None,
+    resource_attributes: Optional[dict] = None,
+    flush_on_exit: bool = True,
+    quiet: bool = False,
+) -> Any:
+    """Initialize Orbitrage observability. Call once at program startup.
+
+    Args:
+        api_key: Your Orbitrage API key (orb_xxx_yyy). Falls back to
+                 ORBITRAGE_API_KEY env var.
+        app_name: Project / workflow name (groups spans in the dashboard).
+                 Defaults to your script name.
+        endpoint: Override the telemetry endpoint. Almost never needed.
+        enabled: Set False to no-op the SDK (tests, CI).
+        disable_batch: We force-warn on this — synchronous OTLP export adds
+                 ~800ms per span. Don't use it outside Jupyter.
+        capture_content: When True (default), prompt + completion text is
+                 exported on every span so they render in the Orbitrage
+                 flow graph. Set False to redact content for compliance
+                 (token counts + cost + routing are still captured).
+        flush_on_exit: Register an atexit hook that flushes spans before
+                 process exit. Default True — turn off only if you manage
+                 the flush yourself.
+        quiet: Suppress the one-line "telemetry on" log.
+
+    Returns:
+        The underlying Traceloop client (or None if disabled).
+    """
+    global _initialized, _client, _tracer_wrapper
+
+    if _initialized:
+        return _client
+
+    api_key = _resolve_api_key(api_key)
+    if not enabled:
+        if not quiet:
+            logger.info("orbitrage disabled")
+        _initialized = True
+        return None
+
+    if not api_key:
+        # Soft-fail rather than raising: same philosophy as Sentry. The
+        # user's app should not crash because telemetry was misconfigured.
+        if not quiet:
+            sys.stderr.write(
+                "orbitrage: no API key provided — telemetry off. "
+                "Set ORBITRAGE_API_KEY or call orbitrage.init('orb_...').\n"
+            )
+        _initialized = True
+        return None
+
+    # Cheap shape check — rejects typos that could exfiltrate prompts to a
+    # wrong endpoint. Matches the live key format (orb_<prefix>_<secret>).
+    if not _API_KEY_RE.match(api_key):
+        sys.stderr.write(
+            "orbitrage: API key format invalid (expected `orb_<prefix>_<secret>`) "
+            "— telemetry off.\n"
+        )
+        _initialized = True
+        return None
+
+    # Force batch mode — this is the single biggest perf win. If a user
+    # explicitly asks for disable_batch=True we'll honor it after warning.
+    if disable_batch:
+        sys.stderr.write(
+            "orbitrage: disable_batch=True forces synchronous OTLP export "
+            "(adds ~100-200ms per span). Strongly consider leaving it False.\n"
+        )
+
+    _set_bsp_env_defaults()
+    _silence_otel_exporter_noise()
+
+    # Privacy-first content default. Traceloop's own default is "true" —
+    # meaning every prompt + completion would be POSTed to the OTLP endpoint.
+    # We require an explicit opt-in via `capture_content=True`. The env var
+    # is the toggle Traceloop's instrumentors read at span time.
+    if capture_content:
+        os.environ["TRACELOOP_TRACE_CONTENT"] = "true"
+    else:
+        # setdefault so a deliberately-set "true" via env still works.
+        os.environ.setdefault("TRACELOOP_TRACE_CONTENT", "false")
+
+    # Resolve endpoint and app name.
+    endpoint = _resolve_endpoint(endpoint)
+    app_name = app_name or os.environ.get("ORBITRAGE_APP_NAME") or _default_app_name()
+
+    # Lazy import: importing traceloop ~150 ms on cold disk. We pay that once
+    # but only when init is actually called.
+    from traceloop.sdk import Traceloop
+
+    # Auto-detect instruments unless the caller pinned a set explicitly.
+    # Cuts init from ~2.6s (all 30+ instrumentors) to ~0.9s on a typical
+    # openai-only app, because Traceloop only imports what's installed.
+    if instruments is None:
+        instruments = _autodetect_instruments()
+
+    try:
+        client = Traceloop.init(
+            app_name=app_name,
+            api_endpoint=endpoint,
+            api_key=api_key,
+            disable_batch=disable_batch,
+            telemetry_enabled=False,  # don't phone home to traceloop.com
+            traceloop_sync_enabled=False,
+            instruments=instruments,
+            block_instruments=block_instruments,
+            resource_attributes=resource_attributes or {},
+        )
+    except Exception as e:
+        sys.stderr.write(f"orbitrage: init failed ({e}) — telemetry off.\n")
+        _initialized = True
+        return None
+
+    _client = client
+    _initialized = True
+
+    if flush_on_exit:
+        atexit.register(_safe_shutdown)
+
+    if not quiet:
+        logger.info("orbitrage: telemetry → %s app=%s", endpoint, app_name)
+    return client
+
+
+def _default_app_name() -> str:
+    """Best-effort app name — file basename, falling back to 'orbitrage'."""
+    try:
+        argv0 = sys.argv[0] if sys.argv and sys.argv[0] else ""
+        if argv0:
+            base = os.path.basename(argv0)
+            stem = os.path.splitext(base)[0]
+            if stem:
+                return stem
+    except Exception:
+        pass
+    return "orbitrage"
+
+
+# ── lifecycle ─────────────────────────────────────────────────────────────
+def flush(timeout_ms: int = 5000) -> bool:
+    """Force-flush pending spans. Returns True on success."""
+    if not _initialized:
+        return True
+    try:
+        from opentelemetry import trace
+        provider = trace.get_tracer_provider()
+        fn = getattr(provider, "force_flush", None)
+        if callable(fn):
+            return bool(fn(timeout_ms))
+    except Exception:
+        pass
+    return True
+
+
+def shutdown() -> None:
+    """Shut down the SDK. Flushes pending spans then closes the exporter."""
+    if not _initialized:
+        return
+    _safe_shutdown()
+
+
+def _safe_shutdown() -> None:
+    """atexit-friendly shutdown — never raises."""
+    try:
+        from opentelemetry import trace
+        provider = trace.get_tracer_provider()
+        fn = getattr(provider, "shutdown", None)
+        if callable(fn):
+            fn()
+    except Exception:
+        pass
+
+
+# ── decorators (re-export from Traceloop) ─────────────────────────────────
+def workflow(name: Optional[str] = None, **kwargs) -> Callable:
+    """Mark a function as a workflow (groups all nested LLM calls).
+
+    @orbitrage.workflow("checkout")
+    def run():
+        ...
+    """
+    from traceloop.sdk.decorators import workflow as _wf
+    return _wf(name=name, **kwargs)
+
+
+def task(name: Optional[str] = None, **kwargs) -> Callable:
+    """Mark a function as a single task inside a workflow."""
+    from traceloop.sdk.decorators import task as _t
+    return _t(name=name, **kwargs)
+
+
+def tool(name: Optional[str] = None, **kwargs) -> Callable:
+    """Mark a function as a tool call."""
+    from traceloop.sdk.decorators import tool as _t
+    return _t(name=name, **kwargs)
+
+
+def agent(name: Optional[str] = None, **kwargs) -> Callable:
+    """Mark a function as an agent step."""
+    from traceloop.sdk.decorators import agent as _a
+    return _a(name=name, **kwargs)
+
+
+def set_association_properties(properties: dict) -> None:
+    """Attach metadata (user_id, tenant_id, etc.) to every span in scope."""
+    if not _initialized:
+        return
+    try:
+        from traceloop.sdk import Traceloop
+        Traceloop.set_association_properties(properties)
+    except Exception:
+        pass

orbitrage-0.2.0.dist-info/METADATA

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: orbitrage
+Version: 0.2.0
+Summary: One-line observability + intelligent LLM routing for Python agents.
+Author: Orbitrage
+License: Apache-2.0
+Project-URL: Homepage, https://orbitrage.xyz
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: traceloop-sdk<1.0,>=0.50.0
+Requires-Dist: opentelemetry-sdk>=1.27.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27.0
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.20; extra == "anthropic"
+Provides-Extra: langchain
+Requires-Dist: langchain-openai>=0.2; extra == "langchain"
+Requires-Dist: langchain-core>=0.3; extra == "langchain"
+
+# orbitrage
+
+One-line observability + intelligent LLM routing for Python agents.
+
+```python
+import orbitrage
+orbitrage.init("orb_xxx_yyy")          # one line. that's it.
+
+# now any OpenAI / Anthropic / LangChain call you make is auto-traced
+# AND can be auto-routed via:
+from openai import OpenAI
+client = OpenAI(base_url="https://orbitrage.xyz/api/v1", api_key="orb_xxx_yyy")
+```
+
+## What it does
+
+- **Zero-latency observability**: non-blocking batch span export — your hot
+  path stays at LLM-call speed, not LLM-call + telemetry RTT.
+- **Auto-instruments** OpenAI, Anthropic, LangChain, LlamaIndex, etc. via
+  OpenLLMetry under the hood.
+- **One endpoint**: `https://orbitrage.xyz/api/telemetry` — auth via your
+  Orbitrage API key.
+- **Decorators** for grouping multi-step workflows:
+
+```python
+from orbitrage import workflow, task
+
+@workflow("checkout_flow")
+def checkout(user_id):
+    plan = planner.invoke(...)
+    out  = executor.invoke(...)
+    return formatter.invoke(...)
+```
+
+## Install
+
+```
+pip install orbitrage
+```
+
+## Redacting prompts (opt-out)
+
+Prompt + completion text is captured by default so it renders in the
+Orbitrage dashboard. To redact content (token counts, costs, and routing
+decisions still flow):
+
+```python
+orbitrage.init("orb_xxx", capture_content=False)
+```
+

orbitrage-0.2.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+orbitrage/__init__.py,sha256=cej4X_qvPgjlipUQKEVphLgWIQGL1JLC1A6dhIEK2wA,487
+orbitrage/_client.py,sha256=mf84uXSdYuFNcSLEGIc4T16I2O1v7eHoD9SJS23Y4pk,15581
+orbitrage-0.2.0.dist-info/METADATA,sha256=5rU_wTgvMIE3keFgtkiWDgiG-0Zx4wSaIcL-T5-8_NU,2608
+orbitrage-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+orbitrage-0.2.0.dist-info/top_level.txt,sha256=x-k_0Wk9P1meLDIOfc10DSjgyFwAkWLwe8G0xjknSOc,10
+orbitrage-0.2.0.dist-info/RECORD,,

orbitrage-0.2.0.dist-info/WHEEL

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

orbitrage-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+orbitrage