Context & Event Schema

{
    "text": str,              # Required: the passage content
    "id": str,                # Optional: your passage/document ID
    "source": str,            # Optional: e.g., "wiki", "notion", "pdf:foo.pdf"
    "score": float,           # Optional: retrieval/relevance score (0.0-1.0)
    "metadata": dict,         # Optional: free-form attributes (collection, author, etc.)
}

context = [
    "Christopher Nolan directed Inception.",
    "Nolan is British-American."
]

context = [
    {
        "text": "Christopher Nolan directed Inception.",
        "id": "doc-001",
        "source": "wiki",
        "score": 0.95,
    },
    {
        "text": "Nolan is British-American.",
        "id": "doc-002",
        "source": "wiki",
        "score": 0.89,
    }
]

client.log(
    # Required
    task=str,                                # The user query
    context=list[dict | str],                # Passage list

    # Metadata (free-form filtering)
    metadata=dict | None,                    # env, user_id, etc.

    # OpenTelemetry (auto-detected by default)
    trace_id=str | None,                     # Auto-detected from OTEL context
    span_id=str | None,                      # Auto-detected from OTEL context
    parent_span_id=str | None,               # OTEL parent span ID
    span_name=str | None,                    # Auto-detected from OTEL span name
    use_otel_trace=bool,                     # Enable auto-detection (default: True)

    # Multi-hop / Agentic retrieval
    is_final_context=bool,                   # Mark as final evidence for LLM/agent
    subquery=str | None,                     # Decomposed sub-question for this hop

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

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

POST /v1/log
Authorization: Bearer seer_live_...
Content-Type: application/json

{
  "task": "Who directed Inception and what is their nationality?",
  "context": [
    {
      "text": "Christopher Nolan directed Inception.",
      "id": "doc-001",
      "source": "wiki",
      "score": 0.95
    },
    {
      "text": "Nolan is British-American.",
      "id": "doc-002",
      "source": "wiki",
      "score": 0.89
    }
  ],
  "metadata": {
    "env": "prod",
    "index_version": "v1"
  },
  "span_name": "retrieval",
  "sample_rate": 0.25
}

{
  "record_id": "rec_01HQXYZ...",
  "accepted": true
}

client.log(
    task="...",
    context=[...],
    metadata={
        "feature_flag": "retrieval-v2",  # for A/B testing
        "env": "prod",
        "index": "kb-prod",
    },
)

# All spans in this trace will be sampled together
with tracer.start_as_current_span("multi_hop_query"):
    client.log(task=query, context=hop1_results, span_name="retrieval_hop_1")
    client.log(task=query, context=hop2_results, span_name="retrieval_hop_2")
    # Both logs get the same sampling decision

client.log(
    task="What awards did the director of Inception win?",
    context=final_context,
    is_final_context=True,  # This context is what the LLM sees
)

# Original question requires multiple pieces of information
original_query = "What awards did the director of Inception win?"

# Hop 1: Find the director
client.log(
    task=original_query,                    # Keep original query
    context=hop1_results,
    subquery="Who directed Inception?",     # What this hop answers
    span_name="retrieval_hop_1",
)

# Hop 2: Find awards for that director
client.log(
    task=original_query,                    # Same original query
    context=hop2_results,
    subquery="What awards has Christopher Nolan won?",  # Rewritten with entity
    span_name="retrieval_hop_2",
    is_final_context=True,
)

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

        # Expected answer (optional)
        "answer": "Machine learning is a type of AI that learns from data",
    },
)

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