eldros-sdk 0.1.0__py3-none-any.whl

eldros_sdk/__init__.py

@@ -0,0 +1,38 @@
+"""Eldros tracing SDK — OpenTelemetry-native instrumentation for AI agents.
+
+Quick start::
+
+    from eldros_sdk import init, trace
+
+    init(agent_id="my-agent")   # ELDROS_API_KEY and ELDROS_API_BASE_URL from env
+
+    @trace
+    async def handle_conversation(user_message: str) -> str:
+        # OpenAI / Anthropic calls inside here are auto-instrumented.
+        ...
+
+One ``init()`` call resolves Langfuse credentials from the Eldros platform, wires
+up OpenTelemetry, and auto-instruments installed LLM providers. ``@trace`` opens a
+root span per call.
+"""
+
+from __future__ import annotations
+
+from . import attributes
+from .client import flush, get_config, init, is_enabled, shutdown
+from .config import TraceConfig
+from .decorator import get_tracer, trace
+from .version import __version__
+
+__all__ = [
+    "__version__",
+    "init",
+    "trace",
+    "flush",
+    "shutdown",
+    "get_config",
+    "get_tracer",
+    "is_enabled",
+    "TraceConfig",
+    "attributes",
+]

eldros_sdk/_instrument.py

@@ -0,0 +1,72 @@
+"""Optional auto-instrumentation of LLM provider SDKs.
+
+We rely on OpenLLMetry (traceloop) instrumentors, which emit OpenTelemetry
+GenAI-semconv spans that Langfuse understands natively. Each provider is an
+optional extra; if the instrumentor is not installed we log and move on so the
+core SDK never hard-depends on any provider library.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+from opentelemetry.sdk.trace import TracerProvider
+
+from .config import TraceConfig
+
+logger: logging.Logger = logging.getLogger("eldros_sdk")
+
+
+def instrument_llm_providers(config: TraceConfig, provider: TracerProvider) -> None:
+    """Auto-instrument enabled LLM providers against the given tracer provider."""
+    # OpenLLMetry honors this env var to toggle prompt/response content capture.
+    os.environ.setdefault(
+        "TRACELOOP_TRACE_CONTENT", "true" if config.capture_content else "false"
+    )
+
+    if config.instrument_openai:
+        _safe_instrument(
+            label="openai",
+            module_path="opentelemetry.instrumentation.openai",
+            class_name="OpenAIInstrumentor",
+            provider=provider,
+        )
+    if config.instrument_anthropic:
+        _safe_instrument(
+            label="anthropic",
+            module_path="opentelemetry.instrumentation.anthropic",
+            class_name="AnthropicInstrumentor",
+            provider=provider,
+        )
+
+
+def _safe_instrument(
+    label: str, module_path: str, class_name: str, provider: TracerProvider
+) -> None:
+    """Import and apply one instrumentor, swallowing all failures with a log line."""
+    try:
+        module: Any = __import__(module_path, fromlist=[class_name])
+        instrumentor_cls: Any = getattr(module, class_name)
+    except ImportError:
+        logger.info(
+            "eldros_sdk: %s auto-instrumentation not installed "
+            "(pip install eldros-sdk[%s])",
+            label,
+            label,
+        )
+        return
+    except Exception as exc:  # pragma: no cover - defensive
+        logger.warning("eldros_sdk: could not import %s instrumentor: %s", label, exc)
+        return
+
+    try:
+        instrumentor: Any = instrumentor_cls()
+        if getattr(instrumentor, "is_instrumented_by_opentelemetry", False):
+            logger.debug("eldros_sdk: %s already instrumented; skipping", label)
+            return
+        instrumentor.instrument(tracer_provider=provider)
+        logger.info("eldros_sdk: %s auto-instrumented", label)
+    except Exception as exc:  # pragma: no cover - defensive
+        logger.warning("eldros_sdk: failed to instrument %s: %s", label, exc)

eldros_sdk/attributes.py

@@ -0,0 +1,37 @@
+"""Canonical span/resource attribute keys for the Eldros tracing SDK.
+
+These are the first-class attributes our backend understands. Most voice keys
+are not emitted by the Week 1-2 core (text agents only) but are defined here so
+the schema lives in one place and ``@trace(attributes=...)`` usage is typed and
+discoverable. See ``sdk_for_client_traces.md`` section 5 for the full schema.
+"""
+
+from __future__ import annotations
+
+# --- identity / routing (set on every span via resource + root span) ---------
+AGENT_ID: str = "agent.id"
+TRAFFIC_TYPE: str = "traffic_type"  # "prod" | "eval"
+SESSION_ID: str = "session.id"
+
+# --- generic IO capture for user-decorated functions -------------------------
+# Langfuse-native keys: these map directly to an observation's Input/Output in
+# the Langfuse UI, and the root observation's I/O becomes the trace's I/O.
+INPUT: str = "langfuse.observation.input"
+OUTPUT: str = "langfuse.observation.output"
+
+# --- voice: speech-to-text ----------------------------------------------------
+VOICE_TURN_INDEX: str = "voice.turn_index"
+STT_PROVIDER: str = "stt.provider"
+STT_TRANSCRIPT: str = "stt.transcript"
+STT_LATENCY_MS: str = "stt.latency_ms"
+STT_AUDIO_DURATION_MS: str = "stt.audio_duration_ms"
+
+# --- voice: text-to-speech ----------------------------------------------------
+TTS_PROVIDER: str = "tts.provider"
+TTS_TTFB_MS: str = "tts.ttfb_ms"
+TTS_CHARACTERS: str = "tts.characters"
+VOICE_INTERRUPTED: str = "voice.interrupted"
+
+# --- tools --------------------------------------------------------------------
+TOOL_CALL_NAME: str = "tool_call.name"
+TOOL_CALL_MOCKED: str = "tool_call.mocked"

eldros_sdk/client.py

@@ -0,0 +1,311 @@
+"""SDK lifecycle: ``init()`` configures OpenTelemetry to export to Langfuse.
+
+A single global state object holds the resolved config and tracer provider.
+``init()`` is idempotent. When tracing is disabled or credentials are missing,
+span creation still works but spans are simply never exported — client code
+never has to null-check (the OTel API returns non-recording spans by default).
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+import ssl
+import threading
+from typing import Optional
+
+from opentelemetry import trace as otel_trace
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import (
+    BatchSpanProcessor,
+    ConsoleSpanExporter,
+    SpanExporter,
+)
+
+from . import attributes as attr
+from ._instrument import instrument_llm_providers
+from .config import TraceConfig
+from .version import __version__
+
+logger: logging.Logger = logging.getLogger("eldros_sdk")
+
+
+class _State:
+    """Process-global SDK state, populated once by ``init()``."""
+
+    def __init__(self) -> None:
+        self.config: Optional[TraceConfig] = None
+        self.provider: Optional[TracerProvider] = None
+        self.initialized: bool = False
+
+
+_state: _State = _State()
+_lock: threading.Lock = threading.Lock()
+
+
+def init(
+    *,
+    api_key: Optional[str] = None,
+    api_base_url: Optional[str] = None,
+    agent_id: Optional[str] = None,
+    traffic_type: Optional[str] = None,
+    env: Optional[str] = None,
+    service_name: Optional[str] = None,
+    instrument_openai: Optional[bool] = None,
+    instrument_anthropic: Optional[bool] = None,
+    instrument_claude_agent_sdk: Optional[bool] = None,
+    capture_content: Optional[bool] = None,
+    debug: Optional[bool] = None,
+    enabled: Optional[bool] = None,
+) -> TraceConfig:
+    """Initialize tracing for this process. Safe to leave in production.
+
+    The SDK resolves Langfuse credentials from the Eldros platform using the
+    API key — clients never configure Langfuse directly.
+
+    Args:
+        api_key: Eldros platform key (``agt_...``). Falls back to ELDROS_API_KEY env var.
+        api_base_url: Eldros platform base URL. Falls back to ELDROS_API_BASE_URL env var.
+        agent_id: Stamped as ``agent.id`` on every span. Falls back to ELDROS_AGENT_ID.
+        traffic_type/env: ``"prod"`` or ``"eval"`` (``env`` is an alias).
+        service_name: OTel ``service.name``.
+        instrument_openai: Auto-instrument openai if installed. Default False — opt in explicitly.
+        instrument_anthropic: Auto-instrument anthropic if installed. Default False — opt in explicitly.
+        instrument_claude_agent_sdk: Auto-instrument claude_agent_sdk via LangSmith if installed. Default False — opt in explicitly.
+        capture_content: Whether LLM spans record prompt/response text.
+        debug: Also print spans to the console.
+        enabled: Master off-switch; ``False`` makes the SDK a no-op.
+
+    Returns:
+        The resolved :class:`TraceConfig`.
+    """
+    with _lock:
+        if _state.initialized:
+            logger.warning("eldros_sdk.init() already called; ignoring repeat call")
+            return _state.config  # type: ignore[return-value]
+
+        config: TraceConfig = TraceConfig.resolve(
+            api_key=api_key,
+            api_base_url=api_base_url,
+            agent_id=agent_id,
+            traffic_type=traffic_type or env,
+            service_name=service_name,
+            instrument_openai=instrument_openai,
+            instrument_anthropic=instrument_anthropic,
+            instrument_claude_agent_sdk=instrument_claude_agent_sdk,
+            capture_content=capture_content,
+            debug=debug,
+            enabled=enabled,
+        )
+
+        if not config.enabled:
+            logger.info("eldros_sdk disabled (enabled=False); all tracing is a no-op")
+            _state.config = config
+            _state.initialized = True
+            return config
+
+        # Resolve a platform API key to Langfuse credentials (unless creds were supplied).
+        if config.api_key and not config.has_credentials:
+            _resolve_credentials_from_api_key(config)
+
+        # Additive: if the client already has a real TracerProvider (their own OTel setup,
+        # LangSmith OTEL mode, Datadog, etc.) attach our exporter to it instead of
+        # replacing it — spans flow to both their backend and our Langfuse.
+        existing: otel_trace.TracerProvider = otel_trace.get_tracer_provider()
+        if isinstance(existing, TracerProvider):
+            provider = existing
+            logger.info("eldros_sdk: attaching to existing TracerProvider (additive mode)")
+        else:
+            provider = TracerProvider(resource=_build_resource(config))
+            otel_trace.set_tracer_provider(provider)
+            logger.info("eldros_sdk: created new TracerProvider")
+
+        if config.has_credentials:
+            provider.add_span_processor(BatchSpanProcessor(_build_otlp_exporter(config)))
+            logger.info("eldros_sdk exporting spans to %s", config.otlp_traces_endpoint)
+        else:
+            logger.warning(
+                "eldros_sdk: no Langfuse credentials resolved — set ELDROS_API_KEY "
+                "and ELDROS_API_BASE_URL. Spans will be created but not exported."
+            )
+
+        if config.debug:
+            provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))
+
+        instrument_llm_providers(config, provider)
+
+        if config.instrument_claude_agent_sdk:
+            _try_instrument_claude(config)
+
+        _state.config = config
+        _state.provider = provider
+        _state.initialized = True
+        logger.info(
+            "eldros_sdk initialized (agent_id=%s, traffic_type=%s, service=%s)",
+            config.agent_id,
+            config.traffic_type,
+            config.service_name,
+        )
+        return config
+
+
+def _build_resource(config: TraceConfig) -> Resource:
+    """OTel resource attributes stamped onto every span emitted by this process."""
+    resource_attrs: dict[str, str] = {
+        "service.name": config.service_name,
+        "eldros_sdk.version": __version__,
+        attr.TRAFFIC_TYPE: config.traffic_type,
+    }
+    if config.agent_id:
+        resource_attrs[attr.AGENT_ID] = config.agent_id
+    return Resource.create(resource_attrs)
+
+
+def _build_otlp_exporter(config: TraceConfig) -> SpanExporter:
+    """Build the Langfuse OTLP/HTTP exporter with basic-auth headers.
+
+    Imported lazily so the core package imports without the OTLP HTTP exporter
+    extra installed (only needed when credentials are present).
+    """
+    from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+
+    token: str = base64.b64encode(
+        f"{config._public_key}:{config._secret_key}".encode("utf-8")
+    ).decode("ascii")
+    return OTLPSpanExporter(
+        endpoint=config.otlp_traces_endpoint,
+        headers={"Authorization": f"Basic {token}"},
+    )
+
+
+def _resolve_credentials_from_api_key(config: TraceConfig) -> None:
+    """Resolve the Eldros platform API key to Langfuse credentials at startup.
+
+    Calls ``GET {api_base_url}/api/v1/langfuse/resolve`` with the
+    ``X-Client-API-Key`` header and fills public_key/secret_key/host on ``config``.
+    Tolerant: on any failure it logs a warning and leaves credentials unset (spans are
+    created but not exported) rather than crashing the client app.
+
+    Must not be called from a running async event loop — use ``asyncio.run()`` or call
+    ``init()`` before starting the event loop (e.g. at module import time).
+    """
+    import asyncio
+    import json
+    import time
+    import urllib.error
+    import urllib.request
+
+    try:
+        asyncio.get_running_loop()
+        logger.warning(
+            "eldros_sdk: init() was called from a running event loop — "
+            "credential resolve skipped to avoid blocking. Call init() before "
+            "starting the event loop, or use ainit() in async contexts."
+        )
+        return
+    except RuntimeError:
+        pass  # no running loop — safe to block
+
+    if not config.api_base_url:
+        logger.warning(
+            "eldros_sdk: api_key set but ELDROS_API_BASE_URL is missing; cannot resolve."
+        )
+        return
+
+    base_url: str = config.api_base_url.rstrip("/")
+    # Reject non-HTTPS in production to prevent secret_key travelling in cleartext.
+    if not base_url.startswith("https://") and not base_url.startswith("http://localhost") and not base_url.startswith("http://127.0.0.1"):
+        logger.warning(
+            "eldros_sdk: ELDROS_API_BASE_URL uses non-HTTPS scheme (%s); "
+            "resolve skipped to protect credentials.",
+            base_url,
+        )
+        return
+
+    url: str = f"{base_url}/api/v1/langfuse/resolve"
+    req: urllib.request.Request = urllib.request.Request(
+        url, headers={"X-Client-API-Key": config.api_key or ""}
+    )
+
+    ssl_ctx: ssl.SSLContext | None = None
+    if not config.ssl_verify:
+        ssl_ctx = ssl.create_default_context()
+        ssl_ctx.check_hostname = False
+        ssl_ctx.verify_mode = ssl.CERT_NONE
+        logger.warning("eldros_sdk: SSL certificate verification disabled (ssl_verify=False)")
+
+    # Retry with exponential backoff (3 attempts: 1s, 2s, 4s).
+    _MAX_ATTEMPTS: int = 3
+    for attempt in range(1, _MAX_ATTEMPTS + 1):
+        try:
+            with urllib.request.urlopen(req, timeout=10, context=ssl_ctx) as response:  # noqa: S310
+                creds: dict[str, str] = json.loads(response.read().decode("utf-8"))
+            config._public_key = creds["public_key"]
+            config._secret_key = creds["secret_key"]
+            config._host = creds.get("host") or config._host
+            logger.info("eldros_sdk resolved Langfuse credentials via API key (%s)", url)
+            return
+        except (urllib.error.URLError, KeyError, ValueError, TimeoutError) as exc:
+            if attempt < _MAX_ATTEMPTS:
+                wait: float = 2 ** (attempt - 1)
+                logger.warning(
+                    "eldros_sdk: resolve attempt %d/%d failed (%s); retrying in %.0fs",
+                    attempt, _MAX_ATTEMPTS, exc, wait,
+                )
+                time.sleep(wait)
+            else:
+                logger.warning(
+                    "eldros_sdk: could not resolve credentials after %d attempts: %s",
+                    _MAX_ATTEMPTS, exc,
+                )
+
+
+def _try_instrument_claude(config: TraceConfig) -> None:
+    """Auto-instrument claude_agent_sdk if the [claude] extra is installed."""
+    try:
+        import claude_agent_sdk  # noqa: F401
+    except ImportError:
+        return  # not installed — skip silently
+
+    if not config.has_credentials:
+        logger.warning(
+            "eldros_sdk: claude_agent_sdk found but credentials not resolved — "
+            "instrument_claude_agent_sdk() skipped."
+        )
+        return
+
+    try:
+        from .integrations.claude_agent_sdk import _instrument_langsmith
+        _instrument_langsmith()
+    except ImportError:
+        logger.info(
+            "eldros_sdk: claude_agent_sdk found but langsmith[claude-agent-sdk] not installed; "
+            "run: pip install 'eldros-sdk[claude]'"
+        )
+    except Exception as exc:
+        logger.warning("eldros_sdk: claude_agent_sdk auto-instrumentation failed: %s", exc)
+
+
+def get_config() -> Optional[TraceConfig]:
+    """Return the resolved config, or ``None`` if ``init()`` has not run."""
+    return _state.config
+
+
+def is_enabled() -> bool:
+    """True when the SDK is initialized and not disabled."""
+    return bool(_state.config and _state.config.enabled)
+
+
+def flush() -> None:
+    """Force-export any buffered spans. Useful before a short-lived process exits."""
+    if _state.provider is not None:
+        _state.provider.force_flush()
+
+
+def shutdown() -> None:
+    """Flush and tear down the tracer provider."""
+    if _state.provider is not None:
+        _state.provider.shutdown()
+    _state.provider = None
+    _state.initialized = False

eldros_sdk/config.py

@@ -0,0 +1,98 @@
+"""Configuration model for the Eldros tracing SDK.
+
+Values can come from explicit ``init(...)`` keyword arguments or environment
+variables. Explicit kwargs always win over env vars.
+
+Credentials are resolved from the Eldros platform via ``ELDROS_API_KEY`` —
+clients never configure Langfuse directly. ``LANGFUSE_*`` env vars are NOT read.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, PrivateAttr
+
+# Langfuse Cloud (EU). US region: https://us.cloud.langfuse.com
+DEFAULT_LANGFUSE_HOST: str = "https://cloud.langfuse.com"
+
+# No default — clients must set ELDROS_API_BASE_URL. Updated to the real domain when available.
+DEFAULT_ELDROS_API_BASE_URL: str = ""
+
+
+def _as_bool(value: Optional[str]) -> Optional[bool]:
+    """Parse a loose boolean env var. Returns ``None`` when unset."""
+    if value is None:
+        return None
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+class TraceConfig(BaseModel):
+    """Resolved configuration for a single SDK process.
+
+    Client-facing fields are set via ``init()`` kwargs or env vars.
+    Langfuse credentials (_public_key, _secret_key, _host) are private —
+    resolved internally from the Eldros platform and never exposed to clients.
+    """
+
+    model_config = ConfigDict(repr=False)
+
+    # Private — resolved from Eldros platform, never set by clients.
+    _public_key: str = PrivateAttr(default="")
+    _secret_key: str = PrivateAttr(default="")
+    _host: str = PrivateAttr(default=DEFAULT_LANGFUSE_HOST)
+
+    # Client-facing — set via init() kwargs or env vars.
+    api_key: Optional[str] = None
+    api_base_url: Optional[str] = None
+    ssl_verify: bool = True
+    agent_id: Optional[str] = None
+    traffic_type: str = "prod"
+    service_name: str = "eldros-agent"
+    instrument_openai: bool = False
+    instrument_anthropic: bool = False
+    instrument_claude_agent_sdk: bool = False
+    capture_content: bool = True
+    debug: bool = False
+    enabled: bool = True
+
+    def __repr__(self) -> str:
+        return (
+            f"TraceConfig(agent_id={self.agent_id!r}, host={self._host!r}, "
+            f"traffic_type={self.traffic_type!r}, enabled={self.enabled})"
+        )
+
+    def __str__(self) -> str:
+        return self.__repr__()
+
+    @classmethod
+    def resolve(cls, **overrides: object) -> "TraceConfig":
+        """Build a config from environment variables overlaid with explicit kwargs.
+
+        ``None`` overrides are dropped so they fall back to env, then to defaults.
+        """
+        from_env: dict[str, object] = {
+            "api_key": os.getenv("ELDROS_API_KEY"),
+            "api_base_url": os.getenv("ELDROS_API_BASE_URL") or DEFAULT_ELDROS_API_BASE_URL,
+            "ssl_verify": _as_bool(os.getenv("ELDROS_API_SSL_VERIFY")),
+            "agent_id": os.getenv("ELDROS_AGENT_ID"),
+            "traffic_type": os.getenv("ELDROS_TRAFFIC_TYPE"),
+            "service_name": os.getenv("ELDROS_SERVICE_NAME"),
+            "instrument_claude_agent_sdk": _as_bool(os.getenv("ELDROS_INSTRUMENT_CLAUDE_AGENT_SDK")),
+            "capture_content": _as_bool(os.getenv("ELDROS_CAPTURE_CONTENT")),
+            "debug": _as_bool(os.getenv("ELDROS_TRACE_DEBUG")),
+            "enabled": _as_bool(os.getenv("ELDROS_TRACE_ENABLED")),
+        }
+        merged: dict[str, object] = {k: v for k, v in from_env.items() if v is not None}
+        merged.update({k: v for k, v in overrides.items() if v is not None})
+        return cls(**merged)
+
+    @property
+    def has_credentials(self) -> bool:
+        return bool(self._public_key and self._secret_key)
+
+    @property
+    def otlp_traces_endpoint(self) -> str:
+        """Full OTLP/HTTP traces endpoint for the configured Langfuse host."""
+        return f"{self._host.rstrip('/')}/api/public/otel/v1/traces"

eldros_sdk/decorator.py

@@ -0,0 +1,168 @@
+"""The ``@trace`` decorator — wraps a function in a root span.
+
+Handles plain sync functions, coroutines, sync generators and async generators
+so streaming agent loops keep a single span open across the whole generation.
+Identity attributes (``agent.id``, ``traffic_type``) from :func:`init` config are
+stamped onto the span automatically. If ``init()`` was never called the span is
+a no-op (the OTel API returns a non-recording span), so the decorator is always
+safe to apply.
+
+All four wrapper variants share span setup/teardown via :func:`_span_scope`, so
+identity stamping, input capture and error recording live in exactly one place.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import functools
+import inspect
+import logging
+from typing import Any, Callable, Iterator, Mapping, Optional
+
+from opentelemetry import trace as otel_trace
+from opentelemetry.trace import Span, SpanKind, Status, StatusCode
+
+from . import attributes as attr
+from .client import get_config
+from .config import TraceConfig
+from .version import __version__
+
+logger: logging.Logger = logging.getLogger("eldros_sdk")
+
+_MAX_IO_CHARS: int = 2000
+
+
+def get_tracer() -> otel_trace.Tracer:
+    """Return the SDK tracer. Non-recording until ``init()`` sets a provider."""
+    return otel_trace.get_tracer("eldros_sdk", __version__)
+
+
+def _truncate(text: str) -> str:
+    return text if len(text) <= _MAX_IO_CHARS else text[:_MAX_IO_CHARS] + "...[truncated]"
+
+
+def _io_repr(args: tuple[Any, ...], kwargs: dict[str, Any]) -> str:
+    return f"args={args!r} kwargs={kwargs!r}"
+
+
+def _apply_attributes(span: Span, extra: Optional[Mapping[str, Any]]) -> None:
+    """Stamp identity attributes from config plus any caller-supplied extras."""
+    config: Optional[TraceConfig] = get_config()
+    if config is not None:
+        if config.agent_id:
+            span.set_attribute(attr.AGENT_ID, config.agent_id)
+        span.set_attribute(attr.TRAFFIC_TYPE, config.traffic_type)
+    if extra:
+        for key, value in extra.items():
+            span.set_attribute(key, value)
+
+
+def _record_error(span: Span, exc: BaseException, record_exception: bool) -> None:
+    logger.debug("eldros_sdk: recording error on span: %s", exc)
+    if record_exception:
+        span.record_exception(exc)
+    span.set_status(Status(StatusCode.ERROR, str(exc)))
+
+
+@contextlib.contextmanager
+def _span_scope(
+    span_name: str,
+    kind: SpanKind,
+    attributes: Optional[Mapping[str, Any]],
+    capture_io: bool,
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+    record_exception: bool,
+) -> Iterator[Span]:
+    """Open a span, stamp attributes/input, and record any error from the body."""
+    tracer: otel_trace.Tracer = get_tracer()
+    with tracer.start_as_current_span(span_name, kind=kind) as span:
+        _apply_attributes(span, attributes)
+        logger.debug("eldros_sdk: span %r started", span_name)
+        if capture_io:
+            span.set_attribute(attr.INPUT, _truncate(_io_repr(args, kwargs)))
+        try:
+            yield span
+        except Exception as exc:
+            _record_error(span, exc, record_exception)
+            raise
+
+
+def trace(
+    func: Optional[Callable[..., Any]] = None,
+    *,
+    name: Optional[str] = None,
+    kind: SpanKind = SpanKind.INTERNAL,
+    attributes: Optional[Mapping[str, Any]] = None,
+    capture_io: bool = False,
+    record_exception: bool = True,
+) -> Any:
+    """Wrap a function so each call is recorded as a span.
+
+    Usable bare (``@trace``) or parameterized (``@trace(name=..., capture_io=True)``).
+
+    Args:
+        name: Span name. Defaults to the function's qualified name.
+        kind: OTel :class:`SpanKind`.
+        attributes: Static attributes to set on every span this function emits.
+        capture_io: Record (truncated) call args and return value on the span.
+            Off by default to avoid capturing large/sensitive payloads.
+        record_exception: Attach exception details to the span before re-raising.
+    """
+
+    def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
+        span_name: str = name or fn.__qualname__
+
+        if inspect.isasyncgenfunction(fn):
+
+            @functools.wraps(fn)
+            async def async_gen_wrapper(*args: Any, **kwargs: Any) -> Any:
+                with _span_scope(
+                    span_name, kind, attributes, capture_io, args, kwargs, record_exception
+                ):
+                    async for item in fn(*args, **kwargs):
+                        yield item
+
+            return async_gen_wrapper
+
+        if inspect.iscoroutinefunction(fn):
+
+            @functools.wraps(fn)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                with _span_scope(
+                    span_name, kind, attributes, capture_io, args, kwargs, record_exception
+                ) as span:
+                    result: Any = await fn(*args, **kwargs)
+                    if capture_io:
+                        span.set_attribute(attr.OUTPUT, _truncate(repr(result)))
+                    return result
+
+            return async_wrapper
+
+        if inspect.isgeneratorfunction(fn):
+
+            @functools.wraps(fn)
+            def gen_wrapper(*args: Any, **kwargs: Any) -> Any:
+                with _span_scope(
+                    span_name, kind, attributes, capture_io, args, kwargs, record_exception
+                ):
+                    yield from fn(*args, **kwargs)
+
+            return gen_wrapper
+
+        @functools.wraps(fn)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            with _span_scope(
+                span_name, kind, attributes, capture_io, args, kwargs, record_exception
+            ) as span:
+                result: Any = fn(*args, **kwargs)
+                if capture_io:
+                    span.set_attribute(attr.OUTPUT, _truncate(repr(result)))
+                return result
+
+        return sync_wrapper
+
+    # Bare @trace vs @trace(...) usage.
+    if func is not None and callable(func):
+        return decorator(func)
+    return decorator

eldros_sdk/integrations/__init__.py

@@ -0,0 +1,3 @@
+"""Framework integrations for eldros-sdk (e.g. the Claude Agent SDK)."""
+
+from __future__ import annotations

eldros_sdk/integrations/claude_agent_sdk.py

@@ -0,0 +1,64 @@
+"""Instrument the Claude Agent SDK and route its traces to Langfuse via LangSmith.
+
+LangSmith patches ClaudeSDKClient and converts RunTree data to OTel spans via its
+background thread when OTEL_ENABLED=true. It detects the global TracerProvider set
+by eldros_sdk.init() and uses it directly — no separate OTLP endpoint config needed.
+Spans flow through our BatchSpanProcessor to Langfuse alongside @trace and LLM spans.
+
+If the client also has LANGSMITH_API_KEY set, the RunTree path simultaneously posts
+to their LangSmith account (dual destination).
+
+Clients who add their own SpanProcessor to the global TracerProvider will also receive
+Claude Agent SDK spans — they can route to their own Langfuse or any OTel backend.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+logger = logging.getLogger("eldros_sdk")
+
+
+def _instrument_langsmith() -> None:
+    try:
+        from langsmith.integrations.claude_agent_sdk import configure_claude_agent_sdk
+    except ImportError as exc:
+        raise ImportError(
+            "instrument_claude_agent_sdk() needs the langsmith[claude-agent-sdk] extra: "
+            "pip install 'eldros-sdk[claude-agent-sdk]'"
+        ) from exc
+
+    # Always enable OTel so LangSmith emits spans via our global TracerProvider → Langfuse.
+    os.environ["LANGSMITH_OTEL_ENABLED"] = "true"
+
+    has_real_ls_key: bool = bool(os.environ.get("LANGSMITH_API_KEY"))
+    if has_real_ls_key:
+        # Hybrid: OTEL_ONLY not set → hybrid_otel_and_langsmith=True automatically.
+        # RunTree posts to client's LangSmith AND OTel → our Langfuse.
+        logger.info("eldros_sdk: LANGSMITH_API_KEY detected — traces → LangSmith + Langfuse")
+    else:
+        # OTel-only: explicitly disable LangSmith API posting — no 401, no noise.
+        os.environ["LANGSMITH_OTEL_ONLY"] = "true"
+        logger.info("eldros_sdk: no LANGSMITH_API_KEY — OTel-only mode → Langfuse only")
+
+    os.environ.setdefault("LANGSMITH_TRACING", "true")
+
+    # get_env_var is lru_cache'd — clear it so the values we just set are picked up.
+    try:
+        import langsmith.utils as _ls_utils
+        _ls_utils.get_env_var.cache_clear()
+    except Exception:
+        pass
+
+    # Rebuild the LangSmith client so it picks up OTEL_ENABLED and attaches to
+    # our global TracerProvider.
+    try:
+        import langsmith.run_trees as _rt
+        _rt._CLIENT = None
+    except Exception:
+        pass
+
+    configure_claude_agent_sdk()
+
+    logger.info("eldros_sdk: claude_agent_sdk instrumented via LangSmith (OTel → global TracerProvider)")

eldros_sdk/version.py

@@ -0,0 +1,5 @@
+"""Single source of truth for the eldros-sdk package version."""
+
+from __future__ import annotations
+
+__version__: str = "0.1.0"

eldros_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: eldros-sdk
+Version: 0.1.0
+Summary: OpenTelemetry-native tracing SDK for Eldros AI agents
+License: MIT
+License-File: LICENSE
+Keywords: opentelemetry,tracing,llm,ai-agents,observability
+Author: Eldros
+Author-email: shyam@sentient.xyz
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT 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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Monitoring
+Provides-Extra: all
+Provides-Extra: anthropic
+Provides-Extra: claude-agent-sdk
+Provides-Extra: openai
+Requires-Dist: claude-agent-sdk (>=0.2.0) ; extra == "claude-agent-sdk" or extra == "all"
+Requires-Dist: langsmith[claude-agent-sdk] (>=0.8.17) ; extra == "claude-agent-sdk" or extra == "all"
+Requires-Dist: opentelemetry-api (>=1.25.0)
+Requires-Dist: opentelemetry-exporter-otlp-proto-http (>=1.25.0)
+Requires-Dist: opentelemetry-instrumentation-anthropic (>=0.25.0) ; extra == "anthropic" or extra == "all"
+Requires-Dist: opentelemetry-instrumentation-openai (>=0.25.0) ; extra == "openai" or extra == "all"
+Requires-Dist: opentelemetry-sdk (>=1.25.0)
+Requires-Dist: pydantic (>=2.0)
+Project-URL: Homepage, https://github.com/GShyam001/Construct
+Project-URL: Repository, https://github.com/GShyam001/Construct
+Description-Content-Type: text/markdown
+
+# eldros-sdk
+
+OpenTelemetry-native tracing SDK for Eldros AI agents. One `init()` call
+resolves your Langfuse credentials from the Eldros platform, wires up
+OpenTelemetry, and auto-instruments your LLM provider clients. Drop a `@trace`
+decorator on your handler and you get a root span per call.
+
+**You need exactly one thing: an Eldros API key** (`agt_...`). The SDK
+resolves Langfuse credentials from the Eldros platform at startup — you never
+configure Langfuse directly.
+
+## Install
+
+```bash
+pip install eldros-sdk              # core
+pip install "eldros-sdk[claude-agent-sdk]"    # + Claude Agent SDK instrumentation via LangSmith
+pip install "eldros-sdk[openai]"    # + OpenAI auto-instrumentation
+pip install "eldros-sdk[anthropic]" # + Anthropic auto-instrumentation
+pip install "eldros-sdk[all]"       # everything
+```
+
+## Quick start
+
+```bash
+export ELDROS_API_KEY=agt_...
+```
+
+```python
+from eldros_sdk import init, trace
+
+init(agent_id="support-bot")   # api_key is read from ELDROS_API_KEY
+
+@trace
+async def handle_conversation(user_message: str) -> str:
+    # OpenAI / Anthropic calls in here are auto-instrumented as child spans.
+    ...
+```
+
+`init()` blocks briefly at startup to call the Eldros platform and fetch your
+Langfuse credentials — call it before starting your event loop (e.g. at module
+import time or in your `if __name__ == "__main__"` block).
+
+## Configuration
+
+Every argument can come from an environment variable. Explicit `init(...)` kwargs
+win over env vars.
+
+| `init()` arg             | Env var                  | Default                                        |
+| ------------------------ | ------------------------ | ---------------------------------------------- |
+| `api_key`                | `ELDROS_API_KEY`         | — *(required)*                                 |
+| `api_base_url`           | `ELDROS_API_BASE_URL`    | — *(required until official domain is live)*   |
+| `agent_id`               | `ELDROS_AGENT_ID`        | —                                              |
+| `traffic_type` / `env`   | `ELDROS_TRAFFIC_TYPE`    | `prod`                                         |
+| `service_name`           | `ELDROS_SERVICE_NAME`    | `eldros-agent`                                 |
+| `instrument_claude_agent_sdk` | `ELDROS_INSTRUMENT_CLAUDE_AGENT_SDK` | `false` *(opt in explicitly)*  |
+| `instrument_openai`      | —                        | `false` *(opt in explicitly)*                  |
+| `instrument_anthropic`   | —                        | `false` *(opt in explicitly)*                  |
+| `capture_content`        | `ELDROS_CAPTURE_CONTENT` | `true`                                         |
+| `debug`                  | `ELDROS_TRACE_DEBUG`     | `false`                                        |
+| `enabled`                | `ELDROS_TRACE_ENABLED`   | `true`                                         |
+
+- **`enabled=False`** makes the whole SDK a no-op — safe to leave in any environment.
+- **`debug=True`** (or `ELDROS_TRACE_DEBUG=true`) also prints spans to the console.
+- **`capture_content=False`** strips prompt/response text from LLM spans.
+
+## Decorator options
+
+```python
+@trace(name="checkout", capture_io=True, attributes={"tier": "pro"})
+def run(payload: dict) -> dict:
+    ...
+```
+
+`@trace` supports sync functions, coroutines, sync generators, and async
+generators (the span stays open across the whole generation).
+
+## Claude Agent SDK instrumentation
+
+Install the `[claude-agent-sdk]` extra and pass the flag to `init()` — no separate call:
+
+```bash
+pip install "eldros-sdk[claude-agent-sdk]"
+```
+
+```python
+import eldros_sdk
+
+eldros_sdk.init(agent_id="my-agent", instrument_claude_agent_sdk=True)
+```
+
+`init()` is the single entry point. LangSmith patches `ClaudeSDKClient` and routes
+spans through the global `TracerProvider` — alongside `@trace` and LLM spans.
+Requires `ClaudeSDKClient` (not the module-level `query()`).
+
+If `LANGSMITH_API_KEY` is also set, traces go to both your LangSmith account and
+Eldros's Langfuse simultaneously (hybrid mode).
+
+## Lifecycle
+
+```python
+from eldros_sdk import flush, shutdown
+
+flush()      # force-export buffered spans (e.g. end of a serverless invocation)
+shutdown()   # flush + tear down the provider
+```
+
+## Testing the SDK
+
+```bash
+# Verify credential resolution and SDK init
+ELDROS_API_KEY=agt_... ELDROS_API_BASE_URL=https://... python3 -c "
+import eldros_sdk
+cfg = eldros_sdk.init(agent_id='test')
+print('has_credentials:', cfg.has_credentials)
+"
+
+# Verify a span actually reaches Langfuse
+ELDROS_API_KEY=agt_... ELDROS_TRACE_DEBUG=true python3 -c "
+import eldros_sdk
+
+eldros_sdk.init(agent_id='test', debug=True)
+
+@eldros_sdk.trace
+def hello():
+    return 'world'
+
+hello()
+eldros_sdk.flush()
+print('done — check Langfuse')
+"
+```
+
+## Design notes
+
+- **Credential resolution.** On `init()`, the SDK calls
+  `GET {api_base_url}/api/v1/langfuse/resolve` with your `ELDROS_API_KEY` in the
+  `X-Client-API-Key` header and receives `{public_key, secret_key, host}` for your
+  org's Langfuse project. The Langfuse secret key is never stored on the client.
+- **Langfuse via OTLP/HTTP.** No Langfuse SDK dependency — spans are exported as
+  OTel protobuf over HTTP with basic auth.
+- **Additive OTel.** If a `TracerProvider` already exists (Datadog, etc.) the SDK
+  attaches its exporter to it instead of replacing it — spans flow to both destinations.
+  **Call `init()` before any other tracing setup** so the SDK's provider is detected first.
+- **Claude Agent SDK spans use the global provider.** LangSmith detects the global
+  `TracerProvider` set by `init()` and routes all Claude Agent SDK OTel spans through it.
+  This means any `SpanProcessor` you add to the global provider also receives those spans —
+  you can route to your own Langfuse or any OTel backend alongside ours.
+- **Auto-instrumentation is optional.** Provider instrumentors are extras; if a
+  provider library isn't installed the SDK logs and continues.
+- **Safe by default.** Spans are non-recording until `init()` runs, so `@trace`
+  never breaks code even if `init()` is missing.
+

eldros_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+eldros_sdk/__init__.py,sha256=jQ6Y_rAGx_NOL0k5hPla3rvrxqgqiMyvtV0ukEgh7sI,974
+eldros_sdk/_instrument.py,sha256=oQTdfVGZFNTmz20eZaQJY1Sk5B6lTHYlz-w1HKRhlY0,2632
+eldros_sdk/attributes.py,sha256=WvyqA0ZpPmwPEdMRvrsonViR_WjFeNQqoZdhAc6UDlg,1630
+eldros_sdk/client.py,sha256=Syp82E7yhbXLcHZvSXLKh746chJZGCosQmhVksnQA98,12061
+eldros_sdk/config.py,sha256=Wvd944dOwIJhHiilOqO8kcWD0dyyj3lfcuTSPw3ZplE,3827
+eldros_sdk/decorator.py,sha256=snCYvE9hxOlk4zehC-zmpPyApmDCJVTVUp4NHpxQNmg,6024
+eldros_sdk/integrations/__init__.py,sha256=ZdO7tbTp_orp0vZdZwg1Yi3AbgyfFZNP-UI5ynsS8iM,109
+eldros_sdk/integrations/claude_agent_sdk.py,sha256=KgqoGvfk9T3IlnSCtJihxnwtYVOFW4ZOnRvAFOAD_Ec,2574
+eldros_sdk/version.py,sha256=mSjIBsld1fVnbLPzLrU3TdY5rADDr3qIx6GGfr1Rqxc,129
+eldros_sdk-0.1.0.dist-info/METADATA,sha256=S1k2cmjfhmhvPNdYh4MmJ0DqrnrF2u3_5kYMnG6u3HI,7782
+eldros_sdk-0.1.0.dist-info/WHEEL,sha256=EGEvSphFYqXKs23-kQBeyNoJP1nrT8ZJKQoi5p5DYL8,88
+eldros_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=T-phNFfIt9tzz23JHErwAvuy8KVP5rjvcix7sh29ovI,1063
+eldros_sdk-0.1.0.dist-info/RECORD,,

eldros_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.4.0
+Root-Is-Purelib: true
+Tag: py3-none-any

eldros_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eldros
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.