spoor-sdk 0.0.1__tar.gz

spoor_sdk-0.0.1/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+.env
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+dist/

spoor_sdk-0.0.1/.python-version

@@ -0,0 +1 @@
+3.14

spoor_sdk-0.0.1/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.5
+Name: spoor-sdk
+Version: 0.0.1
+Summary: Send agent and LLM traces to Spoor
+Requires-Python: >=3.10
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.38
+Requires-Dist: opentelemetry-instrumentation-anthropic>=0.62
+Requires-Dist: opentelemetry-instrumentation-bedrock>=0.62
+Requires-Dist: opentelemetry-instrumentation-cohere>=0.62
+Requires-Dist: opentelemetry-instrumentation-crewai>=0.62
+Requires-Dist: opentelemetry-instrumentation-google-generativeai>=0.62
+Requires-Dist: opentelemetry-instrumentation-groq>=0.62
+Requires-Dist: opentelemetry-instrumentation-langchain>=0.62
+Requires-Dist: opentelemetry-instrumentation-litellm>=0.62
+Requires-Dist: opentelemetry-instrumentation-llamaindex>=0.62
+Requires-Dist: opentelemetry-instrumentation-mistralai>=0.62
+Requires-Dist: opentelemetry-instrumentation-ollama>=0.62
+Requires-Dist: opentelemetry-instrumentation-openai-agents>=0.62
+Requires-Dist: opentelemetry-instrumentation-openai>=0.62
+Requires-Dist: opentelemetry-sdk>=1.38
+Description-Content-Type: text/markdown
+
+# spoor-sdk
+
+Send agent and LLM traces to Spoor.
+
+```python
+import spoor
+
+spoor.init()  # reads SPOOR_API_KEY, SPOOR_URL (default http://localhost:8000)
+```
+
+`init()` turns on OpenLLMetry instrumentation for every installed library it supports
+(openai, anthropic, LangChain/LangGraph, litellm, OpenAI Agents SDK, CrewAI, LlamaIndex,
+google-genai, Bedrock, Mistral, Cohere, Groq, Ollama; see `src/spoor/libraries.py`) and exports
+spans over OTLP/HTTP. If the app already has an OTel `TracerProvider`, Spoor's exporter is added to it.
+
+Options: `api_key`, `url`, `service_name` (else `OTEL_SERVICE_NAME`, else the script name),
+`environment` (else `SPOOR_ENVIRONMENT`, else `main`).
+
+## Operations
+
+Each run belongs to an operation. It's named after the function that made the call, or explicitly:
+
+```python
+@spoor.operation("triage")          # or bare @spoor.operation, or `with spoor.operation("triage"):`
+def triage(ticket): ...
+```
+
+## Test
+
+```bash
+uv run pytest
+```

spoor_sdk-0.0.1/README.md

@@ -0,0 +1,32 @@
+# spoor-sdk
+
+Send agent and LLM traces to Spoor.
+
+```python
+import spoor
+
+spoor.init()  # reads SPOOR_API_KEY, SPOOR_URL (default http://localhost:8000)
+```
+
+`init()` turns on OpenLLMetry instrumentation for every installed library it supports
+(openai, anthropic, LangChain/LangGraph, litellm, OpenAI Agents SDK, CrewAI, LlamaIndex,
+google-genai, Bedrock, Mistral, Cohere, Groq, Ollama; see `src/spoor/libraries.py`) and exports
+spans over OTLP/HTTP. If the app already has an OTel `TracerProvider`, Spoor's exporter is added to it.
+
+Options: `api_key`, `url`, `service_name` (else `OTEL_SERVICE_NAME`, else the script name),
+`environment` (else `SPOOR_ENVIRONMENT`, else `main`).
+
+## Operations
+
+Each run belongs to an operation. It's named after the function that made the call, or explicitly:
+
+```python
+@spoor.operation("triage")          # or bare @spoor.operation, or `with spoor.operation("triage"):`
+def triage(ticket): ...
+```
+
+## Test
+
+```bash
+uv run pytest
+```

spoor_sdk-0.0.1/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "spoor-sdk"
+version = "0.0.1"
+description = "Send agent and LLM traces to Spoor"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "opentelemetry-sdk>=1.38",
+    "opentelemetry-exporter-otlp-proto-http>=1.38",
+    "opentelemetry-instrumentation-openai>=0.62",
+    "opentelemetry-instrumentation-anthropic>=0.62",
+    "opentelemetry-instrumentation-langchain>=0.62",
+    "opentelemetry-instrumentation-litellm>=0.62",
+    "opentelemetry-instrumentation-openai-agents>=0.62",
+    "opentelemetry-instrumentation-crewai>=0.62",
+    "opentelemetry-instrumentation-llamaindex>=0.62",
+    "opentelemetry-instrumentation-google-generativeai>=0.62",
+    "opentelemetry-instrumentation-bedrock>=0.62",
+    "opentelemetry-instrumentation-mistralai>=0.62",
+    "opentelemetry-instrumentation-cohere>=0.62",
+    "opentelemetry-instrumentation-groq>=0.62",
+    "opentelemetry-instrumentation-ollama>=0.62",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3",
+    "ruff>=0.7",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/spoor"]
+
+[tool.ruff]
+line-length = 100

spoor_sdk-0.0.1/src/spoor/__init__.py

@@ -0,0 +1,5 @@
+from spoor.operations import operation
+from spoor.setup import init
+
+__all__ = ["init", "operation"]
+__version__ = "0.1.0"

spoor_sdk-0.0.1/src/spoor/caller.py

@@ -0,0 +1,50 @@
+"""Name runs after the user code that started them: the first stack frame outside libraries."""
+
+import sys
+import sysconfig
+from pathlib import Path
+
+from opentelemetry.sdk.trace import SpanProcessor
+
+_LIBRARY_PATHS = tuple(
+    {sysconfig.get_path(p) for p in ("stdlib", "platstdlib", "purelib", "platlib")}
+    | {str(Path(__file__).parent)}
+)
+
+
+MAX_CALLERS = 5
+
+
+class CallerProcessor(SpanProcessor):
+    """Adds the calling user code to every root span: OTel `code.*` attributes for the innermost
+    user frame, plus `spoor.callers`, the user call chain (innermost first). A shared helper like
+    `ask()` is the innermost frame of many call types; the chain lets the server name each one."""
+
+    def on_start(self, span, parent_context=None) -> None:
+        if span.parent is not None and not span.parent.is_remote:
+            return
+        frames = user_frames()
+        if not frames:
+            return
+        frame = frames[0]
+        span.set_attribute("code.function.name", function_name(frame))
+        span.set_attribute("code.file.path", frame.f_code.co_filename)
+        span.set_attribute("code.line.number", frame.f_lineno)
+        span.set_attribute("spoor.callers", [function_name(f) for f in frames])
+
+
+def function_name(frame) -> str:
+    code = frame.f_code
+    if code.co_name == "<module>":  # top-level script code: use the file name
+        return Path(code.co_filename).stem
+    return getattr(code, "co_qualname", code.co_name)
+
+
+def user_frames() -> list:
+    frames, frame = [], sys._getframe(1)
+    while frame is not None and len(frames) < MAX_CALLERS:
+        filename = frame.f_code.co_filename
+        if not filename.startswith(_LIBRARY_PATHS) and not filename.startswith("<"):
+            frames.append(frame)
+        frame = frame.f_back
+    return frames

spoor_sdk-0.0.1/src/spoor/libraries.py

@@ -0,0 +1,49 @@
+"""Libraries `spoor.init()` instruments when they are installed, via OpenLLMetry instrumentors."""
+
+import importlib
+import logging
+from importlib.metadata import PackageNotFoundError, version
+
+logger = logging.getLogger("spoor")
+
+# (distribution the user has installed, instrumentor module, instrumentor class)
+LIBRARIES = [
+    ("openai", "opentelemetry.instrumentation.openai", "OpenAIInstrumentor"),
+    ("anthropic", "opentelemetry.instrumentation.anthropic", "AnthropicInstrumentor"),
+    ("langchain-core", "opentelemetry.instrumentation.langchain", "LangchainInstrumentor"),
+    ("litellm", "opentelemetry.instrumentation.litellm", "LiteLLMInstrumentor"),
+    ("openai-agents", "opentelemetry.instrumentation.openai_agents", "OpenAIAgentsInstrumentor"),
+    ("crewai", "opentelemetry.instrumentation.crewai", "CrewAIInstrumentor"),
+    ("llama-index-core", "opentelemetry.instrumentation.llamaindex", "LlamaIndexInstrumentor"),
+    ("google-genai", "opentelemetry.instrumentation.google_generativeai", "GoogleGenerativeAiInstrumentor"),
+    ("boto3", "opentelemetry.instrumentation.bedrock", "BedrockInstrumentor"),
+    ("mistralai", "opentelemetry.instrumentation.mistralai", "MistralAiInstrumentor"),
+    ("cohere", "opentelemetry.instrumentation.cohere", "CohereInstrumentor"),
+    ("groq", "opentelemetry.instrumentation.groq", "GroqInstrumentor"),
+    ("ollama", "opentelemetry.instrumentation.ollama", "OllamaInstrumentor"),
+]
+
+
+def installed(distribution: str) -> bool:
+    try:
+        version(distribution)
+        return True
+    except PackageNotFoundError:
+        return False
+
+
+def instrument() -> list[str]:
+    """Turn on the instrumentor for every installed library; returns the ones enabled."""
+    enabled = []
+    for library, module, cls in LIBRARIES:
+        if not installed(library):
+            continue
+        try:
+            instrumentor = getattr(importlib.import_module(module), cls)()
+            if not instrumentor.is_instrumented_by_opentelemetry:
+                instrumentor.instrument()
+            if instrumentor.is_instrumented_by_opentelemetry:
+                enabled.append(library)
+        except Exception:  # one broken instrumentor must not break the app
+            logger.warning("spoor: could not instrument %s", library, exc_info=True)
+    return enabled

spoor_sdk-0.0.1/src/spoor/operations.py

@@ -0,0 +1,58 @@
+import functools
+import inspect
+from collections.abc import Callable
+
+from opentelemetry import trace
+
+tracer = trace.get_tracer("spoor")
+
+
+def operation(name: str | Callable | None = None):
+    """Mark an operation: each call is one run in Spoor.
+
+        @spoor.operation                # named after the function
+        @spoor.operation("classify")    # explicit name
+        with spoor.operation("classify"): ...
+    """
+    if callable(name):
+        return _wrap(name, name.__name__)
+    return _Operation(name)
+
+
+class _Operation:
+    def __init__(self, name: str | None) -> None:
+        self.name = name
+
+    def __call__(self, fn: Callable) -> Callable:
+        return _wrap(fn, self.name or fn.__name__)
+
+    def __enter__(self):
+        self._span = _span(self.name or "operation")
+        return self._span.__enter__()
+
+    def __exit__(self, *exc_info):
+        return self._span.__exit__(*exc_info)
+
+
+def _span(name: str):
+    return tracer.start_as_current_span(
+        name, attributes={"spoor.operation.name": name, "traceloop.span.kind": "workflow"}
+    )
+
+
+def _wrap(fn: Callable, name: str) -> Callable:
+    if inspect.iscoroutinefunction(fn):
+
+        @functools.wraps(fn)
+        async def async_wrapper(*args, **kwargs):
+            with _span(name):
+                return await fn(*args, **kwargs)
+
+        return async_wrapper
+
+    @functools.wraps(fn)
+    def wrapper(*args, **kwargs):
+        with _span(name):
+            return fn(*args, **kwargs)
+
+    return wrapper

spoor_sdk-0.0.1/src/spoor/setup.py

@@ -0,0 +1,65 @@
+import logging
+import os
+import sys
+from pathlib import Path
+
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+from spoor import libraries
+from spoor.caller import CallerProcessor
+
+logger = logging.getLogger("spoor")
+
+_provider: TracerProvider | None = None
+
+
+def init(
+    api_key: str | None = None,
+    *,
+    url: str | None = None,
+    service_name: str | None = None,
+    environment: str | None = None,
+) -> TracerProvider:
+    """Send traces of every installed LLM/agent library to Spoor.
+
+    Arguments fall back to SPOOR_API_KEY, SPOOR_URL, OTEL_SERVICE_NAME and SPOOR_ENVIRONMENT.
+    If the app already has an OTel TracerProvider, Spoor's exporter is added to it.
+    """
+    global _provider
+    if _provider is not None:
+        return _provider
+
+    api_key = api_key or os.environ.get("SPOOR_API_KEY")
+    if not api_key:
+        raise ValueError("spoor.init(): pass api_key or set SPOOR_API_KEY")
+    url = (url or os.environ.get("SPOOR_URL", "http://localhost:8000")).rstrip("/")
+    exporter = OTLPSpanExporter(
+        endpoint=f"{url}/v1/traces", headers={"Authorization": f"Bearer {api_key}"}
+    )
+
+    provider = trace.get_tracer_provider()
+    if not isinstance(provider, TracerProvider):
+        provider = TracerProvider(resource=_resource(service_name, environment))
+        trace.set_tracer_provider(provider)
+    provider.add_span_processor(CallerProcessor())
+    provider.add_span_processor(BatchSpanProcessor(exporter))
+
+    enabled = libraries.instrument()
+    logger.info("spoor: sending traces to %s, instrumented: %s", url, ", ".join(enabled) or "none")
+    _provider = provider
+    return provider
+
+
+def _resource(service_name: str | None, environment: str | None) -> Resource:
+    attributes = {
+        "service.name": service_name
+        or os.environ.get("OTEL_SERVICE_NAME")
+        or Path(sys.argv[0]).stem
+        or "unknown_service",
+        "deployment.environment.name": environment or os.environ.get("SPOOR_ENVIRONMENT", "main"),
+    }
+    return Resource.create(attributes)

spoor_sdk-0.0.1/tests/test_init.py

@@ -0,0 +1,31 @@
+import pytest
+from opentelemetry.sdk.trace import TracerProvider
+
+import spoor
+from spoor import libraries, setup
+
+
+@pytest.fixture(autouse=True)
+def reset(monkeypatch):
+    monkeypatch.setattr(setup, "_provider", None)
+    monkeypatch.setattr(libraries, "instrument", list)
+    monkeypatch.delenv("SPOOR_API_KEY", raising=False)
+
+
+def test_requires_api_key():
+    with pytest.raises(ValueError, match="SPOOR_API_KEY"):
+        spoor.init()
+
+
+def test_init_sets_resource_and_is_idempotent(monkeypatch):
+    monkeypatch.setenv("SPOOR_API_KEY", "sk-test")
+    provider = spoor.init(service_name="billing", environment="staging")
+    assert isinstance(provider, TracerProvider)
+    assert provider.resource.attributes["service.name"] == "billing"
+    assert provider.resource.attributes["deployment.environment.name"] == "staging"
+    assert spoor.init() is provider
+
+
+def test_installed_checks_distributions():
+    assert libraries.installed("opentelemetry-sdk")
+    assert not libraries.installed("openai-agents")

spoor_sdk-0.0.1/tests/test_operations.py

@@ -0,0 +1,77 @@
+import asyncio
+
+import pytest
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+from opentelemetry.trace import StatusCode
+
+import spoor
+from spoor import operations
+from spoor.caller import CallerProcessor
+
+
+@pytest.fixture
+def spans(monkeypatch):
+    exporter = InMemorySpanExporter()
+    provider = TracerProvider()
+    provider.add_span_processor(CallerProcessor())
+    provider.add_span_processor(SimpleSpanProcessor(exporter))
+    monkeypatch.setattr(operations, "tracer", provider.get_tracer("test"))
+    return exporter.get_finished_spans
+
+
+def test_bare_decorator_uses_function_name(spans):
+    @spoor.operation
+    def classify_ticket(text):
+        return text.upper()
+
+    assert classify_ticket("hi") == "HI"
+    [span] = spans()
+    assert span.name == "classify_ticket"
+    assert span.attributes["spoor.operation.name"] == "classify_ticket"
+
+
+def test_named_decorator_on_async_function(spans):
+    @spoor.operation("triage")
+    async def handle():
+        return 1
+
+    assert asyncio.run(handle()) == 1
+    assert spans()[0].attributes["spoor.operation.name"] == "triage"
+
+
+def test_context_manager_records_errors(spans):
+    with pytest.raises(ValueError), spoor.operation("refund"):
+        raise ValueError("boom")
+    [span] = spans()
+    assert span.name == "refund"
+    assert span.status.status_code == StatusCode.ERROR
+
+
+def test_root_span_is_named_after_calling_function(spans):
+    def summarize_ticket():
+        tracer = operations.tracer
+        with tracer.start_as_current_span("openai.chat"), tracer.start_as_current_span("child"):
+            pass
+
+    summarize_ticket()
+    child, root = spans()
+    assert root.attributes["code.function.name"].endswith("summarize_ticket")
+    assert root.attributes["code.file.path"] == __file__
+    assert "code.function.name" not in child.attributes
+
+
+def test_root_span_records_the_user_call_chain(spans):
+    def ask():
+        with operations.tracer.start_as_current_span("openai.chat"):
+            pass
+
+    def summarize_ticket():
+        ask()
+
+    summarize_ticket()
+    callers = spans()[0].attributes["spoor.callers"]
+    assert [c.rsplit(".", 1)[-1] for c in callers[:3]] == [
+        "ask", "summarize_ticket", "test_root_span_records_the_user_call_chain"
+    ]