pulse-trace-sdk 0.2.4__tar.gz

pulse_trace_sdk-0.2.4/.gitignore

@@ -0,0 +1,4 @@
+.venv
+.env
+__pycache__/
+*.pyc

pulse_trace_sdk-0.2.4/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: pulse-trace-sdk
+Version: 0.2.4
+Summary: Pulse Python SDK for tracing LLM providers
+Author: Pulse
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.32.0
+Provides-Extra: dev
+Requires-Dist: black>=26.1.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Pulse Python SDK
+
+Python client helpers for Pulse trace ingestion. Wrap your LLM provider SDK (OpenAI, Anthropic) and Pulse automatically captures trace metadata and ships it to your trace-service instance.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install pulse-trace-sdk
+```
+
+For local development:
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+```python
+from openai import OpenAI
+from pulse_sdk import init_pulse, observe, Provider
+
+init_pulse({
+    "api_key": "pulse_sk_...",
+    "api_url": "http://localhost:3000",
+})
+
+client = OpenAI(api_key="your-openai-key")
+observed = observe(client, Provider.OPENAI)
+
+response = observed.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "Hello Pulse"}],
+    pulse_session_id="session-123",
+    pulse_metadata={"feature": "chat"},
+)
+```
+
+To instrument Anthropic:
+
+```python
+from anthropic import Anthropic
+from pulse_sdk import observe, Provider
+
+anthropic_client = Anthropic(api_key="anthropic-key")
+observe(anthropic_client, Provider.ANTHROPIC)
+
+anthropic_client.messages.create(
+    model="claude-3-5-haiku-20241022",
+    max_tokens=300,
+    messages=[{"role": "user", "content": "Summarize"}],
+)
+```
+
+## API
+
+- `init_pulse(config)` – configure API URL, key, batch size, and flush interval. Starts a background worker that periodically flushes traces.
+- `observe(client, provider, options=None)` – wraps the provider SDK and returns the same client instance instrumented with tracing.
+- `flush_buffer()` – (optional) force-send buffered traces, useful before process shutdown.
+- `shutdown()` – stop the background worker and clear buffers.
+
+### Config options
+
+```python
+init_pulse({
+    "api_key": "pulse_sk_...",     # required
+    "api_url": "https://api.example.com",  # default http://localhost:3000
+    "batch_size": 10,               # flush when buffer hits this size
+    "flush_interval": 5000,         # milliseconds between automatic flushes
+    "enabled": True,                # set False to disable tracing
+})
+```
+
+### Pulse specific metadata
+
+All `chat.completions.create` / `messages.create` calls support:
+
+- `pulse_session_id` – associate traces with a session.
+- `pulse_metadata` – arbitrary dictionary merged into trace metadata.
+
+## Requirements
+
+- Python 3.10+
+- `requests`
+- Corresponding provider SDK (`openai`, `anthropic`) for the helpers you use.
+
+## Tests
+
+```bash
+uv run pytest
+```
+
+### Live integration check
+
+To manually exercise the SDK against real providers, run:
+
+```bash
+uv run python tests/test_server.py openai
+uv run python tests/test_server.py anthropic
+```
+
+Set `PULSE_API_KEY` and the relevant provider key (`OPENAI_API_KEY` or `ANTHROPIC_API_KEY`) before running. The script makes a single completion request and relies on `observe()` to push traces to your trace-service instance.

pulse_trace_sdk-0.2.4/README.md

@@ -0,0 +1,104 @@
+# Pulse Python SDK
+
+Python client helpers for Pulse trace ingestion. Wrap your LLM provider SDK (OpenAI, Anthropic) and Pulse automatically captures trace metadata and ships it to your trace-service instance.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install pulse-trace-sdk
+```
+
+For local development:
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+```python
+from openai import OpenAI
+from pulse_sdk import init_pulse, observe, Provider
+
+init_pulse({
+    "api_key": "pulse_sk_...",
+    "api_url": "http://localhost:3000",
+})
+
+client = OpenAI(api_key="your-openai-key")
+observed = observe(client, Provider.OPENAI)
+
+response = observed.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "Hello Pulse"}],
+    pulse_session_id="session-123",
+    pulse_metadata={"feature": "chat"},
+)
+```
+
+To instrument Anthropic:
+
+```python
+from anthropic import Anthropic
+from pulse_sdk import observe, Provider
+
+anthropic_client = Anthropic(api_key="anthropic-key")
+observe(anthropic_client, Provider.ANTHROPIC)
+
+anthropic_client.messages.create(
+    model="claude-3-5-haiku-20241022",
+    max_tokens=300,
+    messages=[{"role": "user", "content": "Summarize"}],
+)
+```
+
+## API
+
+- `init_pulse(config)` – configure API URL, key, batch size, and flush interval. Starts a background worker that periodically flushes traces.
+- `observe(client, provider, options=None)` – wraps the provider SDK and returns the same client instance instrumented with tracing.
+- `flush_buffer()` – (optional) force-send buffered traces, useful before process shutdown.
+- `shutdown()` – stop the background worker and clear buffers.
+
+### Config options
+
+```python
+init_pulse({
+    "api_key": "pulse_sk_...",     # required
+    "api_url": "https://api.example.com",  # default http://localhost:3000
+    "batch_size": 10,               # flush when buffer hits this size
+    "flush_interval": 5000,         # milliseconds between automatic flushes
+    "enabled": True,                # set False to disable tracing
+})
+```
+
+### Pulse specific metadata
+
+All `chat.completions.create` / `messages.create` calls support:
+
+- `pulse_session_id` – associate traces with a session.
+- `pulse_metadata` – arbitrary dictionary merged into trace metadata.
+
+## Requirements
+
+- Python 3.10+
+- `requests`
+- Corresponding provider SDK (`openai`, `anthropic`) for the helpers you use.
+
+## Tests
+
+```bash
+uv run pytest
+```
+
+### Live integration check
+
+To manually exercise the SDK against real providers, run:
+
+```bash
+uv run python tests/test_server.py openai
+uv run python tests/test_server.py anthropic
+```
+
+Set `PULSE_API_KEY` and the relevant provider key (`OPENAI_API_KEY` or `ANTHROPIC_API_KEY`) before running. The script makes a single completion request and relies on `observe()` to push traces to your trace-service instance.

pulse_trace_sdk-0.2.4/pulse_sdk/__init__.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from .config import load_config
+from .providers import observe_anthropic, observe_openai
+from .state import (
+    flush_buffer,
+    reset_state,
+    set_config,
+    start_flush_worker,
+    stop_flush_worker,
+)
+from .types import ObserveOptions, Provider, PulseConfig
+
+
+def init_pulse(config: PulseConfig) -> None:
+    resolved = load_config(config)
+    set_config(resolved)
+    start_flush_worker()
+
+
+def shutdown() -> None:
+    stop_flush_worker()
+    reset_state()
+
+
+def observe(client, provider: Provider, options: ObserveOptions | None = None):
+    if provider in (Provider.OPENAI, Provider.OPENROUTER):
+        return observe_openai(client, provider, options)
+    if provider == Provider.ANTHROPIC:
+        return observe_anthropic(client, options)
+    raise ValueError(f"Unsupported provider: {provider}")
+
+
+__all__ = [
+    "init_pulse",
+    "shutdown",
+    "observe",
+    "flush_buffer",
+    "Provider",
+    "ObserveOptions",
+]

pulse_trace_sdk-0.2.4/pulse_sdk/config.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from .types import PulseConfig
+
+
+@dataclass(frozen=True)
+class ResolvedConfig:
+    api_key: str
+    api_url: str
+    batch_size: int
+    flush_interval: int
+    enabled: bool
+
+
+DEFAULT_API_URL = "http://localhost:3000"
+DEFAULT_BATCH_SIZE = 10
+DEFAULT_FLUSH_INTERVAL = 5000  # ms
+DEFAULT_ENABLED = True
+
+
+class ConfigError(ValueError):
+    """Raised when the user passes invalid configuration."""
+
+
+def load_config(config: PulseConfig) -> ResolvedConfig:
+    api_key = config.get("api_key")
+    if not api_key:
+        raise ConfigError("Pulse SDK: api_key is required")
+
+    if not api_key.startswith("pulse_sk_"):
+        raise ConfigError("Pulse SDK: api_key must start with 'pulse_sk_'")
+
+    batch_size = int(config.get("batch_size", DEFAULT_BATCH_SIZE))
+    if batch_size < 1 or batch_size > 100:
+        raise ConfigError("Pulse SDK: batch_size must be between 1 and 100")
+
+    flush_interval = int(config.get("flush_interval", DEFAULT_FLUSH_INTERVAL))
+    if flush_interval < 1000:
+        raise ConfigError("Pulse SDK: flush_interval must be at least 1000ms")
+
+    api_url = config.get("api_url", DEFAULT_API_URL)
+    enabled = bool(config.get("enabled", DEFAULT_ENABLED))
+
+    return ResolvedConfig(
+        api_key=api_key,
+        api_url=api_url,
+        batch_size=batch_size,
+        flush_interval=flush_interval,
+        enabled=enabled,
+    )

pulse_trace_sdk-0.2.4/pulse_sdk/normalize.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from .types import NormalizedResponse
+
+try:
+    from openai.types.chat import ChatCompletion
+except Exception:
+    ChatCompletion = object  # type: ignore
+
+try:
+    from anthropic.types import Message
+except Exception:
+    Message = object  # type: ignore
+
+
+ANTHROPIC_STOP_REASON_MAP = {
+    "end_turn": "stop",
+    "max_tokens": "length",
+    "stop_sequence": "stop",
+    "tool_use": "tool_calls",
+}
+
+
+def normalize_openai_response(response: "ChatCompletion") -> NormalizedResponse:
+    choice = response.choices[0] if response.choices else None
+    content = getattr(choice.message, "content", None) if choice else None
+    usage = getattr(response, "usage", None)
+    input_tokens = getattr(usage, "prompt_tokens", None)
+    output_tokens = getattr(usage, "completion_tokens", None)
+    finish_reason = getattr(choice, "finish_reason", None)
+    model = getattr(response, "model", "unknown")
+    provider_id = getattr(response, "id", None)
+
+    cost_cents = None
+    cost_value = getattr(response, "cost", None)
+    if isinstance(cost_value, (int, float)):
+        cost_cents = cost_value * 100
+
+    return NormalizedResponse(
+        model=model,
+        content=content if isinstance(content, str) else None,
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        finish_reason=finish_reason,
+        cost_cents=cost_cents,
+        provider_request_id=provider_id,
+    )
+
+
+def normalize_anthropic_response(response: "Message") -> NormalizedResponse:
+    content_parts = []
+    for block in getattr(response, "content", []) or []:
+        if getattr(block, "type", None) == "text":
+            text_value = getattr(block, "text", None)
+            if text_value:
+                content_parts.append(text_value)
+    content = "".join(content_parts) if content_parts else None
+
+    usage = getattr(response, "usage", None)
+    input_tokens = getattr(usage, "input_tokens", None)
+    output_tokens = getattr(usage, "output_tokens", None)
+
+    stop_reason = getattr(response, "stop_reason", None)
+    finish_reason = ANTHROPIC_STOP_REASON_MAP.get(stop_reason, stop_reason)
+    model = getattr(response, "model", "unknown")
+
+    return NormalizedResponse(
+        model=model,
+        content=content,
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        finish_reason=finish_reason,
+    )

pulse_trace_sdk-0.2.4/pulse_sdk/pricing.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from typing import Dict, Optional
+
+ModelPricing = Dict[str, float]
+
+MODEL_PRICING: Dict[str, ModelPricing] = {
+    "gpt-5.1": {"input": 125, "output": 1000},
+    "gpt-5": {"input": 150, "output": 1000},
+    "gpt-5-mini": {"input": 90, "output": 400},
+    "gpt-5-nano": {"input": 20, "output": 100},
+    "gpt-5.1-chat-latest": {"input": 125, "output": 1000},
+    "gpt-5-chat-latest": {"input": 150, "output": 1000},
+    "gpt-5.1-codex-max": {"input": 250, "output": 1250},
+    "gpt-5.1-codex": {"input": 125, "output": 600},
+    "gpt-5-codex": {"input": 145, "output": 600},
+    "gpt-5.1-codex-mini": {"input": 40, "output": 160},
+    "codex-mini-latest": {"input": 40, "output": 160},
+    "gpt-5-pro": {"input": 250, "output": 1200},
+    "gpt-5-search-api": {"input": 400, "output": 1600},
+    "gpt-4.1": {"input": 250, "output": 1000},
+    "gpt-4.1-mini": {"input": 100, "output": 400},
+    "gpt-4.1-nano": {"input": 15, "output": 60},
+    "gpt-4o": {"input": 250, "output": 1000},
+    "gpt-4o-2024-05-13": {"input": 250, "output": 1000},
+    "gpt-4o-mini": {"input": 15, "output": 60},
+    "gpt-4o-mini-search-preview": {"input": 500, "output": 2000},
+    "gpt-4o-search-preview": {"input": 1000, "output": 4000},
+    "gpt-realtime": {"input": 500, "output": 2000},
+    "gpt-realtime-mini": {"input": 250, "output": 1000},
+    "gpt-4o-realtime-preview": {"input": 500, "output": 2000},
+    "gpt-4o-mini-realtime-preview": {"input": 15, "output": 60},
+    "gpt-audio": {"input": 250, "output": 1000},
+    "gpt-audio-mini": {"input": 60, "output": 250},
+    "gpt-4o-audio-preview": {"input": 250, "output": 1000},
+    "gpt-4o-mini-audio-preview": {"input": 15, "output": 60},
+    "o1": {"input": 1500, "output": 6000},
+    "o1-pro": {"input": 1800, "output": 7200},
+    "o1-mini": {"input": 350, "output": 1400},
+    "o3-pro": {"input": 1500, "output": 6000},
+    "o3": {"input": 600, "output": 2400},
+    "o3-mini": {"input": 200, "output": 800},
+    "o3-deep-research": {"input": 2500, "output": 10000},
+    "o4-mini": {"input": 300, "output": 1200},
+    "o4-mini-deep-research": {"input": 500, "output": 2000},
+    "computer-use-preview": {"input": 500, "output": 0},
+    "gpt-image-1": {"input": 5000, "output": 0},
+    "gpt-image-1-mini": {"input": 2000, "output": 0},
+    "gpt-4-turbo": {"input": 1000, "output": 3000},
+    "gpt-3.5-turbo": {"input": 50, "output": 150},
+    "claude-opus-4-5-20251101": {"input": 500, "output": 2500},
+    "claude-opus-4-1-20250805": {"input": 1500, "output": 7500},
+    "claude-opus-4-20250514": {"input": 1500, "output": 7500},
+    "claude-sonnet-4-5-20250929": {"input": 300, "output": 1500},
+    "claude-sonnet-4-20250514": {"input": 300, "output": 1500},
+    "claude-3-7-sonnet-20250219": {"input": 300, "output": 1500},
+    "claude-3-sonnet-20240229": {"input": 300, "output": 1500},
+    "claude-3-5-sonnet-20241022": {"input": 300, "output": 1500},
+    "claude-haiku-4-5-20251001": {"input": 100, "output": 500},
+    "claude-3-5-haiku-20241022": {"input": 80, "output": 400},
+    "claude-3-haiku-20240307": {"input": 25, "output": 125},
+    "claude-3-opus-20240229": {"input": 1500, "output": 7500},
+}
+
+MODEL_ALIASES: Dict[str, str] = {
+    "gpt-5.1-latest": "gpt-5.1",
+    "gpt-5-latest": "gpt-5",
+    "gpt-5-mini-latest": "gpt-5-mini",
+    "gpt-5-nano-latest": "gpt-5-nano",
+    "gpt-5.1-codex-latest": "gpt-5.1-codex",
+    "gpt-5-codex-latest": "gpt-5-codex",
+    "gpt-5.1-codex-mini-latest": "gpt-5.1-codex-mini",
+    "gpt-4.1-latest": "gpt-4.1",
+    "gpt-4.1-mini-latest": "gpt-4.1-mini",
+    "gpt-4.1-nano-latest": "gpt-4.1-nano",
+    "gpt-4o-2024-11-20": "gpt-4o",
+    "gpt-4o-2024-08-06": "gpt-4o",
+    "gpt-4o-mini-2024-07-18": "gpt-4o-mini",
+    "gpt-4-turbo-2024-04-09": "gpt-4-turbo",
+    "gpt-4-turbo-preview": "gpt-4-turbo",
+    "gpt-3.5-turbo-0125": "gpt-3.5-turbo",
+    "gpt-3.5-turbo-1106": "gpt-3.5-turbo",
+    "claude-3-5-sonnet": "claude-3-5-sonnet-20241022",
+    "claude-3.5-sonnet": "claude-3-5-sonnet-20241022",
+    "claude-3-sonnet": "claude-3-sonnet-20240229",
+    "claude-3.0-sonnet": "claude-3-sonnet-20240229",
+    "claude-3-5-haiku": "claude-3-5-haiku-20241022",
+    "claude-3.5-haiku": "claude-3-5-haiku-20241022",
+    "claude-3-opus": "claude-3-opus-20240229",
+    "claude-opus-4-5": "claude-opus-4-5-20251101",
+    "claude-opus-4.5": "claude-opus-4-5-20251101",
+    "claude-opus-4-1": "claude-opus-4-1-20250805",
+    "claude-opus-4.1": "claude-opus-4-1-20250805",
+    "claude sonnet": "claude-3-sonnet-20240229",
+}
+
+
+def _resolve_model(model: str) -> Optional[ModelPricing]:
+    if model in MODEL_PRICING:
+        return MODEL_PRICING[model]
+    alias = MODEL_ALIASES.get(model)
+    if alias and alias in MODEL_PRICING:
+        return MODEL_PRICING[alias]
+    return None
+
+
+def calculate_cost(
+    model: str, input_tokens: int, output_tokens: int
+) -> Optional[float]:
+    pricing = _resolve_model(model)
+    if not pricing:
+        return None
+
+    cost = 0.0
+    cost += (input_tokens * pricing["input"]) / 1_000_000
+    cost += (output_tokens * pricing["output"]) / 1_000_000
+    return round(cost, 6)

pulse_trace_sdk-0.2.4/pulse_sdk/providers/__init__.py

@@ -0,0 +1,4 @@
+from .anthropic import observe_anthropic
+from .openai import observe_openai
+
+__all__ = ["observe_openai", "observe_anthropic"]

pulse_trace_sdk-0.2.4/pulse_sdk/providers/anthropic.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import copy
+import time
+from typing import Any, Dict
+
+from ..normalize import normalize_anthropic_response
+from ..state import add_to_buffer, is_enabled
+from ..trace import (
+    build_error_trace,
+    build_trace,
+    extract_pulse_params,
+    resolve_trace_metadata,
+)
+from ..types import ObserveOptions, Provider
+
+
+class AnthropicIntegrationError(RuntimeError):
+    pass
+
+
+def observe_anthropic(client: Any, options: ObserveOptions | None = None) -> Any:
+    try:
+        import anthropic  # noqa: F401
+    except ImportError as exc:
+        raise AnthropicIntegrationError(
+            "anthropic package is required to observe Anthropic clients"
+        ) from exc
+
+    messages = getattr(client, "messages", None)
+    if messages is None or not hasattr(messages, "create"):
+        raise AnthropicIntegrationError("Client is missing messages.create")
+
+    original_create = messages.create
+
+    def wrapped_create(*args: Any, **kwargs: Any):
+        if not is_enabled():
+            return original_create(*args, **kwargs)
+
+        if args:
+            return original_create(*args, **kwargs)
+
+        clean_payload, pulse_session_id, pulse_metadata = extract_pulse_params(kwargs)
+        request_payload: Dict[str, Any] = copy.deepcopy(clean_payload)
+
+        observe_session = options.session_id if options else None
+        observe_metadata = options.metadata if options else None
+        session_id, metadata = resolve_trace_metadata(
+            observe_session,
+            observe_metadata,
+            pulse_session_id,
+            pulse_metadata,
+        )
+
+        start = time.perf_counter()
+        try:
+            response = original_create(**clean_payload)
+        except Exception as exc:
+            latency = (time.perf_counter() - start) * 1000
+            trace = build_error_trace(
+                request_payload,
+                exc,
+                Provider.ANTHROPIC,
+                latency,
+                session_id,
+                metadata,
+            )
+            add_to_buffer(trace)
+            raise
+
+        latency = (time.perf_counter() - start) * 1000
+        normalized = normalize_anthropic_response(response)
+        trace = build_trace(
+            request_payload,
+            normalized,
+            Provider.ANTHROPIC,
+            latency,
+            session_id,
+            metadata,
+        )
+        add_to_buffer(trace)
+        return response
+
+    messages.create = wrapped_create  # type: ignore[assignment]
+    return client

pulse_trace_sdk-0.2.4/pulse_sdk/providers/openai.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import copy
+import time
+from typing import Any, Dict
+
+from ..normalize import normalize_openai_response
+from ..state import add_to_buffer, is_enabled
+from ..trace import (
+    build_error_trace,
+    build_trace,
+    extract_pulse_params,
+    resolve_trace_metadata,
+)
+from ..types import ObserveOptions, Provider
+
+
+class OpenAIIntegrationError(RuntimeError):
+    pass
+
+
+def observe_openai(
+    client: Any, provider: Provider, options: ObserveOptions | None = None
+) -> Any:
+    if provider not in (Provider.OPENAI, Provider.OPENROUTER):
+        raise ValueError("Provider must be openai or openrouter for observe_openai")
+
+    try:
+        import openai  # noqa: F401  # ensure dependency is available
+    except ImportError as exc:
+        raise OpenAIIntegrationError(
+            "openai package is required to observe OpenAI clients"
+        ) from exc
+
+    chat = getattr(client, "chat", None)
+    completions = getattr(chat, "completions", None)
+    if completions is None or not hasattr(completions, "create"):
+        raise OpenAIIntegrationError("Client is missing chat.completions.create")
+
+    original_create = completions.create
+
+    def wrapped_create(*args: Any, **kwargs: Any):
+        if not is_enabled():
+            return original_create(*args, **kwargs)
+
+        if args:
+            # openai-python uses keyword-only API. Fall back if user passed args.
+            return original_create(*args, **kwargs)
+
+        clean_payload, pulse_session_id, pulse_metadata = extract_pulse_params(kwargs)
+        request_payload: Dict[str, Any] = copy.deepcopy(clean_payload)
+
+        observe_session = options.session_id if options else None
+        observe_metadata = options.metadata if options else None
+        session_id, metadata = resolve_trace_metadata(
+            observe_session,
+            observe_metadata,
+            pulse_session_id,
+            pulse_metadata,
+        )
+
+        start = time.perf_counter()
+        try:
+            response = original_create(**clean_payload)
+        except Exception as exc:
+            latency = (time.perf_counter() - start) * 1000
+            trace = build_error_trace(
+                request_payload,
+                exc,
+                provider,
+                latency,
+                session_id,
+                metadata,
+            )
+            add_to_buffer(trace)
+            raise
+
+        latency = (time.perf_counter() - start) * 1000
+        normalized = normalize_openai_response(response)
+        trace = build_trace(
+            request_payload,
+            normalized,
+            provider,
+            latency,
+            session_id,
+            metadata,
+        )
+        add_to_buffer(trace)
+        return response
+
+    completions.create = wrapped_create  # type: ignore[assignment]
+    return client

pulse_trace_sdk-0.2.4/pulse_sdk/state.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import threading
+import time
+from typing import List
+
+from .config import ResolvedConfig
+from .transport import send_traces
+from .types import Trace
+
+_config: ResolvedConfig | None = None
+_buffer: List[Trace] = []
+_buffer_lock = threading.Lock()
+_flush_thread: threading.Thread | None = None
+_stop_event: threading.Event | None = None
+
+
+def set_config(config: ResolvedConfig) -> None:
+    global _config
+    _config = config
+
+
+def get_config() -> ResolvedConfig:
+    if _config is None:
+        raise RuntimeError("Pulse SDK: init_pulse() must be called before use")
+    return _config
+
+
+def is_enabled() -> bool:
+    return bool(_config and _config.enabled)
+
+
+def add_to_buffer(trace: Trace) -> None:
+    if not is_enabled():
+        return
+
+    with _buffer_lock:
+        _buffer.append(trace)
+        threshold = _config.batch_size if _config else 0
+        should_flush = len(_buffer) >= threshold > 0
+
+    if should_flush:
+        flush_buffer()
+
+
+def flush_buffer() -> None:
+    if not is_enabled():
+        return
+
+    traces: List[Trace]
+    with _buffer_lock:
+        if not _buffer:
+            return
+        traces = list(_buffer)
+        _buffer.clear()
+
+    cfg = get_config()
+    try:
+        send_traces(cfg.api_url, cfg.api_key, traces)
+    except Exception as exc:
+        print(f"Pulse SDK: failed to send traces: {exc}")
+
+
+def _flush_loop(interval_ms: int, stop_event: threading.Event) -> None:
+    interval = max(interval_ms / 1000.0, 1.0)
+    while not stop_event.wait(interval):
+        flush_buffer()
+
+
+def start_flush_worker() -> None:
+    global _flush_thread, _stop_event
+
+    if not is_enabled():
+        return
+
+    stop_flush_worker()
+    cfg = get_config()
+    stop_event = threading.Event()
+    thread = threading.Thread(
+        target=_flush_loop,
+        args=(cfg.flush_interval, stop_event),
+        name="pulse-sdk-flush",
+        daemon=True,
+    )
+    _stop_event = stop_event
+    _flush_thread = thread
+    thread.start()
+
+
+def stop_flush_worker() -> None:
+    global _flush_thread, _stop_event
+
+    if _stop_event:
+        _stop_event.set()
+    if _flush_thread and _flush_thread.is_alive():
+        _flush_thread.join(timeout=1)
+    _stop_event = None
+    _flush_thread = None
+
+
+def reset_state() -> None:
+    global _buffer
+    stop_flush_worker()
+    with _buffer_lock:
+        _buffer = []

pulse_trace_sdk-0.2.4/pulse_sdk/trace.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import copy
+import datetime
+import time
+import uuid
+from typing import Any, Dict, Optional
+
+from .pricing import calculate_cost
+from .types import NormalizedResponse, Provider, Trace, TraceStatus
+
+
+def generate_trace_id() -> str:
+    return str(uuid.uuid4())
+
+
+def current_timestamp() -> str:
+    return datetime.datetime.utcnow().replace(tzinfo=datetime.timezone.utc).isoformat()
+
+
+def extract_pulse_params(
+    payload: Dict[str, Any],
+) -> tuple[Dict[str, Any], Optional[str], Optional[Dict[str, Any]]]:
+    clean = copy.deepcopy(payload)
+    session = None
+    metadata = None
+
+    for key in ("pulse_session_id", "pulseSessionId"):
+        if key in clean:
+            session = clean.pop(key)
+            break
+
+    for key in ("pulse_metadata", "pulseMetadata"):
+        if key in clean:
+            metadata = clean.pop(key)
+            break
+
+    return clean, session, metadata  # type: ignore[return-value]
+
+
+def resolve_trace_metadata(
+    observe_session: Optional[str],
+    observe_metadata: Optional[Dict[str, Any]],
+    pulse_session: Optional[str],
+    pulse_metadata: Optional[Dict[str, Any]],
+) -> tuple[Optional[str], Optional[Dict[str, Any]]]:
+    session_id = pulse_session or observe_session
+    metadata = observe_metadata.copy() if observe_metadata else None
+    if pulse_metadata:
+        metadata = {**(metadata or {}), **pulse_metadata}
+    return session_id, metadata
+
+
+def build_trace(
+    request: Dict[str, Any],
+    response: Optional[NormalizedResponse],
+    provider: Provider,
+    latency_ms: float,
+    session_id: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+) -> Trace:
+    trace: Trace = {
+        "trace_id": generate_trace_id(),
+        "timestamp": current_timestamp(),
+        "provider": provider.value,
+        "model_requested": str(request.get("model", "unknown")),
+        "request_body": request,
+        "latency_ms": int(round(latency_ms)),
+        "status": TraceStatus.SUCCESS.value if response else TraceStatus.ERROR.value,
+    }
+
+    if response:
+        trace["model_used"] = response.model
+        trace["response_body"] = {
+            "content": response.content,
+            "inputTokens": response.input_tokens,
+            "outputTokens": response.output_tokens,
+            "finishReason": response.finish_reason,
+            "model": response.model,
+        }
+        trace["input_tokens"] = response.input_tokens
+        trace["output_tokens"] = response.output_tokens
+        trace["output_text"] = response.content
+        trace["finish_reason"] = response.finish_reason
+        if response.provider_request_id:
+            trace["provider_request_id"] = response.provider_request_id
+
+        if response.cost_cents is not None:
+            trace["cost_cents"] = response.cost_cents
+        elif response.input_tokens is not None and response.output_tokens is not None:
+            calculated = calculate_cost(
+                response.model, response.input_tokens, response.output_tokens
+            )
+            if calculated is not None:
+                trace["cost_cents"] = calculated
+    else:
+        trace["status"] = TraceStatus.ERROR.value
+
+    if session_id:
+        trace["session_id"] = session_id
+    if metadata:
+        trace["metadata"] = metadata
+
+    return trace
+
+
+def build_error_trace(
+    request: Dict[str, Any],
+    error: Exception,
+    provider: Provider,
+    latency_ms: float,
+    session_id: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+) -> Trace:
+    trace = build_trace(request, None, provider, latency_ms, session_id, metadata)
+    trace["status"] = TraceStatus.ERROR.value
+    trace["error"] = {
+        "name": error.__class__.__name__,
+        "message": str(error),
+    }
+    return trace

pulse_trace_sdk-0.2.4/pulse_sdk/transport.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import json
+from typing import List
+
+import requests
+
+from .types import Trace
+
+DEFAULT_TIMEOUT = 10  # seconds
+
+
+def send_traces(api_url: str, api_key: str, traces: List[Trace]) -> None:
+    if not traces:
+        return
+
+    url = f"{api_url.rstrip('/')}/v1/traces/async"
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+    }
+    response = requests.post(
+        url, headers=headers, data=json.dumps(traces), timeout=DEFAULT_TIMEOUT
+    )
+    if not response.ok:
+        raise RuntimeError(
+            f"Pulse SDK: failed to send traces ({response.status_code}): {response.text}"
+        )

pulse_trace_sdk-0.2.4/pulse_sdk/types.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Dict, Optional, TypedDict
+
+
+class Provider(str, Enum):
+    OPENAI = "openai"
+    OPENROUTER = "openrouter"
+    ANTHROPIC = "anthropic"
+
+
+class TraceStatus(str, Enum):
+    SUCCESS = "success"
+    ERROR = "error"
+
+
+class Trace(TypedDict, total=False):
+    trace_id: str
+    timestamp: str
+    provider: str
+    model_requested: str
+    model_used: Optional[str]
+    provider_request_id: Optional[str]
+    request_body: Dict[str, Any]
+    response_body: Dict[str, Any]
+    input_tokens: Optional[int]
+    output_tokens: Optional[int]
+    output_text: Optional[str]
+    finish_reason: Optional[str]
+    status: str
+    error: Dict[str, Any]
+    cost_cents: Optional[float]
+    latency_ms: int
+    session_id: Optional[str]
+    metadata: Dict[str, Any]
+
+
+class PulseConfig(TypedDict, total=False):
+    api_key: str
+    api_url: str
+    batch_size: int
+    flush_interval: int
+    enabled: bool
+
+
+@dataclass
+class ObserveOptions:
+    session_id: Optional[str] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class NormalizedResponse:
+    model: str
+    content: Optional[str]
+    input_tokens: Optional[int]
+    output_tokens: Optional[int]
+    finish_reason: Optional[str]
+    cost_cents: Optional[float] = None
+    provider_request_id: Optional[str] = None

pulse_trace_sdk-0.2.4/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pulse-trace-sdk"
+version = "0.2.4"
+description = "Pulse Python SDK for tracing LLM providers"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+  { name = "Pulse" }
+]
+dependencies = [
+  "requests>=2.32.0",
+]
+license = { text = "MIT" }
+
+[tool.hatch.build]
+packages = ["src/pulse_sdk"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pulse_sdk"]
+exclude = [
+  "src/pulse_sdk/__pycache__",
+  "**/*.pyc",
+]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/pulse_sdk",
+  "README.md",
+  "pyproject.toml",
+]
+exclude = [
+  "tests",
+  "**/__pycache__",
+  "**/*.pyc",
+]
+
+[dependency-groups]
+dev = [
+    "anthropic>=0.79.0",
+    "openai>=2.20.0",
+    "pytest>=9.0.2",
+    "python-dotenv>=1.0.1",
+    "fastapi>=0.115.5",
+    "uvicorn>=0.32.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "black>=26.1.0",
+  "pytest>=8.3.0",
+]