Python SDK

pip install seer-sdk

# With OpenTelemetry support (optional)
pip install seer-sdk opentelemetry-api

from seer import SeerClient

client = SeerClient()  # reads SEER_API_KEY from env

client.log(
    task="How do I reset my password?",
    context=[
        {"text": "To reset your password, go to Settings...", "score": 0.89}
    ],
)
# Events auto-flush on process exit

client = SeerClient(
    api_key="seer_live_...",           # or from SEER_API_KEY env
    fire_and_forget=True,              # async (default) or sync
    max_queue_size=10_000,             # max events before dropping
    flush_interval=0.5,                # worker flush interval (seconds)
    timeout=5.0,                       # HTTP timeout
)

client.log(
    # Required
    task: str,                                # The user query
    context: list[dict | str],                # Retrieved passages

    # Metadata
    metadata: dict | None = None,             # Free-form metadata

    # OpenTelemetry (auto-detected by default)
    trace_id: str | None = None,              # OTEL trace ID (32 hex)
    span_id: str | None = None,               # OTEL span ID (16 hex)
    parent_span_id: str | None = None,        # OTEL parent span ID
    span_name: str | None = None,             # Operation type
    use_otel_trace: bool = True,              # Auto-detect OTEL context

    # Multi-hop / Agentic
    is_final_context: bool = False,           # Mark as final evidence
    subquery: str | None = None,              # Decomposed sub-question

    # Accuracy testing
    ground_truth: dict | None = None,         # For comparing against expected

    # Other options
    created_at: str | None = None,            # ISO8601 timestamp override
    sample_rate: float | None = None,         # 0.0-1.0 sampling rate
) -> str | None

client.flush(timeout: float | None = None)

stats = client.stats()
print(f"Sent: {stats.events_sent}, Failed: {stats.events_failed}")

@dataclass
class ClientStats:
    events_enqueued: int = 0
    events_sent: int = 0
    events_dropped: int = 0
    events_failed: int = 0
    bytes_sent: int = 0
    last_error: str | None = None

client.close()

# Simple strings
context = ["Passage one...", "Passage two..."]

# Passage objects (recommended)
context = [
    {
        "text": "The main content...",    # Required
        "score": 0.95,                     # Optional: retrieval score
        "id": "doc-123",                   # Optional: document ID
        "source": "wiki",                  # Optional: source name
        "metadata": {"author": "..."},     # Optional: custom metadata
    }
]

from seer import seer_trace

@seer_trace(
    task_arg="query",           # which argument is the query
    context_from_return=True,   # return value is the context
    metadata={"service": "help-bot"},
    sample_rate=0.10,
)
def retrieve(query: str) -> list[dict]:
    return [{"text": "Result...", "score": 0.9}]

# Automatically logged when called
results = retrieve("How do I reset my password?")

client = SeerClient()  # fire_and_forget=True
client.log(task="...", context=[...])  # returns None, queued
# Auto-flushes on process exit

client = SeerClient(fire_and_forget=False)
record_id = client.log(task="...", context=[...])
print(f"Created: {record_id}")

from opentelemetry import trace

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("retrieval"):
    # trace_id, span_id, span_name are captured automatically
    client.log(task="...", context=[...])

client.log(
    task="...",
    context=[...],
    trace_id="0af7651916cd43dd8448eb211c80319c",
    span_id="b7ad6b7169203331",
    span_name="retrieval",
    use_otel_trace=False,  # disable auto-detection
)

client.log(
    task="What is machine learning?",
    context=[
        {"text": "ML is a subset of AI...", "id": "doc-ml-intro"},
        {"text": "Neural networks learn from data...", "id": "doc-nn-basics"},
    ],
    ground_truth={
        # Document IDs that are relevant (matched against passage.id)
        "gold_doc_ids": ["doc-ml-intro", "doc-nn-basics"],
        "answer": "ML is a type of AI that learns from data",  # optional
    },
)

from seer import seer_log

seer_log(
    task="Quick question",
    context=[{"text": "Answer..."}],
)