getstacklens 0.0.1__py3-none-any.whl

getstacklens/__init__.py

@@ -0,0 +1,350 @@
+"""
+StackLens Python SDK
+====================
+
+Observability and governance for your AI stack.
+
+Quickstart::
+
+    import getstacklens
+
+    getstacklens.configure(api_key="sl-xxxx")
+    getstacklens.trace("my-llm-call", model="gpt-4o", provider="openai",
+                    input_tokens=150, output_tokens=200)
+
+Full example with context manager::
+
+    with getstacklens.start_trace("agent-run") as span:
+        response = openai_client.chat.completions.create(
+            model="gpt-4o",
+            messages=[{"role": "user", "content": "Hello"}],
+        )
+        span.record_llm(
+            model="gpt-4o",
+            provider="openai",
+            input_tokens=response.usage.prompt_tokens,
+            output_tokens=response.usage.completion_tokens,
+            completion=response.choices[0].message.content,
+        )
+
+Docs: https://getstacklens.ai/docs
+"""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager, contextmanager
+from datetime import datetime
+from typing import AsyncIterator, Iterator
+
+from .exceptions import (
+    ApiError,
+    AuthError,
+    ConfigurationError,
+    NetworkError,
+    StackLensError,
+)
+from .prompts import AsyncPromptsClient, PromptsClient
+from .tracer import AsyncTracer, Span, Tracer
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "configure",
+    "trace",
+    "start_trace",
+    "prompts",
+    "atrace",
+    "astart_trace",
+    "aprompts",
+    "Tracer",
+    "AsyncTracer",
+    "Span",
+    "PromptsClient",
+    "AsyncPromptsClient",
+    "StackLensError",
+    "ConfigurationError",
+    "AuthError",
+    "ApiError",
+    "NetworkError",
+]
+
+_DEFAULT_ENDPOINT = "https://api.getstacklens.ai"
+
+_tracer: Tracer | None = None
+_prompts_client: PromptsClient | None = None
+_async_tracer: AsyncTracer | None = None
+_async_prompts_client: AsyncPromptsClient | None = None
+
+
+def configure(api_key: str, endpoint: str = _DEFAULT_ENDPOINT) -> None:
+    """
+    Configure the StackLens SDK.
+
+    Call this once at application startup before any tracing or prompt calls.
+
+    Args:
+        api_key:  Your StackLens API key (starts with ``sl-``).
+                  Generate one from the StackLens dashboard under Settings → API Keys.
+        endpoint: Override the API base URL for self-hosted deployments.
+                  Defaults to ``https://api.getstacklens.ai``.
+
+    Example::
+
+        import getstacklens
+        getstacklens.configure(api_key="sl-xxxx")
+
+        # Self-hosted:
+        getstacklens.configure(api_key="sl-xxxx", endpoint="https://api.your-domain.com")
+    """
+    global _tracer, _prompts_client, _async_tracer, _async_prompts_client
+    _tracer = Tracer(api_key=api_key, endpoint=endpoint)
+    _prompts_client = PromptsClient(api_key=api_key, endpoint=endpoint)
+    _async_tracer = AsyncTracer(api_key=api_key, endpoint=endpoint)
+    _async_prompts_client = AsyncPromptsClient(api_key=api_key, endpoint=endpoint)
+
+
+def _require_tracer() -> Tracer:
+    if _tracer is None:
+        raise ConfigurationError(
+            "StackLens is not configured. "
+            "Call getstacklens.configure(api_key='sl-...') before tracing."
+        )
+    return _tracer
+
+
+def trace(
+    name: str,
+    *,
+    model: str,
+    provider: str,
+    input_tokens: int,
+    output_tokens: int,
+    total_tokens: int | None = None,
+    cost_usd: float = 0.0,
+    attributes: dict[str, str] | None = None,
+    tags: list[str] | None = None,
+    status: str = "ok",
+    start_time: datetime | None = None,
+    end_time: datetime | None = None,
+) -> str:
+    """
+    Record a single LLM call and send it to StackLens. Returns the trace ID.
+
+    This is the simplest tracing path — one call, no context managers needed.
+
+    Args:
+        name:         A descriptive name for this operation (e.g. ``"chat-completion"``).
+        model:        The model name (e.g. ``"gpt-4o"``, ``"claude-3-5-sonnet"``).
+        provider:     The provider name (e.g. ``"openai"``, ``"anthropic"``, ``"gemini"``).
+        input_tokens: Number of input/prompt tokens.
+        output_tokens: Number of output/completion tokens.
+        total_tokens: Total tokens (computed from input + output if omitted).
+        cost_usd:     Estimated cost in USD.
+        attributes:   Arbitrary key-value pairs attached to the span.
+        tags:         String tags for filtering in the dashboard.
+        status:       ``'ok'`` (default) or ``'error'``.
+        start_time:   When the LLM call started. Record before the call for accurate latency.
+        end_time:     When the LLM call ended. Defaults to now if omitted.
+
+    Returns:
+        The trace ID string.
+
+    Example::
+
+        start = datetime.now(timezone.utc)
+        response = client.chat.completions.create(...)
+        getstacklens.trace(
+            "my-llm-call",
+            model="gpt-4o",
+            provider="openai",
+            input_tokens=150,
+            output_tokens=200,
+            start_time=start,
+        )
+    """
+    return _require_tracer().record(
+        name,
+        model=model,
+        provider=provider,
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        total_tokens=total_tokens,
+        cost_usd=cost_usd,
+        attributes=attributes,
+        tags=tags,
+        status=status,
+        start_time=start_time,
+        end_time=end_time,
+    )
+
+
+@contextmanager
+def start_trace(name: str) -> Iterator[Span]:
+    """
+    Context manager for tracing a multi-step or agent operation.
+
+    The span is sent to StackLens when the context exits. If an exception
+    is raised, the span status is automatically set to ``'error'``.
+
+    Args:
+        name: A descriptive name for this trace (e.g. ``"agent-run"``).
+
+    Yields:
+        :class:`~getstacklens.tracer.Span` — call :meth:`~getstacklens.tracer.Span.record_llm`
+        on it to attach LLM metadata.
+
+    Example::
+
+        with getstacklens.start_trace("agent-run") as span:
+            response = openai_client.chat.completions.create(
+                model="gpt-4o",
+                messages=[{"role": "user", "content": "Hello"}],
+            )
+            span.record_llm(
+                model="gpt-4o",
+                provider="openai",
+                input_tokens=response.usage.prompt_tokens,
+                output_tokens=response.usage.completion_tokens,
+                completion=response.choices[0].message.content,
+            )
+    """
+    with _require_tracer().start_trace(name) as span:
+        yield span
+
+
+def _require_async_tracer() -> AsyncTracer:
+    if _async_tracer is None:
+        raise ConfigurationError(
+            "StackLens is not configured. "
+            "Call getstacklens.configure(api_key='sl-...') before tracing."
+        )
+    return _async_tracer
+
+
+async def atrace(
+    name: str,
+    *,
+    model: str,
+    provider: str,
+    input_tokens: int,
+    output_tokens: int,
+    total_tokens: int | None = None,
+    cost_usd: float = 0.0,
+    attributes: dict[str, str] | None = None,
+    tags: list[str] | None = None,
+    status: str = "ok",
+    start_time: datetime | None = None,
+    end_time: datetime | None = None,
+) -> str:
+    """
+    Async version of :func:`trace`. Record a single LLM call. Returns the trace ID.
+
+    Use this in asyncio / FastAPI applications instead of the sync :func:`trace`.
+
+    Example::
+
+        trace_id = await getstacklens.atrace(
+            "chat-completion",
+            model="gpt-4o",
+            provider="openai",
+            input_tokens=150,
+            output_tokens=200,
+        )
+    """
+    return await _require_async_tracer().arecord(
+        name,
+        model=model,
+        provider=provider,
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        total_tokens=total_tokens,
+        cost_usd=cost_usd,
+        attributes=attributes,
+        tags=tags,
+        status=status,
+        start_time=start_time,
+        end_time=end_time,
+    )
+
+
+@asynccontextmanager
+async def astart_trace(name: str) -> AsyncIterator[Span]:
+    """
+    Async context manager for tracing a multi-step or agent operation.
+
+    Use this in asyncio / FastAPI applications instead of the sync :func:`start_trace`.
+
+    Example::
+
+        async with getstacklens.astart_trace("agent-run") as span:
+            response = await async_client.chat.completions.create(...)
+            span.record_llm(
+                model="gpt-4o",
+                provider="openai",
+                input_tokens=response.usage.prompt_tokens,
+                output_tokens=response.usage.completion_tokens,
+            )
+    """
+    async with _require_async_tracer().astart_trace(name) as span:
+        yield span
+
+
+class _PromptsNamespace:
+    """Access FlowOps versioned prompts. Use ``getstacklens.prompts.get()``."""
+
+    def get(self, name: str, *, env: str = "production") -> str:
+        """
+        Fetch the active prompt for the given name and environment.
+
+        Args:
+            name: The prompt name as configured in FlowOps.
+            env:  The environment — ``'dev'``, ``'staging'``, or ``'production'``
+                  (default).
+
+        Returns:
+            The prompt content string.
+
+        Example::
+
+            system_prompt = getstacklens.prompts.get("support-system-prompt")
+            user_prompt = getstacklens.prompts.get("onboarding-email", env="staging")
+        """
+        if _prompts_client is None:
+            raise ConfigurationError(
+                "StackLens is not configured. "
+                "Call getstacklens.configure(api_key='sl-...') first."
+            )
+        return _prompts_client.get(name, env=env)
+
+
+prompts = _PromptsNamespace()
+
+
+class _AsyncPromptsNamespace:
+    """Async access to FlowOps versioned prompts. Use ``await getstacklens.aprompts.get()``."""
+
+    async def get(self, name: str, *, env: str = "production") -> str:
+        """
+        Async version of :meth:`_PromptsNamespace.get`.
+
+        Args:
+            name: The prompt name as configured in FlowOps.
+            env:  The environment — ``'dev'``, ``'staging'``, or ``'production'``
+                  (default).
+
+        Returns:
+            The prompt content string.
+
+        Example::
+
+            system_prompt = await getstacklens.aprompts.get("support-system-prompt")
+        """
+        if _async_prompts_client is None:
+            raise ConfigurationError(
+                "StackLens is not configured. "
+                "Call getstacklens.configure(api_key='sl-...') first."
+            )
+        return await _async_prompts_client.get(name, env=env)
+
+
+aprompts = _AsyncPromptsNamespace()

getstacklens/_client.py

@@ -0,0 +1,118 @@
+"""Internal HTTP client. Not part of the public API."""
+
+from __future__ import annotations
+
+import asyncio
+import atexit
+import time
+
+import httpx
+
+from .exceptions import ApiError, AuthError, NetworkError
+
+_DEFAULT_TIMEOUT = 10.0
+_RETRY_ATTEMPTS = 2
+_RETRY_DELAY = 0.5  # seconds; only applied on 5xx and network errors
+
+
+def _parse_response(resp: httpx.Response) -> dict:
+    """Raise the appropriate SDK exception or return the parsed JSON body."""
+    if resp.status_code == 401:
+        raise AuthError("Invalid API key.")
+    if resp.status_code == 403:
+        raise AuthError("API key does not have the required scope.")
+    if not resp.is_success:
+        try:
+            msg = resp.json().get("error", resp.text)
+        except Exception:
+            msg = resp.text
+        raise ApiError(resp.status_code, msg)
+    return resp.json()
+
+
+class _HttpClient:
+    def __init__(self, api_key: str, endpoint: str) -> None:
+        self._base = endpoint.rstrip("/")
+        self._http = httpx.Client(
+            headers={"X-Api-Key": api_key, "Content-Type": "application/json"},
+            timeout=_DEFAULT_TIMEOUT,
+        )
+        atexit.register(self.close)
+
+    def post(self, path: str, payload: dict) -> dict:
+        return self._request("POST", path, json=payload)
+
+    def get(self, path: str, params: dict | None = None) -> dict:
+        return self._request("GET", path, params=params)
+
+    def _request(self, method: str, path: str, **kwargs) -> dict:
+        url = f"{self._base}{path}"
+        last_exc: Exception | None = None
+        for attempt in range(_RETRY_ATTEMPTS):
+            try:
+                resp = self._http.request(method, url, **kwargs)
+                # Retry on server errors (5xx) but not on client errors (4xx)
+                if resp.status_code >= 500 and attempt < _RETRY_ATTEMPTS - 1:
+                    time.sleep(_RETRY_DELAY)
+                    continue
+                return _parse_response(resp)
+            except httpx.TimeoutException as exc:
+                last_exc = exc
+                if attempt < _RETRY_ATTEMPTS - 1:
+                    time.sleep(_RETRY_DELAY)
+            except httpx.NetworkError as exc:
+                last_exc = exc
+                if attempt < _RETRY_ATTEMPTS - 1:
+                    time.sleep(_RETRY_DELAY)
+        raise NetworkError(
+            f"Could not reach StackLens API at {self._base}: {last_exc}"
+        ) from last_exc
+
+    def close(self) -> None:
+        try:
+            self._http.close()
+        except Exception:
+            pass
+
+
+class _AsyncHttpClient:
+    def __init__(self, api_key: str, endpoint: str) -> None:
+        self._base = endpoint.rstrip("/")
+        self._http = httpx.AsyncClient(
+            headers={"X-Api-Key": api_key, "Content-Type": "application/json"},
+            timeout=_DEFAULT_TIMEOUT,
+        )
+
+    async def post(self, path: str, payload: dict) -> dict:
+        return await self._request("POST", path, json=payload)
+
+    async def get(self, path: str, params: dict | None = None) -> dict:
+        return await self._request("GET", path, params=params)
+
+    async def _request(self, method: str, path: str, **kwargs) -> dict:
+        url = f"{self._base}{path}"
+        last_exc: Exception | None = None
+        for attempt in range(_RETRY_ATTEMPTS):
+            try:
+                resp = await self._http.request(method, url, **kwargs)
+                if resp.status_code >= 500 and attempt < _RETRY_ATTEMPTS - 1:
+                    await asyncio.sleep(_RETRY_DELAY)
+                    continue
+                return _parse_response(resp)
+            except httpx.TimeoutException as exc:
+                last_exc = exc
+                if attempt < _RETRY_ATTEMPTS - 1:
+                    await asyncio.sleep(_RETRY_DELAY)
+            except httpx.NetworkError as exc:
+                last_exc = exc
+                if attempt < _RETRY_ATTEMPTS - 1:
+                    await asyncio.sleep(_RETRY_DELAY)
+        raise NetworkError(
+            f"Could not reach StackLens API at {self._base}: {last_exc}"
+        ) from last_exc
+
+    async def close(self) -> None:
+        try:
+            await self._http.aclose()
+        except Exception:
+            pass

getstacklens/exceptions.py

@@ -0,0 +1,25 @@
+"""StackLens SDK exceptions."""
+
+
+class StackLensError(Exception):
+    """Base exception for all StackLens SDK errors."""
+
+
+class ConfigurationError(StackLensError):
+    """Raised when the SDK is not configured. Call stacklens.configure() first."""
+
+
+class AuthError(StackLensError):
+    """Raised when the API key is invalid or does not have the required scope."""
+
+
+class ApiError(StackLensError):
+    """Raised when the StackLens API returns an error response."""
+
+    def __init__(self, status_code: int, message: str) -> None:
+        self.status_code = status_code
+        super().__init__(f"API error {status_code}: {message}")
+
+
+class NetworkError(StackLensError):
+    """Raised when the StackLens API cannot be reached (timeout, DNS, connection refused)."""

getstacklens/prompts.py

@@ -0,0 +1,61 @@
+"""FlowOps prompt client."""
+
+from __future__ import annotations
+
+from ._client import _AsyncHttpClient, _HttpClient
+
+_PROMPTS_PATH = "/api/v1/flowops/v1/prompts/by-name"
+
+
+class PromptsClient:
+    """
+    FlowOps client for fetching versioned prompts at runtime.
+
+    Prefer using the module-level ``getstacklens.prompts.get()`` helper over
+    instantiating this directly.
+    """
+
+    def __init__(self, api_key: str, endpoint: str) -> None:
+        self._http = _HttpClient(api_key=api_key, endpoint=endpoint)
+
+    def get(self, name: str, *, env: str = "production") -> str:
+        """
+        Fetch the active prompt content for the given name and environment.
+
+        Args:
+            name: The prompt name as configured in FlowOps.
+            env:  The environment — ``'dev'``, ``'staging'``, or ``'production'``
+                  (default).
+
+        Returns:
+            The prompt content string.
+
+        Example::
+
+            system_prompt = getstacklens.prompts.get("support-system-prompt", env="production")
+        """
+        resp = self._http.get(f"{_PROMPTS_PATH}/{name}", params={"env": env})
+        return resp["content"]
+
+
+class AsyncPromptsClient:
+    """
+    Async FlowOps client for fetching versioned prompts at runtime.
+
+    Prefer using the module-level ``getstacklens.aprompts.get()`` helper over
+    instantiating this directly.
+    """
+
+    def __init__(self, api_key: str, endpoint: str) -> None:
+        self._http = _AsyncHttpClient(api_key=api_key, endpoint=endpoint)
+
+    async def get(self, name: str, *, env: str = "production") -> str:
+        """
+        Async version of :meth:`PromptsClient.get`.
+
+        Example::
+
+            system_prompt = await getstacklens.aprompts.get("support-system-prompt")
+        """
+        resp = await self._http.get(f"{_PROMPTS_PATH}/{name}", params={"env": env})
+        return resp["content"]

getstacklens/tracer.py

@@ -0,0 +1,306 @@
+"""StackTrace tracing client."""
+
+from __future__ import annotations
+
+import uuid
+from contextlib import asynccontextmanager, contextmanager
+from datetime import datetime, timezone
+from typing import AsyncIterator, Iterator
+
+from ._client import _AsyncHttpClient, _HttpClient
+
+_TRACES_PATH = "/api/v1/stacktrace/v1/traces"
+
+
+class Span:
+    """
+    A single span within a trace.
+
+    Create spans via :func:`getstacklens.start_trace` rather than instantiating directly.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        trace_id: str,
+        span_id: str,
+        parent_span_id: str | None,
+    ) -> None:
+        self._name = name
+        self._trace_id = trace_id
+        self._span_id = span_id
+        self._parent_span_id = parent_span_id
+        self._start = datetime.now(timezone.utc)
+        self._llm: dict | None = None
+        self._attributes: dict[str, str] = {}
+        self._tags: list[str] = []
+        self._status = "ok"
+
+    def set_attribute(self, key: str, value: str) -> "Span":
+        """Attach a key-value attribute to this span."""
+        self._attributes[str(key)] = str(value)
+        return self
+
+    def add_tag(self, *tags: str) -> "Span":
+        """Add one or more string tags to this span."""
+        self._tags.extend(tags)
+        return self
+
+    def set_status(self, status: str) -> "Span":
+        """Set span status: ``'ok'`` (default) or ``'error'``."""
+        self._status = status
+        return self
+
+    def record_llm(
+        self,
+        *,
+        model: str,
+        provider: str,
+        input_tokens: int,
+        output_tokens: int,
+        total_tokens: int | None = None,
+        cost_usd: float = 0.0,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        prompt: str | None = None,
+        completion: str | None = None,
+        is_streaming: bool = False,
+        finish_reason: str | None = None,
+    ) -> "Span":
+        """
+        Record LLM call metadata for this span.
+
+        Example::
+
+            with getstacklens.start_trace("chat") as span:
+                response = openai_client.chat.completions.create(...)
+                span.record_llm(
+                    model="gpt-4o",
+                    provider="openai",
+                    input_tokens=response.usage.prompt_tokens,
+                    output_tokens=response.usage.completion_tokens,
+                )
+        """
+        self._llm = {
+            "model": model,
+            "provider": provider,
+            "inputTokens": input_tokens,
+            "outputTokens": output_tokens,
+            "totalTokens": total_tokens
+            if total_tokens is not None
+            else input_tokens + output_tokens,
+            "estimatedCostUsd": cost_usd,
+            "temperature": temperature,
+            "maxTokens": max_tokens,
+            "promptContent": prompt,
+            "completionContent": completion,
+            "isStreaming": is_streaming,
+            "finishReason": finish_reason,
+        }
+        return self
+
+    def _to_payload(self) -> dict:
+        end = datetime.now(timezone.utc)
+        return {
+            "traceId": self._trace_id,
+            "spanId": self._span_id,
+            "parentSpanId": self._parent_span_id,
+            "name": self._name,
+            "kind": "llm" if self._llm else "internal",
+            "status": self._status,
+            "startTime": self._start.isoformat(),
+            "endTime": end.isoformat(),
+            "attributes": self._attributes,
+            "tags": self._tags,
+            "llmSpan": self._llm,
+        }
+
+
+class Tracer:
+    """
+    StackTrace client.
+
+    Prefer using the module-level :func:`getstacklens.trace` and
+    :func:`getstacklens.start_trace` helpers over instantiating this directly.
+    """
+
+    def __init__(self, api_key: str, endpoint: str) -> None:
+        self._http = _HttpClient(api_key=api_key, endpoint=endpoint)
+
+    def record(
+        self,
+        name: str,
+        *,
+        model: str,
+        provider: str,
+        input_tokens: int,
+        output_tokens: int,
+        total_tokens: int | None = None,
+        cost_usd: float = 0.0,
+        attributes: dict[str, str] | None = None,
+        tags: list[str] | None = None,
+        status: str = "ok",
+        start_time: datetime | None = None,
+        end_time: datetime | None = None,
+    ) -> str:
+        """
+        Send a single LLM span. Returns the trace ID.
+
+        For accurate latency, record ``start_time`` before the LLM call and
+        ``end_time`` after::
+
+            start = datetime.now(timezone.utc)
+            response = client.chat.completions.create(...)
+            tracer.record("chat", model="gpt-4o", provider="openai",
+                          input_tokens=..., output_tokens=...,
+                          start_time=start, end_time=datetime.now(timezone.utc))
+
+        If omitted, both timestamps are set to the moment ``record()`` is called
+        and the span will show 0 ms duration.
+        """
+        trace_id = str(uuid.uuid4())
+        span_id = str(uuid.uuid4())
+        recorded_at = datetime.now(timezone.utc)
+        payload = {
+            "traceId": trace_id,
+            "spanId": span_id,
+            "parentSpanId": None,
+            "name": name,
+            "kind": "llm",
+            "status": status,
+            "startTime": (start_time or recorded_at).isoformat(),
+            "endTime": (end_time or recorded_at).isoformat(),
+            "attributes": attributes or {},
+            "tags": tags or [],
+            "llmSpan": {
+                "model": model,
+                "provider": provider,
+                "inputTokens": input_tokens,
+                "outputTokens": output_tokens,
+                "totalTokens": total_tokens
+                if total_tokens is not None
+                else input_tokens + output_tokens,
+                "estimatedCostUsd": cost_usd,
+                "temperature": None,
+                "maxTokens": None,
+                "promptContent": None,
+                "completionContent": None,
+                "isStreaming": False,
+                "finishReason": None,
+            },
+        }
+        self._http.post(_TRACES_PATH, payload)
+        return trace_id
+
+    @contextmanager
+    def start_trace(self, name: str) -> Iterator[Span]:
+        """
+        Context manager for tracing a multi-step or agent operation.
+
+        Flushes the span to StackLens when the context exits (including on error).
+
+        Example::
+
+            with tracer.start_trace("my-agent-run") as span:
+                response = client.chat.completions.create(...)
+                span.record_llm(model="gpt-4o", provider="openai",
+                                input_tokens=150, output_tokens=200)
+        """
+        trace_id = str(uuid.uuid4())
+        span_id = str(uuid.uuid4())
+        span = Span(name=name, trace_id=trace_id, span_id=span_id, parent_span_id=None)
+        try:
+            yield span
+        except Exception:
+            span.set_status("error")
+            raise
+        finally:
+            self._http.post(_TRACES_PATH, span._to_payload())
+
+
+class AsyncTracer:
+    """
+    Async StackTrace client for use with asyncio / FastAPI / async frameworks.
+
+    Prefer the module-level :func:`getstacklens.atrace` and
+    :func:`getstacklens.astart_trace` helpers over instantiating this directly.
+    """
+
+    def __init__(self, api_key: str, endpoint: str) -> None:
+        self._http = _AsyncHttpClient(api_key=api_key, endpoint=endpoint)
+
+    async def arecord(
+        self,
+        name: str,
+        *,
+        model: str,
+        provider: str,
+        input_tokens: int,
+        output_tokens: int,
+        total_tokens: int | None = None,
+        cost_usd: float = 0.0,
+        attributes: dict[str, str] | None = None,
+        tags: list[str] | None = None,
+        status: str = "ok",
+        start_time: datetime | None = None,
+        end_time: datetime | None = None,
+    ) -> str:
+        """Async version of :meth:`Tracer.record`. Returns the trace ID."""
+        trace_id = str(uuid.uuid4())
+        span_id = str(uuid.uuid4())
+        recorded_at = datetime.now(timezone.utc)
+        payload = {
+            "traceId": trace_id,
+            "spanId": span_id,
+            "parentSpanId": None,
+            "name": name,
+            "kind": "llm",
+            "status": status,
+            "startTime": (start_time or recorded_at).isoformat(),
+            "endTime": (end_time or recorded_at).isoformat(),
+            "attributes": attributes or {},
+            "tags": tags or [],
+            "llmSpan": {
+                "model": model,
+                "provider": provider,
+                "inputTokens": input_tokens,
+                "outputTokens": output_tokens,
+                "totalTokens": total_tokens
+                if total_tokens is not None
+                else input_tokens + output_tokens,
+                "estimatedCostUsd": cost_usd,
+                "temperature": None,
+                "maxTokens": None,
+                "promptContent": None,
+                "completionContent": None,
+                "isStreaming": False,
+                "finishReason": None,
+            },
+        }
+        await self._http.post(_TRACES_PATH, payload)
+        return trace_id
+
+    @asynccontextmanager
+    async def astart_trace(self, name: str) -> AsyncIterator[Span]:
+        """
+        Async context manager for tracing a multi-step or agent operation.
+
+        Flushes the span to StackLens when the context exits (including on error).
+
+        Example::
+
+            async with tracer.astart_trace("my-agent-run") as span:
+                response = await async_openai_client.chat.completions.create(...)
+                span.record_llm(model="gpt-4o", provider="openai",
+                                input_tokens=150, output_tokens=200)
+        """
+        trace_id = str(uuid.uuid4())
+        span_id = str(uuid.uuid4())
+        span = Span(name=name, trace_id=trace_id, span_id=span_id, parent_span_id=None)
+        try:
+            yield span
+        except Exception:
+            span.set_status("error")
+            raise
+        finally:
+            await self._http.post(_TRACES_PATH, span._to_payload())

getstacklens-0.0.1.dist-info/METADATA

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: getstacklens
+Version: 0.0.1
+Summary: Python SDK for StackLens — observability and governance for your AI stack
+Project-URL: Homepage, https://getstacklens.ai
+Project-URL: Documentation, https://getstacklens.ai/docs
+Project-URL: Repository, https://github.com/getstacklens-ai/stacklens-sdk-python
+Project-URL: Bug Tracker, https://github.com/getstacklens-ai/stacklens-sdk-python/issues
+License: StackLens Source-Available License
+        
+        Copyright (c) 2026 StackLens Private Limited. All rights reserved.
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated files (the "Software"), to use and run it
+        for personal or commercial purposes, subject to the following conditions:
+        
+        PERMITTED:
+        - Using and running the Software as-is
+        - Integrating the Software into your own applications
+        - Reading and referencing the source code
+        - Submitting corrections or improvements via pull request to the official
+          repository at https://github.com/getstacklens/stacklens-sdk-python
+        
+        NOT PERMITTED without prior written permission from StackLens Private Limited:
+        - Modifying or creating derivative works based on the Software
+        - Redistributing the Software, in whole or in part
+        - Sublicensing the Software
+        - Selling the Software or incorporating it into a competing product or service
+        - Publishing a fork or modified copy of the Software
+        
+        CONTRIBUTIONS:
+        All contributions submitted via pull request are made under the terms of this
+        license. By submitting a pull request, you agree to transfer copyright of your
+        contribution to StackLens Private Limited and grant StackLens Private Limited the right to use,
+        modify, and publish your contribution under any license.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED. IN NO EVENT SHALL STACKLENS, INC. BE LIABLE FOR ANY CLAIM, DAMAGES,
+        OR OTHER LIABILITY ARISING FROM USE OF THE SOFTWARE.
+License-File: LICENSE
+Keywords: ai,governance,llm,observability,prompt-management,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# stacklens-sdk-python
+
+Python SDK for [StackLens](https://getstacklens.ai) — observability and governance for your AI stack.
+
+Trace LLM calls, fetch versioned prompts, and enforce AI governance policies — in three lines of Python.
+
+## Installation
+
+```bash
+pip install getstacklens
+```
+
+Requires Python 3.9+.
+
+## Quickstart
+
+```python
+import getstacklens
+
+getstacklens.configure(api_key="sl-xxxx")
+getstacklens.trace("my-llm-call", model="gpt-4o", provider="openai", input_tokens=150, output_tokens=200)
+```
+
+Get your API key from the [StackLens dashboard](https://app.getstacklens.ai) under **Settings → API Keys**.
+
+## Tracing LLM calls
+
+### Simple trace (one line)
+
+For accurate latency, record `start_time` before the call and pass it in:
+
+```python
+from datetime import datetime, timezone
+import getstacklens
+
+getstacklens.configure(api_key="sl-xxxx")
+
+start = datetime.now(timezone.utc)
+response = openai_client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Summarise this document."}],
+)
+getstacklens.trace(
+    "chat-completion",
+    model="gpt-4o",
+    provider="openai",
+    input_tokens=response.usage.prompt_tokens,
+    output_tokens=response.usage.completion_tokens,
+    start_time=start,
+)
+```
+
+### Context manager (recommended for agent workflows)
+
+```python
+import openai
+import getstacklens
+
+getstacklens.configure(api_key="sl-xxxx")
+client = openai.OpenAI()
+
+with getstacklens.start_trace("customer-support-agent") as span:
+    response = client.chat.completions.create(
+        model="gpt-4o",
+        messages=[{"role": "user", "content": "How do I reset my password?"}],
+    )
+    span.record_llm(
+        model="gpt-4o",
+        provider="openai",
+        input_tokens=response.usage.prompt_tokens,
+        output_tokens=response.usage.completion_tokens,
+        completion=response.choices[0].message.content,
+    )
+    span.set_attribute("user_id", "u_123")
+    span.add_tag("support", "production")
+```
+
+If an exception is raised inside the context, the span status is automatically set to `error`.
+
+## Fetching versioned prompts (FlowOps)
+
+Manage prompts in the StackLens dashboard, then fetch them at runtime — no deploys needed.
+
+```python
+import getstacklens
+
+getstacklens.configure(api_key="sl-xxxx")
+
+# Fetch the active prompt for the production environment
+system_prompt = getstacklens.prompts.get("support-system-prompt", env="production")
+
+# Use in an LLM call
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[
+        {"role": "system", "content": system_prompt},
+        {"role": "user", "content": user_message},
+    ],
+)
+```
+
+Available environments: `"dev"`, `"staging"`, `"production"` (default).
+
+## Self-hosted deployments
+
+Point the SDK at your own StackLens instance:
+
+```python
+getstacklens.configure(
+    api_key="sl-xxxx",
+    endpoint="https://api.your-domain.com",
+)
+```
+
+See the [self-hosting guide](https://getstacklens.ai/docs/self-hosting) for setup instructions.
+
+## Supported providers
+
+Works with any LLM provider — pass the model and provider name you use:
+
+| Provider | `provider` value |
+|---|---|
+| OpenAI | `"openai"` |
+| Anthropic | `"anthropic"` |
+| Google Gemini | `"gemini"` |
+| Azure OpenAI | `"azure-openai"` |
+| AWS Bedrock | `"bedrock"` |
+| Any other | any string |
+
+## Links
+
+- [Documentation](https://getstacklens.ai/docs)
+- [StackLens Platform](https://getstacklens.ai)
+- [Dashboard](https://app.getstacklens.ai)
+- [GitHub](https://github.com/getstacklens-ai/stacklens-sdk-python)
+- [Report an issue](https://github.com/getstacklens-ai/stacklens-sdk-python/issues)

getstacklens-0.0.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+getstacklens/__init__.py,sha256=3SyL_xckUtM9DNnNJr8XWeC6fL6KqzWzeQsAl2Rs6Bo,10528
+getstacklens/_client.py,sha256=UUR2JQg0etl8vYK7YdJQLVZZaBnJqvSJGO_vH2sDx08,4216
+getstacklens/exceptions.py,sha256=M3Z0G15167NK4eCNuA0yVWFoughT5AjEqXXMzK4nnC8,767
+getstacklens/prompts.py,sha256=Iafs6ESP8yhdNjBNa6yJQOOe4KQcnjc5JplVo2mK39o,1878
+getstacklens/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+getstacklens/tracer.py,sha256=ZFh8JtOs6CmH-7j735-Wg46htLpATF1Xhm1RQd5u4HU,10203
+getstacklens-0.0.1.dist-info/METADATA,sha256=CGtUJP4SMv546oL7e8NacBftM8-TCJfqc4o0tWAy7nI,6663
+getstacklens-0.0.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+getstacklens-0.0.1.dist-info/licenses/LICENSE,sha256=UpKdprvuKX8dASu6LYRCSuLf8NiwLU8QCW0INa3wrZI,1505
+getstacklens-0.0.1.dist-info/RECORD,,

getstacklens-0.0.1.dist-info/WHEEL

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

getstacklens-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,31 @@
+StackLens Source-Available License
+
+Copyright (c) 2026 StackLens Private Limited. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated files (the "Software"), to use and run it
+for personal or commercial purposes, subject to the following conditions:
+
+PERMITTED:
+- Using and running the Software as-is
+- Integrating the Software into your own applications
+- Reading and referencing the source code
+- Submitting corrections or improvements via pull request to the official
+  repository at https://github.com/getstacklens/stacklens-sdk-python
+
+NOT PERMITTED without prior written permission from StackLens Private Limited:
+- Modifying or creating derivative works based on the Software
+- Redistributing the Software, in whole or in part
+- Sublicensing the Software
+- Selling the Software or incorporating it into a competing product or service
+- Publishing a fork or modified copy of the Software
+
+CONTRIBUTIONS:
+All contributions submitted via pull request are made under the terms of this
+license. By submitting a pull request, you agree to transfer copyright of your
+contribution to StackLens Private Limited and grant StackLens Private Limited the right to use,
+modify, and publish your contribution under any license.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL STACKLENS, INC. BE LIABLE FOR ANY CLAIM, DAMAGES,
+OR OTHER LIABILITY ARISING FROM USE OF THE SOFTWARE.