spano 0.1.0__tar.gz

spano-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+if (-not (Test-Path "SDK\.gitignore")) {
+@'
+.venv/
+__pycache__/
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+'@ | Set-Content -Encoding utf8 "SDK\.gitignore"
+}

spano-0.1.0/LICENSE

@@ -0,0 +1,17 @@
+MIT License
+
+Copyright (c) 2026 Spano contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

spano-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.5
+Name: spano
+Version: 0.1.0
+Summary: Python SDK for tracing and exporting AI-agent execution telemetry
+Author: Spano contributors
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,llm,observability,telemetry,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Spano Python SDK
+
+Spano is a lightweight Python SDK for recording AI-agent traces and exporting spans to an HTTP ingestion endpoint. This early release provides manual tracing; automatic LangChain/LangGraph instrumentation is not included yet.
+
+## Install for local development
+
+```bash
+uv sync
+uv run pytest
+```
+
+## Quick start
+
+```python
+from spano import Spano, SpanKind
+
+client = Spano(
+    api_key="your-api-key",
+    endpoint="http://localhost:8000",
+    # The server must implement POST /api/v1/traces.
+)
+
+try:
+    with client.start_trace("research-agent", attributes={"environment": "dev"}) as trace:
+        with trace.start_span("search-web", kind=SpanKind.TOOL, attributes={"tool": "web-search"}):
+            # Run your tool here.
+            pass
+finally:
+    client.close()
+```
+
+## Ingestion contract
+
+Spano sends `POST {endpoint}/api/v1/traces` with `Authorization: Bearer <api-key>` and a JSON body shaped like:
+
+```json
+{"spans": [{"trace_id": "...", "span_id": "...", "parent_span_id": null, "name": "research-agent", "kind": "agent", "start_time": "...", "end_time": "...", "duration_ms": 1.2, "status": "ok", "attributes": {}, "error": null}]}
+```
+
+The endpoint should return a 2xx response. If the response body is non-empty, it must be a JSON object; an optional integer `accepted` field should equal the number of spans in the request. This SDK does not include the backend or persist traces itself.
+
+## Buffering and failures
+
+- `flush()` exports buffered spans and returns `True` on success, `False` when best-effort delivery fails.
+- `close()` attempts to flush and is safe to call more than once.
+- Buffer capacity is bounded. If it fills, the oldest span is dropped and `client.dropped_spans` increments.
+- Transport errors are logged and passed to `on_error` if supplied. Set `strict_transport=True` to raise transport errors from `flush()`/`close()`.
+- Application exceptions are recorded in spans and re-raised; Spano does not swallow them.
+- Input/output prompts and responses are not captured automatically. Only metadata explicitly provided by the developer is recorded. Do not add credentials or sensitive values to attributes.
+
+## Configuration
+
+`Spano(api_key, endpoint="http://localhost:8000", timeout=5.0, ingestion_path="/api/v1/traces", max_buffer_size=1000, batch_size=100, strict_transport=False, logger=None, on_error=None)`
+
+This package is an early alpha. Review behavior and endpoint compatibility before production use.

spano-0.1.0/README.md

@@ -0,0 +1,55 @@
+# Spano Python SDK
+
+Spano is a lightweight Python SDK for recording AI-agent traces and exporting spans to an HTTP ingestion endpoint. This early release provides manual tracing; automatic LangChain/LangGraph instrumentation is not included yet.
+
+## Install for local development
+
+```bash
+uv sync
+uv run pytest
+```
+
+## Quick start
+
+```python
+from spano import Spano, SpanKind
+
+client = Spano(
+    api_key="your-api-key",
+    endpoint="http://localhost:8000",
+    # The server must implement POST /api/v1/traces.
+)
+
+try:
+    with client.start_trace("research-agent", attributes={"environment": "dev"}) as trace:
+        with trace.start_span("search-web", kind=SpanKind.TOOL, attributes={"tool": "web-search"}):
+            # Run your tool here.
+            pass
+finally:
+    client.close()
+```
+
+## Ingestion contract
+
+Spano sends `POST {endpoint}/api/v1/traces` with `Authorization: Bearer <api-key>` and a JSON body shaped like:
+
+```json
+{"spans": [{"trace_id": "...", "span_id": "...", "parent_span_id": null, "name": "research-agent", "kind": "agent", "start_time": "...", "end_time": "...", "duration_ms": 1.2, "status": "ok", "attributes": {}, "error": null}]}
+```
+
+The endpoint should return a 2xx response. If the response body is non-empty, it must be a JSON object; an optional integer `accepted` field should equal the number of spans in the request. This SDK does not include the backend or persist traces itself.
+
+## Buffering and failures
+
+- `flush()` exports buffered spans and returns `True` on success, `False` when best-effort delivery fails.
+- `close()` attempts to flush and is safe to call more than once.
+- Buffer capacity is bounded. If it fills, the oldest span is dropped and `client.dropped_spans` increments.
+- Transport errors are logged and passed to `on_error` if supplied. Set `strict_transport=True` to raise transport errors from `flush()`/`close()`.
+- Application exceptions are recorded in spans and re-raised; Spano does not swallow them.
+- Input/output prompts and responses are not captured automatically. Only metadata explicitly provided by the developer is recorded. Do not add credentials or sensitive values to attributes.
+
+## Configuration
+
+`Spano(api_key, endpoint="http://localhost:8000", timeout=5.0, ingestion_path="/api/v1/traces", max_buffer_size=1000, batch_size=100, strict_transport=False, logger=None, on_error=None)`
+
+This package is an early alpha. Review behavior and endpoint compatibility before production use.

spano-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "spano"
+version = "0.1.0"
+description = "Python SDK for tracing and exporting AI-agent execution telemetry"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Spano contributors" }]
+keywords = ["ai-agents", "observability", "tracing", "llm", "telemetry"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+]
+dependencies = []
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/spano"]
+
+[dependency-groups]
+dev = ["pytest>=8.0", "build>=1.0"]
+
+[tool.pytest.ini_options]
+testpaths = ["test"]

spano-0.1.0/src/spano/__init__.py

@@ -0,0 +1,19 @@
+"""Public API for the Spano SDK."""
+
+from .client import Spano
+from .config import SpanoConfig
+from .events import Span, SpanKind, SpanStatus
+from .exceptions import SpanoConfigurationError, SpanoError, SpanoTransportError
+from .tracer import Trace
+
+__all__ = [
+    "Spano",
+    "SpanoConfig",
+    "Trace",
+    "Span",
+    "SpanKind",
+    "SpanStatus",
+    "SpanoError",
+    "SpanoConfigurationError",
+    "SpanoTransportError",
+]

spano-0.1.0/src/spano/client.py

@@ -0,0 +1,127 @@
+"""Public Spano client."""
+
+from __future__ import annotations
+
+import logging
+from threading import RLock
+from typing import Any, Callable
+
+from .config import SpanoConfig
+from .events import Span
+from .exceptions import SpanoTransportError
+from .tracer import Trace
+from .transport import HTTPExporter
+
+TelemetryErrorCallback = Callable[[Exception], None]
+
+
+class Spano:
+    """Client entry point for Spano tracing and telemetry export.
+
+    Telemetry delivery is best-effort by default. Set ``strict_transport=True``
+    to re-raise transport errors from ``flush()`` and ``close()``.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        endpoint: str = "http://localhost:8000",
+        timeout: float = 5.0,
+        *,
+        ingestion_path: str = "/api/v1/traces",
+        max_buffer_size: int = 1000,
+        batch_size: int = 100,
+        strict_transport: bool = False,
+        logger: logging.Logger | None = None,
+        on_error: TelemetryErrorCallback | None = None,
+    ) -> None:
+        self.config = SpanoConfig(
+            api_key=api_key,
+            endpoint=endpoint,
+            timeout=timeout,
+            ingestion_path=ingestion_path,
+            max_buffer_size=max_buffer_size,
+            batch_size=batch_size,
+            strict_transport=strict_transport,
+        )
+        self._exporter = HTTPExporter(
+            endpoint=self.config.endpoint,
+            api_key=self.config.api_key,
+            timeout=self.config.timeout,
+            ingestion_path=self.config.ingestion_path,
+        )
+        self._logger = logger or logging.getLogger("spano")
+        self._on_error = on_error
+        self._buffer: list[dict[str, Any]] = []
+        self._lock = RLock()
+        self._closed = False
+        self.dropped_spans = 0
+
+    @property
+    def closed(self) -> bool:
+        return self._closed
+
+    def start_trace(self, name: str, *, attributes: dict[str, Any] | None = None) -> Trace:
+        if self._closed:
+            raise RuntimeError("Spano client is closed")
+        return Trace(self, name, attributes)
+
+    def _enqueue(self, spans: list[Span]) -> None:
+        with self._lock:
+            if self._closed:
+                self._report_error(RuntimeError("Cannot enqueue telemetry after client is closed"))
+                return
+            for span in spans:
+                if len(self._buffer) >= self.config.max_buffer_size:
+                    self._buffer.pop(0)
+                    self.dropped_spans += 1
+                self._buffer.append(span.to_dict())
+            should_flush = len(self._buffer) >= self.config.batch_size
+        if should_flush:
+            self.flush()
+
+    def flush(self) -> bool:
+        """Send buffered spans. Returns True when the buffer is empty after success."""
+        if self._closed and not self._buffer:
+            return True
+        while True:
+            with self._lock:
+                if not self._buffer:
+                    return True
+                batch = self._buffer[: self.config.batch_size]
+            try:
+                self._exporter.export(batch)
+            except Exception as exc:
+                self._report_error(exc)
+                if self.config.strict_transport:
+                    if isinstance(exc, SpanoTransportError):
+                        raise
+                    raise SpanoTransportError(str(exc)) from exc
+                return False
+            with self._lock:
+                del self._buffer[: len(batch)]
+
+    def close(self) -> None:
+        """Flush buffered telemetry and close the client; safe to call repeatedly."""
+        if self._closed:
+            return
+        try:
+            self.flush()
+        finally:
+            self._closed = True
+
+    def _report_error(self, error: Exception) -> None:
+        self._logger.warning("Spano telemetry error: %s", error)
+        if self._on_error is not None:
+            try:
+                self._on_error(error)
+            except Exception:
+                self._logger.exception("Spano error callback failed")
+
+    def __enter__(self) -> "Spano":
+        if self._closed:
+            raise RuntimeError("Spano client is already closed")
+        return self
+
+    def __exit__(self, exc_type: Any, exc: BaseException | None, tb: Any) -> None:
+        self.close()

spano-0.1.0/src/spano/config.py

@@ -0,0 +1,39 @@
+"""Configuration for the Spano SDK."""
+
+from dataclasses import dataclass
+import math
+from urllib.parse import urlsplit
+
+
+@dataclass(frozen=True, slots=True)
+class SpanoConfig:
+    api_key: str
+    endpoint: str = "http://localhost:8000"
+    timeout: float = 5.0
+    ingestion_path: str = "/api/v1/traces"
+    max_buffer_size: int = 1000
+    batch_size: int = 100
+    strict_transport: bool = False
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.api_key, str) or not self.api_key.strip():
+            raise ValueError("api_key cannot be empty")
+        if not isinstance(self.endpoint, str):
+            raise ValueError("endpoint must be a string")
+        parsed = urlsplit(self.endpoint)
+        if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+            raise ValueError("endpoint must be an absolute HTTP or HTTPS URL")
+        if parsed.username or parsed.password:
+            raise ValueError("endpoint must not contain embedded credentials")
+        if parsed.query or parsed.fragment:
+            raise ValueError("endpoint must not contain a query or fragment")
+        if not math.isfinite(self.timeout) or self.timeout <= 0:
+            raise ValueError("timeout must be a finite number greater than zero")
+        if not isinstance(self.ingestion_path, str) or not self.ingestion_path.startswith("/"):
+            raise ValueError("ingestion_path must start with '/'")
+        if self.max_buffer_size < 1:
+            raise ValueError("max_buffer_size must be at least 1")
+        if self.batch_size < 1:
+            raise ValueError("batch_size must be at least 1")
+        object.__setattr__(self, "endpoint", self.endpoint.rstrip("/"))
+        object.__setattr__(self, "ingestion_path", "/" + self.ingestion_path.strip("/"))

spano-0.1.0/src/spano/events.py

@@ -0,0 +1,145 @@
+"""Core tracing events and span models for the Spano SDK."""
+
+from __future__ import annotations
+
+import json
+import math
+import secrets
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import StrEnum
+from typing import Any
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def new_trace_id() -> str:
+    """Generate a 32-character hexadecimal trace ID."""
+    return secrets.token_hex(16)
+
+
+def new_span_id() -> str:
+    """Generate a 16-character hexadecimal span ID."""
+    return secrets.token_hex(8)
+
+
+class SpanKind(StrEnum):
+    AGENT = "agent"
+    LLM = "llm"
+    TOOL = "tool"
+    CHAIN = "chain"
+    INTERNAL = "internal"
+
+
+class SpanStatus(StrEnum):
+    UNSET = "unset"
+    OK = "ok"
+    ERROR = "error"
+
+
+def validate_attributes(attributes: dict[str, Any]) -> None:
+    if not isinstance(attributes, dict):
+        raise ValueError("attributes must be a dictionary")
+    if any(not isinstance(key, str) for key in attributes):
+        raise ValueError("attribute keys must be strings")
+    try:
+        json.dumps(attributes, allow_nan=False)
+    except (TypeError, ValueError) as exc:
+        raise ValueError("attributes must contain JSON-serializable values") from exc
+
+
+@dataclass(slots=True)
+class Span:
+    """Represents one unit of work within an execution trace."""
+
+    name: str
+    kind: SpanKind = SpanKind.INTERNAL
+    trace_id: str = field(default_factory=new_trace_id)
+    span_id: str = field(default_factory=new_span_id)
+    parent_span_id: str | None = None
+    start_time: datetime = field(default_factory=utc_now)
+    end_time: datetime | None = None
+    status: SpanStatus = SpanStatus.UNSET
+    attributes: dict[str, Any] = field(default_factory=dict)
+    error: dict[str, str] | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.name, str) or not self.name.strip():
+            raise ValueError("Span name cannot be empty")
+        if not isinstance(self.kind, SpanKind):
+            raise ValueError("kind must be a SpanKind")
+        self._validate_id(self.trace_id, 32, "trace_id")
+        self._validate_id(self.span_id, 16, "span_id")
+        if self.parent_span_id is not None:
+            self._validate_id(self.parent_span_id, 16, "parent_span_id")
+            if self.parent_span_id == self.span_id:
+                raise ValueError("A span cannot be its own parent")
+        self._validate_timestamp(self.start_time, "start_time")
+        if self.end_time is not None:
+            self._validate_timestamp(self.end_time, "end_time")
+            if self.end_time < self.start_time:
+                raise ValueError("end_time cannot precede start_time")
+        validate_attributes(self.attributes)
+
+    @staticmethod
+    def _validate_id(value: str, length: int, name: str) -> None:
+        if (
+            not isinstance(value, str)
+            or len(value) != length
+            or any(char not in "0123456789abcdef" for char in value)
+            or set(value) == {"0"}
+        ):
+            raise ValueError(f"{name} must be {length} non-zero hexadecimal characters")
+
+    @staticmethod
+    def _validate_timestamp(value: datetime, name: str) -> None:
+        if not isinstance(value, datetime) or value.tzinfo is None or value.utcoffset() is None:
+            raise ValueError(f"{name} must be timezone-aware")
+
+    @property
+    def duration_ms(self) -> float | None:
+        if self.end_time is None:
+            return None
+        return (self.end_time - self.start_time).total_seconds() * 1000
+
+    def set_attributes(self, attributes: dict[str, Any] | None = None, **kwargs: Any) -> None:
+        """Add JSON-serializable metadata to this span."""
+        updates = dict(attributes or {})
+        updates.update(kwargs)
+        validate_attributes(updates)
+        self.attributes.update(updates)
+        validate_attributes(self.attributes)
+
+    def finish(
+        self,
+        status: SpanStatus = SpanStatus.OK,
+        error: dict[str, str] | None = None,
+    ) -> None:
+        if self.end_time is not None:
+            raise RuntimeError("Span has already finished")
+        if not isinstance(status, SpanStatus):
+            raise ValueError("status must be a SpanStatus")
+        if status == SpanStatus.ERROR and error is None:
+            raise ValueError("An error span must include error details")
+        if status != SpanStatus.ERROR and error is not None:
+            raise ValueError("Error details require ERROR status")
+        self.end_time = utc_now()
+        self.status = status
+        self.error = error
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "trace_id": self.trace_id,
+            "span_id": self.span_id,
+            "parent_span_id": self.parent_span_id,
+            "name": self.name,
+            "kind": self.kind.value,
+            "start_time": self.start_time.isoformat(),
+            "end_time": self.end_time.isoformat() if self.end_time is not None else None,
+            "duration_ms": self.duration_ms,
+            "status": self.status.value,
+            "attributes": self.attributes,
+            "error": self.error,
+        }

spano-0.1.0/src/spano/exceptions.py

@@ -0,0 +1,13 @@
+"""Custom exceptions for the Spano SDK."""
+
+
+class SpanoError(Exception):
+    """Base exception for Spano SDK errors."""
+
+
+class SpanoConfigurationError(SpanoError):
+    """Invalid SDK configuration."""
+
+
+class SpanoTransportError(SpanoError):
+    """Telemetry transport failed."""

spano-0.1.0/src/spano/tracer.py

@@ -0,0 +1,111 @@
+"""Trace and span context managers."""
+
+from __future__ import annotations
+
+from contextvars import ContextVar, Token
+from typing import Any, TYPE_CHECKING
+
+from .events import Span, SpanKind, SpanStatus
+
+if TYPE_CHECKING:
+    from .client import Spano
+
+_active_trace: ContextVar[Trace | None] = ContextVar("spano_active_trace", default=None)
+_active_span: ContextVar[Span | None] = ContextVar("spano_active_span", default=None)
+
+
+class SpanScope:
+    """Context manager that automatically finishes a span and captures exceptions."""
+
+    def __init__(self, trace: "Trace", span: Span) -> None:
+        self.trace = trace
+        self.span = span
+        self._token: Token[Span | None] | None = None
+
+    def __enter__(self) -> Span:
+        if self.trace.finished:
+            raise RuntimeError("Cannot create a span in a finished trace")
+        self._token = _active_span.set(self.span)
+        return self.span
+
+    def __exit__(self, exc_type: Any, exc: BaseException | None, tb: Any) -> bool:
+        try:
+            if self.span.end_time is None:
+                if exc is not None:
+                    self.span.finish(
+                        status=SpanStatus.ERROR,
+                        error={"type": exc_type.__name__ if exc_type else type(exc).__name__, "message": str(exc)[:1000]},
+                    )
+                else:
+                    self.span.finish()
+        finally:
+            if self._token is not None:
+                _active_span.reset(self._token)
+        return False
+
+
+class Trace:
+    """A trace owns a root span and all child spans created inside it."""
+
+    def __init__(self, client: "Spano", name: str, attributes: dict[str, Any] | None = None) -> None:
+        self.client = client
+        self.root_span = Span(name=name, kind=SpanKind.AGENT, attributes=dict(attributes or {}))
+        self.spans: list[Span] = [self.root_span]
+        self.finished = False
+        self._trace_token: Token[Trace | None] | None = None
+        self._span_token: Token[Span | None] | None = None
+
+    @property
+    def trace_id(self) -> str:
+        return self.root_span.trace_id
+
+    def __enter__(self) -> "Trace":
+        if self.finished:
+            raise RuntimeError("Trace has already finished")
+        self._trace_token = _active_trace.set(self)
+        self._span_token = _active_span.set(self.root_span)
+        return self
+
+    def start_span(
+        self,
+        name: str,
+        *,
+        kind: SpanKind = SpanKind.INTERNAL,
+        attributes: dict[str, Any] | None = None,
+    ) -> SpanScope:
+        if self.finished:
+            raise RuntimeError("Cannot create a span in a finished trace")
+        active_trace = _active_trace.get()
+        active_span = _active_span.get()
+        parent = active_span if active_trace is self and active_span is not None else self.root_span
+        span = Span(
+            name=name,
+            kind=kind,
+            trace_id=self.trace_id,
+            parent_span_id=parent.span_id,
+            attributes=dict(attributes or {}),
+        )
+        self.spans.append(span)
+        return SpanScope(self, span)
+
+    def set_attributes(self, attributes: dict[str, Any] | None = None, **kwargs: Any) -> None:
+        self.root_span.set_attributes(attributes, **kwargs)
+
+    def __exit__(self, exc_type: Any, exc: BaseException | None, tb: Any) -> bool:
+        try:
+            if not self.finished:
+                if exc is not None:
+                    self.root_span.finish(
+                        status=SpanStatus.ERROR,
+                        error={"type": exc_type.__name__ if exc_type else type(exc).__name__, "message": str(exc)[:1000]},
+                    )
+                else:
+                    self.root_span.finish()
+                self.finished = True
+                self.client._enqueue(self.spans)
+        finally:
+            if self._span_token is not None:
+                _active_span.reset(self._span_token)
+            if self._trace_token is not None:
+                _active_trace.reset(self._trace_token)
+        return False

spano-0.1.0/src/spano/transport.py

@@ -0,0 +1,54 @@
+"""HTTP transport for Spano telemetry, implemented with the standard library."""
+
+from __future__ import annotations
+
+import json
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+from typing import Any
+
+from .exceptions import SpanoTransportError
+
+
+class HTTPExporter:
+    def __init__(self, endpoint: str, api_key: str, timeout: float, ingestion_path: str) -> None:
+        self.url = endpoint + ingestion_path
+        self.api_key = api_key
+        self.timeout = timeout
+
+    def export(self, spans: list[dict[str, Any]]) -> None:
+        if not spans:
+            return
+        body = json.dumps({"spans": spans}, allow_nan=False).encode("utf-8")
+        request = Request(
+            self.url,
+            data=body,
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                "Authorization": f"Bearer {self.api_key}",
+                "User-Agent": "spano-python-sdk/0.1.0",
+            },
+        )
+        try:
+            with urlopen(request, timeout=self.timeout) as response:
+                status = response.status
+                response_body = response.read()
+        except HTTPError as exc:
+            raise SpanoTransportError(f"Telemetry endpoint returned HTTP {exc.code}") from exc
+        except (URLError, TimeoutError, OSError) as exc:
+            raise SpanoTransportError(f"Unable to send telemetry: {exc}") from exc
+
+        if not 200 <= status < 300:
+            raise SpanoTransportError(f"Telemetry endpoint returned HTTP {status}")
+        if response_body:
+            try:
+                decoded = json.loads(response_body.decode("utf-8"))
+            except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+                raise SpanoTransportError("Telemetry endpoint returned invalid JSON") from exc
+            if not isinstance(decoded, dict):
+                raise SpanoTransportError("Telemetry endpoint response must be a JSON object")
+            accepted = decoded.get("accepted")
+            if accepted is not None and (not isinstance(accepted, int) or accepted != len(spans)):
+                raise SpanoTransportError("Telemetry endpoint accepted count did not match batch size")

spano-0.1.0/test/test_client.py

@@ -0,0 +1,131 @@
+import json
+from unittest.mock import patch
+
+import pytest
+
+from spano import Spano, SpanoConfig, SpanKind, SpanStatus, SpanoTransportError
+
+
+class FakeResponse:
+    status = 200
+
+    def __init__(self, body: bytes = b'{"accepted": 2}') -> None:
+        self.body = body
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        return False
+
+    def read(self) -> bytes:
+        return self.body
+
+
+def test_client_initializes() -> None:
+    client = Spano(api_key="test-key", endpoint="http://localhost:8000/")
+    assert client.config.endpoint == "http://localhost:8000"
+    assert not client.closed
+
+
+def test_empty_api_key_is_rejected() -> None:
+    with pytest.raises(ValueError, match="api_key"):
+        Spano(api_key="  ")
+
+
+def test_invalid_endpoint_is_rejected() -> None:
+    with pytest.raises(ValueError, match="endpoint"):
+        Spano(api_key="test-key", endpoint="localhost:8000")
+
+
+def test_config_is_immutable() -> None:
+    config = SpanoConfig(api_key="test-key")
+    with pytest.raises(AttributeError):
+        config.timeout = 10.0  # type: ignore[misc]
+
+
+def test_nested_spans_share_trace_and_parent_ids() -> None:
+    client = Spano(api_key="test-key")
+    with patch.object(client._exporter, "export") as export:
+        with client.start_trace("agent.run") as trace:
+            with trace.start_span("tool.search", kind=SpanKind.TOOL):
+                with trace.start_span("http.request") as child:
+                    child.set_attributes(status_code=200)
+        assert client.flush() is True
+        assert export.call_count == 1
+        spans = export.call_args.args[0]
+        assert len(spans) == 3
+        assert len({span["trace_id"] for span in spans}) == 1
+        assert spans[1]["parent_span_id"] == spans[0]["span_id"]
+        assert spans[2]["parent_span_id"] == spans[1]["span_id"]
+        assert spans[0]["status"] == "ok"
+        assert spans[2]["attributes"]["status_code"] == 200
+
+
+def test_exceptions_are_recorded_and_propagated() -> None:
+    client = Spano(api_key="test-key")
+    with patch.object(client._exporter, "export") as export:
+        with pytest.raises(ValueError, match="application failure"):
+            with client.start_trace("agent.run") as trace:
+                with trace.start_span("tool.fail"):
+                    raise ValueError("application failure")
+        assert client.flush() is True
+        spans = export.call_args.args[0]
+        assert spans[1]["status"] == "error"
+        assert spans[1]["error"]["type"] == "ValueError"
+        assert spans[0]["status"] == "error"
+
+
+def test_flush_sends_bearer_token_and_json_payload() -> None:
+    client = Spano(api_key="secret", batch_size=1)
+    with patch("spano.transport.urlopen", return_value=FakeResponse(b'{"accepted": 2}')) as mocked:
+        with client.start_trace("agent"):
+            pass
+        request = mocked.call_args.args[0]
+        assert request.get_header("Authorization") == "Bearer secret"
+        payload = json.loads(request.data.decode())
+        assert len(payload["spans"]) == 1
+
+
+def test_transport_failure_is_nonfatal_by_default_and_reported() -> None:
+    errors: list[Exception] = []
+    client = Spano(api_key="test-key", on_error=errors.append)
+    with patch.object(client._exporter, "export", side_effect=SpanoTransportError("offline")):
+        with client.start_trace("agent"):
+            pass
+        assert client.flush() is False
+        assert len(errors) == 1
+        assert client._buffer
+
+
+def test_strict_transport_raises() -> None:
+    client = Spano(api_key="test-key", strict_transport=True)
+    with patch.object(client._exporter, "export", side_effect=SpanoTransportError("offline")):
+        with client.start_trace("agent"):
+            pass
+        with pytest.raises(SpanoTransportError):
+            client.flush()
+
+
+def test_close_flushes_and_is_idempotent() -> None:
+    client = Spano(api_key="test-key")
+    with patch.object(client._exporter, "export") as export:
+        with client.start_trace("agent"):
+            pass
+        client.close()
+        client.close()
+        assert client.closed
+        assert export.call_count == 1
+    with pytest.raises(RuntimeError, match="closed"):
+        client.start_trace("too-late")
+
+
+def test_buffer_is_bounded() -> None:
+    client = Spano(api_key="test-key", max_buffer_size=1, batch_size=100)
+    with patch.object(client._exporter, "export"):
+        with client.start_trace("first"):
+            pass
+        with client.start_trace("second"):
+            pass
+        assert len(client._buffer) == 1
+        assert client.dropped_spans == 1

spano-0.1.0/test/test_events.py

@@ -0,0 +1,53 @@
+import pytest
+
+from spano import Span, SpanKind, SpanStatus
+
+
+def test_span_generates_valid_ids() -> None:
+    span = Span(name="agent.run")
+    assert len(span.trace_id) == 32
+    assert len(span.span_id) == 16
+    assert span.trace_id != "0" * 32
+    assert span.span_id != "0" * 16
+
+
+def test_span_starts_unfinished() -> None:
+    span = Span(name="llm.call", kind=SpanKind.LLM)
+    assert span.end_time is None
+    assert span.duration_ms is None
+    assert span.status == SpanStatus.UNSET
+
+
+def test_span_finishes_successfully() -> None:
+    span = Span(name="tool.search")
+    span.finish()
+    assert span.end_time is not None
+    assert span.duration_ms is not None
+    assert span.duration_ms >= 0
+    assert span.status == SpanStatus.OK
+
+
+def test_error_span_requires_details() -> None:
+    span = Span(name="llm.call")
+    with pytest.raises(ValueError, match="error details"):
+        span.finish(status=SpanStatus.ERROR)
+
+
+def test_span_serializes_to_dict() -> None:
+    span = Span(name="agent.run", kind=SpanKind.AGENT)
+    data = span.to_dict()
+    assert data["name"] == "agent.run"
+    assert data["kind"] == "agent"
+    assert data["trace_id"] == span.trace_id
+    assert data["duration_ms"] is None
+
+
+def test_attributes_must_be_json_serializable() -> None:
+    with pytest.raises(ValueError, match="JSON-serializable"):
+        Span(name="bad", attributes={"object": object()})
+
+
+def test_set_attributes() -> None:
+    span = Span(name="agent")
+    span.set_attributes(model="gpt-test", token_count=12)
+    assert span.attributes == {"model": "gpt-test", "token_count": 12}

spano-0.1.0/uv.lock

@@ -0,0 +1,106 @@
+version = 1
+revision = 3
+requires-python = ">=3.11"
+
+[[package]]
+name = "build"
+version = "1.6.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "colorama", marker = "os_name == 'nt'" },
+    { name = "packaging" },
+    { name = "pyproject-hooks" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/bd/67/4898a44ea4f3f8e213b0954ec0aa0a16971d62a6212d6ea3931e97115b99/build-1.6.1.tar.gz", hash = "sha256:51cc11666391ab6f092070437ac747002ff46f3e4113a3622177ee6b488bfc53", size = 113427, upload-time = "2026-09-10T07:56:00.417Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ad/9b/9fb3585dabcd73a1b2a6267f63f62649347c9e6d072c9fde365b105abb2c/build-1.6.1-py3-none-any.whl", hash = "sha256:ecd351a4be9d35a9eaaba244a7687143c9c7d4aea6ac964e7e7ddab20cbcf4e7", size = 31179, upload-time = "2026-09-10T07:55:59.148Z" },
+]
+
+[[package]]
+name = "colorama"
+version = "0.4.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d8/53/6f443c9a4a8358a93a6792e2acffb9d9d5cb0a5cfd8802644b7b1c9a02e4/colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44", size = 27697, upload-time = "2022-10-25T02:36:22.414Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335, upload-time = "2022-10-25T02:36:20.889Z" },
+]
+
+[[package]]
+name = "iniconfig"
+version = "2.3.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/01/e1/2069291243c926a2ff1cd706c7f3eeb9b62144bf60f77c9fb9ff2fb26bd3/iniconfig-2.3.1.tar.gz", hash = "sha256:67f4b9c50da0dedf52af349e7749a80a9057a5031199791b906c3bb3ae878960", size = 21209, upload-time = "2026-10-06T22:48:38.076Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/56/43/4ca9e49d27a1fcf6bece6f6aec0ea46bb9112489b93d4b688fb415457bdb/iniconfig-2.3.1-py3-none-any.whl", hash = "sha256:9121e2c1fdb355232495be3194c8dfe87ccc2d5dee45947b78e68f499790d7a7", size = 7552, upload-time = "2026-10-06T22:48:36.959Z" },
+]
+
+[[package]]
+name = "packaging"
+version = "26.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/7d/fa/3944b40b07da9ce895c0e6303a5ab7d53da063554f534556b134a54d6093/packaging-26.3.tar.gz", hash = "sha256:94edc256424af38762eb31306eed28beb9f0efc50a8837492c9d6fd6004aed79", size = 313412, upload-time = "2026-08-04T18:15:28.737Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/63/34/ba1c580383c9eada3711951fef0795c80b829a078d72188184bcab9dd527/packaging-26.3-py3-none-any.whl", hash = "sha256:d7193f7c8e4e93f444fde0262bf90af30e16fa0ad0ad44cb553c87339b23cd1c", size = 129956, upload-time = "2026-08-04T18:15:27.159Z" },
+]
+
+[[package]]
+name = "pluggy"
+version = "1.7.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/bf/db/7fc19e6f2dc92a966727031389fc2e08b558f0f25eb7403c1119ad4713cd/pluggy-1.7.0.tar.gz", hash = "sha256:d1eaa46ebb595891b860ab086b4d09c8588af65ebd4361b8e8f4bb8920b90ba8", size = 123304, upload-time = "2026-10-15T09:50:58.343Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/40/9e/2b38731e0fc536806f16490e1a12d7f0dc2a1235aa8cc07bcc75416a7daa/pluggy-1.7.0-py3-none-any.whl", hash = "sha256:7dd7b0d8832ba3cb632c306926ded123429211b83641b35dc5c41ad2d34f9bec", size = 27082, upload-time = "2026-10-15T09:50:56.808Z" },
+]
+
+[[package]]
+name = "pygments"
+version = "2.21.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/49/2e/ced460408999b33da6b31b0021b0f37d329e202d4169aeb164493778f25b/pygments-2.21.0.tar.gz", hash = "sha256:610ca751c9bc2492b38eb9a38a7fbc93edbbb2d7182edaf34e66ae493dee5c8c", size = 5005329, upload-time = "2026-08-17T08:02:48.824Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/71/46/17f022dd3e953bf20a04a028a21ec746d942f8d2af30fa0f124fa0e6a684/pygments-2.21.0-py3-none-any.whl", hash = "sha256:2363c69b61c4a97c838da3b130dcd6468f4848992b21a82f2a63ec34377137d9", size = 1250147, upload-time = "2026-08-17T08:02:44.912Z" },
+]
+
+[[package]]
+name = "pyproject-hooks"
+version = "1.3.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/6d/5d/f2ddeef4a855a102aaae5e97826a0260007522ab504421b75addfdb1517c/pyproject_hooks-1.3.3.tar.gz", hash = "sha256:defda19b854fa0d3bd4f76ea4ddcba8abd7dcfcdd585a6690ade050744fc5f43", size = 21013, upload-time = "2026-09-16T08:58:03.999Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/85/11/044d1ae1b4ec0d7af88ee5bc91e081be1022533032b906a7bdabdbb60977/pyproject_hooks-1.3.3-py3-none-any.whl", hash = "sha256:5fc53fdac9f7bd63fbcdc868fb5f90b4784d78a53a3d3388cd738b807441a20b", size = 10724, upload-time = "2026-09-16T08:58:02.96Z" },
+]
+
+[[package]]
+name = "pytest"
+version = "9.1.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+    { name = "iniconfig" },
+    { name = "packaging" },
+    { name = "pluggy" },
+    { name = "pygments" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e4/47/b9efed96c114afcfa3c9d3fe98a76a1d14c74a9e266d397cf6eb64be5e01/pytest-9.1.1.tar.gz", hash = "sha256:1088fbde8f2b49d95a549a195707afa7a76a3ce9bcadc26b6d71f0ffda5fe313", size = 1636369, upload-time = "2026-06-19T10:58:32.857Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/24/25/1de2678b631f5a49215c6c96fff41ba892b0a34df68d6d80292b1b48aa7f/pytest-9.1.1-py3-none-any.whl", hash = "sha256:37a86b45efb9a47a61a36449063e8e18d0cab3161329fc099eb21783169c4f0c", size = 386536, upload-time = "2026-06-19T10:58:31.347Z" },
+]
+
+[[package]]
+name = "spano"
+version = "0.1.0"
+source = { editable = "." }
+
+[package.dev-dependencies]
+dev = [
+    { name = "build" },
+    { name = "pytest" },
+]
+
+[package.metadata]
+
+[package.metadata.requires-dev]
+dev = [
+    { name = "build", specifier = ">=1.0" },
+    { name = "pytest", specifier = ">=8.0" },
+]