retrace-sdk 0.1.3__tar.gz

retrace_sdk-0.1.3/.gitignore

@@ -0,0 +1,16 @@
+node_modules/
+dist/
+.env
+.env.local
+.env.staging
+.env.production
+*.pyc
+__pycache__/
+.turbo/
+.next/
+.firecrawl/
+.vercel/
+.fly/
+.source/
+coverage/
+.husky/_

retrace_sdk-0.1.3/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: retrace-sdk
+Version: 0.1.3
+Summary: Record, replay, fork & share AI agent executions
+Project-URL: Homepage, https://retrace.yashbogam.me
+Project-URL: Repository, https://github.com/yash1511-bogam/retrace
+Author: Yash Bogam
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.32.0
+Requires-Dist: websocket-client>=1.9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: gemini
+Requires-Dist: google-genai>=1.52.0; extra == 'gemini'
+Description-Content-Type: text/markdown
+
+# retrace-sdk
+
+The execution replay engine for AI agents. Record every LLM call, tool invocation, and error your AI agent makes. Replay step-by-step. Fork from any point. Share interactive traces via URL.
+
+## Install
+
+```bash
+pip install retrace-sdk
+```
+
+## Quick Start
+
+```python
+from retrace_sdk import configure, record
+
+configure(api_key="rt_live_...")
+
+@record(name="my-agent")
+def run_agent(prompt: str):
+    response = client.chat.completions.create(
+        model="gpt-4o",
+        messages=[{"role": "user", "content": prompt}]
+    )
+    return response.choices[0].message.content
+
+run_agent("What is quantum computing?")
+```
+
+## Features
+
+- **Record** — One decorator captures every LLM call, tool call, and error
+- **Replay** — Step through executions with play/pause/speed controls
+- **Fork** — Branch from any step, modify input, watch a new path diverge
+- **Share** — Publish traces as shareable "tapes" with interactive playback
+
+## Links
+
+- [Documentation](https://retrace.yashbogam.me/docs)
+- [GitHub](https://github.com/yash1511-bogam/retrace)

retrace_sdk-0.1.3/README.md

@@ -0,0 +1,39 @@
+# retrace-sdk
+
+The execution replay engine for AI agents. Record every LLM call, tool invocation, and error your AI agent makes. Replay step-by-step. Fork from any point. Share interactive traces via URL.
+
+## Install
+
+```bash
+pip install retrace-sdk
+```
+
+## Quick Start
+
+```python
+from retrace_sdk import configure, record
+
+configure(api_key="rt_live_...")
+
+@record(name="my-agent")
+def run_agent(prompt: str):
+    response = client.chat.completions.create(
+        model="gpt-4o",
+        messages=[{"role": "user", "content": prompt}]
+    )
+    return response.choices[0].message.content
+
+run_agent("What is quantum computing?")
+```
+
+## Features
+
+- **Record** — One decorator captures every LLM call, tool call, and error
+- **Replay** — Step through executions with play/pause/speed controls
+- **Fork** — Branch from any step, modify input, watch a new path diverge
+- **Share** — Publish traces as shareable "tapes" with interactive playback
+
+## Links
+
+- [Documentation](https://retrace.yashbogam.me/docs)
+- [GitHub](https://github.com/yash1511-bogam/retrace)

retrace_sdk-0.1.3/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "retrace-sdk"
+version = "0.1.3"
+description = "Record, replay, fork & share AI agent executions"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name = "Yash Bogam"}]
+dependencies = [
+    "websocket-client>=1.9.0",
+    "requests>=2.32.0",
+]
+
+[project.urls]
+Homepage = "https://retrace.yashbogam.me"
+Repository = "https://github.com/yash1511-bogam/retrace"
+
+[project.optional-dependencies]
+gemini = ["google-genai>=1.52.0"]
+dev = ["pytest>=8.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/retrace"]

retrace_sdk-0.1.3/src/retrace/__init__.py

@@ -0,0 +1,12 @@
+from .config import configure, get_config
+from .recorder import record, TraceRecorder
+from .trace import Span, Trace, SpanType, TraceStatus
+from .interceptors.gemini import install_gemini_interceptor, uninstall_gemini_interceptor
+
+__version__ = "0.1.0"
+__all__ = [
+    "configure", "get_config",
+    "record", "TraceRecorder",
+    "Span", "Trace", "SpanType", "TraceStatus",
+    "install_gemini_interceptor", "uninstall_gemini_interceptor",
+]

retrace_sdk-0.1.3/src/retrace/config.py

@@ -0,0 +1,52 @@
+import logging
+import os
+from dataclasses import dataclass, field
+
+logger = logging.getLogger("retrace")
+
+
+@dataclass
+class RetraceConfig:
+    api_key: str = ""
+    base_url: str = ""
+    project_id: str | None = None
+    ws_url: str = ""
+    flush_interval: float = 2.0
+    enabled: bool = True
+
+    def __post_init__(self):
+        if not self.api_key:
+            self.api_key = os.environ.get("RETRACE_API_KEY", "")
+        if not self.base_url:
+            self.base_url = os.environ.get("RETRACE_BASE_URL", "http://localhost:3001")
+        if not self.project_id:
+            self.project_id = os.environ.get("RETRACE_PROJECT_ID") or None
+        if not self.ws_url:
+            self.ws_url = self.base_url.replace("https://", "wss://").replace("http://", "ws://")
+        enabled_env = os.environ.get("RETRACE_ENABLED", "true").lower()
+        if enabled_env in ("false", "0", "no"):
+            self.enabled = False
+
+
+_config: RetraceConfig | None = None
+
+
+def get_config() -> RetraceConfig:
+    global _config
+    if _config is None:
+        _config = RetraceConfig()
+    return _config
+
+
+def configure(**kwargs) -> RetraceConfig:
+    global _config
+    if _config is None:
+        _config = RetraceConfig(**kwargs)
+    else:
+        for k, v in kwargs.items():
+            setattr(_config, k, v)
+        if "base_url" in kwargs and "ws_url" not in kwargs:
+            _config.ws_url = _config.base_url.replace("https://", "wss://").replace("http://", "ws://")
+    if _config.api_key and not _config.api_key.startswith("rt_live_"):
+        logger.warning("API key does not start with 'rt_live_'. This may be invalid.")
+    return _config

retrace_sdk-0.1.3/src/retrace/interceptors/__init__.py

@@ -0,0 +1,3 @@
+from .gemini import install_gemini_interceptor, uninstall_gemini_interceptor
+
+__all__ = ["install_gemini_interceptor", "uninstall_gemini_interceptor"]

retrace_sdk-0.1.3/src/retrace/interceptors/gemini.py

@@ -0,0 +1,92 @@
+"""Gemini interceptor for Retrace Python SDK."""
+import time
+import uuid
+from typing import Callable
+
+_original_generate = None
+_installed = False
+_on_span = None
+
+PRICING = {
+    "gemini-3.1-pro-preview": (2.0, 12.0),
+    "gemini-2.5-pro": (1.25, 10.0),
+    "gemini-2.5-flash": (0.15, 0.60),
+    "gemini-2.0-flash": (0.10, 0.40),
+}
+
+
+def _calc_cost(model: str, input_tokens: int, output_tokens: int) -> float:
+    p = PRICING.get(model, (0, 0))
+    return (input_tokens * p[0] + output_tokens * p[1]) / 1_000_000
+
+
+def install_gemini_interceptor(on_span=None):
+    global _original_generate, _installed, _on_span
+    if _installed:
+        if on_span:
+            _on_span = on_span
+        return
+
+    try:
+        from google import genai
+    except ImportError:
+        return
+
+    _on_span = on_span
+    _original_generate = genai.models.Models.generate_content
+
+    def patched_generate(self, *args, **kwargs):
+        model = kwargs.get("model", args[0] if args else "unknown")
+        contents = kwargs.get("contents", args[1] if len(args) > 1 else None)
+        span_id = str(uuid.uuid4())
+        start = time.time()
+
+        try:
+            result = _original_generate(self, *args, **kwargs)
+            duration_ms = int((time.time() - start) * 1000)
+            input_tokens = getattr(getattr(result, "usage_metadata", None), "prompt_token_count", 0) or 0
+            output_tokens = getattr(getattr(result, "usage_metadata", None), "candidates_token_count", 0) or 0
+
+            if _on_span:
+                _on_span({
+                    "id": span_id,
+                    "span_type": "llm_call",
+                    "name": "retrace.ai.generate",
+                    "model": model,
+                    "input": str(contents)[:2000] if contents else None,
+                    "output": getattr(result, "text", "")[:2000],
+                    "input_tokens": input_tokens,
+                    "output_tokens": output_tokens,
+                    "cost": _calc_cost(model, input_tokens, output_tokens),
+                    "duration_ms": duration_ms,
+                })
+            return result
+        except Exception as e:
+            duration_ms = int((time.time() - start) * 1000)
+            if _on_span:
+                _on_span({
+                    "id": span_id,
+                    "span_type": "llm_call",
+                    "name": "retrace.ai.generate",
+                    "model": model,
+                    "input": str(contents)[:2000] if contents else None,
+                    "duration_ms": duration_ms,
+                    "error": str(e),
+                })
+            raise
+
+    genai.models.Models.generate_content = patched_generate
+    _installed = True
+
+
+def uninstall_gemini_interceptor():
+    global _installed, _on_span, _original_generate
+    if not _installed or not _original_generate:
+        return
+    try:
+        from google import genai
+        genai.models.Models.generate_content = _original_generate
+    except ImportError:
+        pass
+    _installed = False
+    _on_span = None

retrace_sdk-0.1.3/src/retrace/recorder.py

@@ -0,0 +1,277 @@
+from __future__ import annotations
+
+import functools
+import logging
+import threading
+import time
+from typing import Any, Callable
+
+logger = logging.getLogger("retrace")
+
+from .config import get_config
+from .trace import Trace, Span, SpanType, TraceStatus
+from .transport import create_transport, WSTransport, HTTPTransport
+from .utils import gen_id, utcnow
+
+
+class TraceRecorder:
+    """Manages recording of a single trace and its spans."""
+
+    def __init__(self, name: str | None = None, input: Any = None, metadata: dict | None = None):
+        self._trace = Trace(
+            name=name,
+            input=input,
+            metadata=metadata or {},
+            project_id=get_config().project_id,
+        )
+        self._lock = threading.Lock()
+        self._transport = create_transport()
+        self._interceptors_installed = False
+
+    @property
+    def trace(self) -> Trace:
+        return self._trace
+
+    @property
+    def output(self):
+        return self._trace.output
+
+    @output.setter
+    def output(self, value):
+        self._trace.output = value
+
+    def _install_interceptors(self):
+        if self._interceptors_installed:
+            return
+        try:
+            from .interceptors.gemini import install_gemini_interceptor
+            install_gemini_interceptor(lambda span_data: self._handle_intercepted_span(span_data))
+        except Exception as e:
+            logger.debug(f"Failed to install interceptors: {e}")
+        self._interceptors_installed = True
+
+    def _handle_intercepted_span(self, span_data: dict):
+        span = Span(
+            trace_id=self._trace.id,
+            span_type=SpanType(span_data.get("span_type", "llm_call")),
+            name=span_data.get("name", ""),
+            model=span_data.get("model"),
+            input=span_data.get("input"),
+            output=span_data.get("output"),
+            input_tokens=span_data.get("input_tokens"),
+            output_tokens=span_data.get("output_tokens"),
+            cost=span_data.get("cost"),
+            duration_ms=span_data.get("duration_ms"),
+            error=span_data.get("error"),
+        )
+        if span_data.get("id"):
+            span.id = span_data["id"]
+        span.ended_at = utcnow()
+        self.add_span(span)
+
+    def start_trace(self, name: str | None = None, input: Any = None, metadata: dict | None = None):
+        if name:
+            self._trace.name = name
+        if input is not None:
+            self._trace.input = input
+        if metadata:
+            self._trace.metadata.update(metadata)
+        self._install_interceptors()
+        self._send("trace_started", self._trace.to_dict())
+
+    def end_trace(self, output: Any = None, status: TraceStatus = TraceStatus.COMPLETED):
+        self._trace.output = output if output is not None else self._trace.output
+        self._trace.status = status
+        self._trace.ended_at = utcnow()
+        if self._trace.started_at:
+            self._trace.total_duration_ms = int(
+                (self._trace.ended_at - self._trace.started_at).total_seconds() * 1000
+            )
+        self._send("trace_ended", {
+            "id": self._trace.id,
+            "ended_at": self._trace.ended_at.isoformat().replace("+00:00", "Z"),
+            "output": self._trace.output,
+            "status": status.value,
+            "total_tokens": self._trace.total_tokens,
+            "total_cost": self._trace.total_cost,
+        })
+        self._transport.close()
+
+    def add_span(self, span: Span):
+        span.trace_id = self._trace.id
+        with self._lock:
+            self._trace.spans.append(span)
+            self._trace.total_tokens += (span.input_tokens or 0) + (span.output_tokens or 0)
+            self._trace.total_cost += span.cost or 0.0
+
+        if span.ended_at:
+            # Span is complete — send both started and ended
+            self._send("span_started", span.to_dict())
+            self._send("span_ended", {
+                "id": span.id,
+                "ended_at": span.ended_at.isoformat().replace("+00:00", "Z"),
+                "output": span.output,
+                "output_tokens": span.output_tokens,
+                "cost": span.cost,
+                "error": span.error,
+            })
+        else:
+            self._send("span_started", span.to_dict())
+
+    def start_span(
+        self,
+        name: str,
+        span_type: SpanType = SpanType.LLM_CALL,
+        input: Any = None,
+        model: str | None = None,
+        parent_id: str | None = None,
+    ) -> Span:
+        span = Span(
+            trace_id=self._trace.id,
+            span_type=span_type,
+            name=name,
+            input=input,
+            model=model,
+            parent_id=parent_id,
+        )
+        with self._lock:
+            self._trace.spans.append(span)
+        self._send("span_started", span.to_dict())
+        return span
+
+    def end_span(self, span_id: str, output: Any = None, error: str | None = None):
+        with self._lock:
+            span = next((s for s in self._trace.spans if s.id == span_id), None)
+        if not span:
+            return
+        span.output = output
+        span.error = error
+        span.ended_at = utcnow()
+        if span.started_at:
+            span.duration_ms = int((span.ended_at - span.started_at).total_seconds() * 1000)
+        self._send("span_ended", {
+            "id": span.id,
+            "ended_at": span.ended_at.isoformat().replace("+00:00", "Z"),
+            "output": output,
+            "error": error,
+        })
+
+    def _send(self, event_type: str, data: dict):
+        try:
+            self._transport.send(event_type, data)
+        except Exception as e:
+            logger.debug(f"Failed to send {event_type}: {e}")
+
+    # Context manager support
+    def __enter__(self):
+        self.start_trace()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if exc_type:
+            self.end_trace(status=TraceStatus.FAILED)
+        else:
+            self.end_trace(status=TraceStatus.COMPLETED)
+        return False
+
+
+def record(name: str | None = None, input: Any = None, metadata: dict | None = None):
+    """Decorator and context manager for recording agent executions.
+
+    Usage as decorator:
+        @retrace.record(name="my-agent")
+        def my_agent(prompt):
+            ...
+
+    Usage as context manager:
+        with retrace.record(name="my-agent", input={"prompt": "hi"}) as t:
+            result = agent.run("hi")
+            t.output = result
+    """
+    cfg = get_config()
+
+    # If called with a function directly: @record without parens
+    if callable(name):
+        fn = name
+        if not cfg.enabled:
+            return fn
+
+        @functools.wraps(fn)
+        def wrapper(*args, **kwargs):
+            recorder = TraceRecorder(name=fn.__name__, input={"args": list(args), "kwargs": kwargs})
+            recorder.start_trace()
+            try:
+                result = fn(*args, **kwargs)
+                recorder.end_trace(output=result, status=TraceStatus.COMPLETED)
+                return result
+            except Exception as e:
+                recorder.end_trace(status=TraceStatus.FAILED)
+                raise
+
+        return wrapper
+
+    # Called with arguments: @record(name="...") or as context manager
+    def decorator(fn: Callable | None = None):
+        if fn is None:
+            # Context manager usage
+            return TraceRecorder(name=name, input=input, metadata=metadata)
+
+        if not cfg.enabled:
+            return fn
+
+        @functools.wraps(fn)
+        def wrapper(*args, **kwargs):
+            recorder = TraceRecorder(
+                name=name or fn.__name__,
+                input=input if input is not None else {"args": list(args), "kwargs": kwargs},
+                metadata=metadata,
+            )
+            recorder.start_trace()
+            try:
+                result = fn(*args, **kwargs)
+                recorder.end_trace(output=result, status=TraceStatus.COMPLETED)
+                return result
+            except Exception as e:
+                recorder.end_trace(status=TraceStatus.FAILED)
+                raise
+
+        return wrapper
+
+    # If no function passed, could be context manager or decorator
+    if not cfg.enabled:
+        # Return a no-op context manager
+        class _NoOp:
+            output = None
+            def __enter__(self): return self
+            def __exit__(self, *a): return False
+            def __call__(self, fn): return fn
+        return _NoOp()
+
+    # Return something that works as both decorator and context manager
+    class _RecordProxy:
+        def __init__(self):
+            self._recorder = TraceRecorder(name=name, input=input, metadata=metadata)
+
+        @property
+        def output(self):
+            return self._recorder.output
+
+        @output.setter
+        def output(self, value):
+            self._recorder.output = value
+
+        def __call__(self, fn):
+            return decorator(fn)
+
+        def __enter__(self):
+            self._recorder.start_trace()
+            return self
+
+        def __exit__(self, exc_type, exc_val, exc_tb):
+            if exc_type:
+                self._recorder.end_trace(status=TraceStatus.FAILED)
+            else:
+                self._recorder.end_trace(status=TraceStatus.COMPLETED)
+            return False
+
+    return _RecordProxy()

retrace_sdk-0.1.3/src/retrace/trace.py

@@ -0,0 +1,115 @@
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Optional
+from enum import Enum
+
+from .utils import gen_id, utcnow
+
+
+class SpanType(str, Enum):
+    LLM_CALL = "llm_call"
+    TOOL_CALL = "tool_call"
+    TOOL_RESULT = "tool_result"
+    REASONING = "reasoning"
+    ACTION = "action"
+    ERROR = "error"
+    FORK_POINT = "fork_point"
+
+
+class TraceStatus(str, Enum):
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+@dataclass
+class Span:
+    id: str = field(default_factory=gen_id)
+    trace_id: str = ""
+    span_type: SpanType = SpanType.LLM_CALL
+    name: str = ""
+    parent_id: Optional[str] = None
+    model: Optional[str] = None
+    input: Any = None
+    output: Any = None
+    input_tokens: Optional[int] = None
+    output_tokens: Optional[int] = None
+    cost: Optional[float] = None
+    duration_ms: Optional[int] = None
+    metadata: dict = field(default_factory=dict)
+    started_at: Optional[datetime] = field(default_factory=utcnow)
+    ended_at: Optional[datetime] = None
+    error: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        d: dict[str, Any] = {
+            "id": self.id,
+            "trace_id": self.trace_id,
+            "parent_id": self.parent_id,
+            "span_type": self.span_type.value,
+            "name": self.name,
+            "started_at": self.started_at.isoformat().replace("+00:00", "Z") if self.started_at else None,
+        }
+        if self.model:
+            d["model"] = self.model
+        if self.input is not None:
+            d["input"] = self.input
+        if self.output is not None:
+            d["output"] = self.output
+        if self.input_tokens is not None:
+            d["input_tokens"] = self.input_tokens
+        if self.output_tokens is not None:
+            d["output_tokens"] = self.output_tokens
+        if self.cost is not None:
+            d["cost"] = self.cost
+        if self.duration_ms is not None:
+            d["duration_ms"] = self.duration_ms
+        if self.metadata:
+            d["metadata"] = self.metadata
+        if self.ended_at:
+            d["ended_at"] = self.ended_at.isoformat().replace("+00:00", "Z")
+        if self.error:
+            d["error"] = self.error
+        return d
+
+
+@dataclass
+class Trace:
+    id: str = field(default_factory=gen_id)
+    name: Optional[str] = None
+    input: Any = None
+    output: Any = None
+    status: TraceStatus = TraceStatus.RUNNING
+    total_tokens: int = 0
+    total_cost: float = 0.0
+    total_duration_ms: int = 0
+    metadata: dict = field(default_factory=dict)
+    started_at: Optional[datetime] = field(default_factory=utcnow)
+    ended_at: Optional[datetime] = None
+    spans: list = field(default_factory=list)
+    project_id: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        d: dict[str, Any] = {
+            "id": self.id,
+            "status": self.status.value,
+            "total_tokens": self.total_tokens,
+            "total_cost": self.total_cost,
+            "total_duration_ms": self.total_duration_ms,
+            "started_at": self.started_at.isoformat().replace("+00:00", "Z") if self.started_at else None,
+        }
+        if self.name:
+            d["name"] = self.name
+        if self.input is not None:
+            d["input"] = self.input
+        if self.output is not None:
+            d["output"] = self.output
+        if self.metadata:
+            d["metadata"] = self.metadata
+        if self.ended_at:
+            d["ended_at"] = self.ended_at.isoformat().replace("+00:00", "Z")
+        if self.project_id:
+            d["project_id"] = self.project_id
+        if self.spans:
+            d["spans"] = [s.to_dict() for s in self.spans]
+        return d

retrace_sdk-0.1.3/src/retrace/transport.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import json
+import logging
+import threading
+import time
+from typing import Any
+
+logger = logging.getLogger("retrace")
+
+from .config import get_config
+from .trace import Trace
+
+
+class WSTransport:
+    """WebSocket transport using websocket-client (sync) for span streaming."""
+
+    def __init__(self):
+        self._ws = None
+        self._lock = threading.Lock()
+        self._connected = False
+        self._backoff = 1.0
+
+    def connect(self):
+        import websocket
+
+        cfg = get_config()
+        url = f"{cfg.ws_url}/ws/v1/stream"
+        try:
+            self._ws = websocket.create_connection(url, timeout=10)
+            # Auth
+            self._ws.send(json.dumps({"type": "auth", "api_key": cfg.api_key}))
+            resp = json.loads(self._ws.recv())
+            if resp.get("type") == "auth_ok":
+                self._connected = True
+                self._backoff = 1.0
+            else:
+                self._ws.close()
+                self._ws = None
+        except Exception as e:
+            logger.debug(f"WebSocket connection failed: {e}")
+            self._ws = None
+            self._connected = False
+
+    def _ensure_connected(self):
+        if not self._connected or self._ws is None:
+            self.connect()
+
+    def send(self, event_type: str, data: dict[str, Any]):
+        with self._lock:
+            self._ensure_connected()
+            if not self._ws:
+                return
+            try:
+                self._ws.send(json.dumps({"type": event_type, "data": data}))
+                # Handle ping
+                self._ws.settimeout(0.1)
+                try:
+                    msg = self._ws.recv()
+                    parsed = json.loads(msg)
+                    if parsed.get("type") == "ping":
+                        self._ws.send(json.dumps({"type": "pong"}))
+                except Exception as e:
+                    logger.debug(f"Ping handling error: {e}")
+                self._ws.settimeout(10)
+            except Exception as e:
+                logger.debug(f"WebSocket send failed: {e}")
+                self._connected = False
+                self._ws = None
+                # Retry with backoff
+                time.sleep(min(self._backoff, 30.0))
+                self._backoff *= 2
+
+    def close(self):
+        with self._lock:
+            if self._ws:
+                try:
+                    self._ws.close()
+                except Exception as e:
+                    logger.debug(f"WebSocket close error: {e}")
+                self._ws = None
+                self._connected = False
+
+
+class HTTPTransport:
+    """HTTP fallback transport using requests."""
+
+    def __init__(self):
+        self._trace_data: dict | None = None
+        self._spans: list[dict] = []
+        self._lock = threading.Lock()
+
+    def send_trace(self, trace: Trace):
+        import requests
+
+        cfg = get_config()
+        url = f"{cfg.base_url}/api/v1/traces"
+        headers = {"x-retrace-key": cfg.api_key, "Content-Type": "application/json"}
+        try:
+            requests.post(url, json=trace.to_dict(), headers=headers, timeout=10)
+        except Exception as e:
+            logger.debug(f"HTTP send_trace failed: {e}")
+
+    def send(self, event_type: str, data: dict[str, Any]):
+        with self._lock:
+            if event_type == "trace_started":
+                self._trace_data = dict(data)
+            elif event_type in ("span_started", "span_ended"):
+                self._spans.append({"_event": event_type, **data})
+            elif event_type == "trace_ended":
+                if self._trace_data:
+                    self._trace_data.update(data)
+                self.flush()
+
+    def flush(self):
+        with self._lock:
+            if not self._trace_data:
+                return
+            # Merge span_started and span_ended events into complete spans
+            merged: dict[str, dict] = {}
+            for ev in self._spans:
+                event_type = ev.pop("_event", None)
+                span_id = ev.get("id", "")
+                if event_type == "span_started":
+                    merged[span_id] = dict(ev)
+                elif event_type == "span_ended" and span_id in merged:
+                    merged[span_id].update(ev)
+            self._trace_data["spans"] = list(merged.values())
+
+            import requests
+            cfg = get_config()
+            url = f"{cfg.base_url}/api/v1/traces"
+            headers = {"x-retrace-key": cfg.api_key, "Content-Type": "application/json"}
+            try:
+                requests.post(url, json=self._trace_data, headers=headers, timeout=10)
+            except Exception as e:
+                logger.debug(f"HTTP flush failed: {e}")
+            self._trace_data = None
+            self._spans = []
+
+    def close(self):
+        self.flush()
+
+
+def create_transport(mode: str = "auto") -> WSTransport | HTTPTransport:
+    if mode == "http":
+        return HTTPTransport()
+    if mode == "ws":
+        return WSTransport()
+    # Auto: try WS
+    try:
+        import websocket  # noqa: F401
+        return WSTransport()
+    except ImportError:
+        return HTTPTransport()

retrace_sdk-0.1.3/src/retrace/utils.py

@@ -0,0 +1,25 @@
+import json
+from datetime import datetime, timezone
+from uuid import uuid4
+
+
+def gen_id() -> str:
+    return str(uuid4())
+
+
+def now_iso() -> str:
+    return utcnow().isoformat().replace("+00:00", "Z")
+
+
+def utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def truncate_json(obj, max_bytes: int = 10240):
+    try:
+        s = json.dumps(obj)
+        if len(s.encode()) <= max_bytes:
+            return obj
+        return json.loads(s.encode()[:max_bytes].decode(errors="ignore"))
+    except (TypeError, ValueError):
+        return str(obj)[:max_bytes]

retrace_sdk-0.1.3/tests/test_config.py

@@ -0,0 +1,21 @@
+import os
+
+def test_default_config():
+    # Clear env and reset
+    os.environ.pop("RETRACE_API_KEY", None)
+    os.environ.pop("RETRACE_BASE_URL", None)
+    import retrace.config as cfg
+    cfg._config = None
+    from retrace.config import get_config
+    config = get_config()
+    assert config.base_url == "http://localhost:3001"
+    assert config.enabled == True
+
+def test_configure():
+    import retrace.config as cfg
+    cfg._config = None
+    from retrace.config import configure, get_config
+    configure(api_key="rt_live_test", base_url="http://custom:3001")
+    config = get_config()
+    assert config.api_key == "rt_live_test"
+    assert config.base_url == "http://custom:3001"