respan-sdk | Respan Docs

Overview

respan-sdk is the foundational package that defines the shared vocabulary for the entire Respan Python ecosystem. It provides Pydantic types for log/span data, constant definitions for OTLP attributes and log types, filter types, and utility functions.

$ pip install respan-sdk

Version: 2.5.0 | Python: >3.9, <4.0

You typically do not install respan-sdk directly. It is installed automatically as a dependency of respan-tracing and respan-ai.

Package structure

respan_sdk/
  __init__.py            # Public exports
  respan_types/          # Pydantic models
    base_types.py        # RespanBaseModel
    log_types.py         # RespanLogParams, RespanFullLogParams
    param_types.py       # RespanParams, Customer, PromptParam, etc.
    filter_types.py      # FilterParamDict, MetricFilterParam, FilterBundle
    span_types.py        # RespanSpanAttributes enum, attribute maps
    ...
  constants/             # Shared constant definitions
    llm_logging.py       # LOG_TYPE_*, LogType, LogTypeChoices
    otlp_constants.py    # OTLP wire-format keys
    tracing_constants.py # Ingest endpoint, headers
  utils/                 # Serialization, preprocessing, retry

Public exports

1 from respan_sdk import (
2     # Types
3     RespanLogParams,
4     RespanFullLogParams,
5     RespanTextLogParams,    # Deprecated
6     RespanParams,           # Deprecated (use RespanLogParams)
7     EvaluationParams,
8     RetryParams,
9     Message,
10     Usage,
11 
12     # Filter types
13     FilterParamDict,
14     MetricFilterParam,
15     FilterBundle,
16     MetricFilterValueType,
17 
18     # Utilities
19     validate_and_separate_params,
20     validate_and_separate_log_and_llm_params,
21 )

Types

RespanLogParams

The primary type for structuring LLM call data. This is the “contract” between integrations and the Respan backend.

1 from respan_sdk import RespanLogParams

Field	Type	Description
`model`	`str`	LLM model name (e.g. `"gpt-4o"`, `"claude-sonnet-4-5-20250929"`).
`prompt_messages`	`list[Message]`	Input messages sent to the LLM.
`completion_message`	`Message`	The LLM’s response message.
`prompt_tokens`	`int \| None`	Input token count.
`completion_tokens`	`int \| None`	Output token count.
`cost`	`float \| None`	Estimated cost in USD.
`latency`	`float \| None`	Request latency in seconds.
`status_code`	`int \| None`	HTTP-style status code (200 = OK, 400+ = error).
`customer_identifier`	`str \| None`	User/customer identifier for grouping.
`customer_email`	`str \| None`	Customer email address.
`customer_name`	`str \| None`	Customer display name.
`metadata`	`dict \| None`	Arbitrary key-value metadata.
`stream`	`bool \| None`	Whether the request used streaming.

All fields are optional except in the context of validate_and_separate_params(), which enforces minimum requirements for the Respan API.

RespanFullLogParams

Extended version of RespanLogParams with backend-only fields. Used internally by the Respan backend — integrations should not use this directly.

Additional fields beyond RespanLogParams:

Field	Type	Description
`log_type`	`LogType`	Classification: `"chat"`, `"embedding"`, `"tool"`, etc.
`organization_id`	`int`	Respan organization ID.
`is_batch`	`bool`	Whether this is a batch API request.
`failed`	`bool`	Whether the request failed.

Message

1 from respan_sdk import Message

Field	Type	Description
`role`	`str`	Message role: `"system"`, `"user"`, `"assistant"`, `"tool"`.
`content`	`str \| None`	Text content of the message.
`tool_calls`	`list \| None`	Tool calls made by the assistant.

Usage

1 from respan_sdk import Usage

Field	Type	Description
`prompt_tokens`	`int`	Input token count.
`completion_tokens`	`int`	Output token count.
`total_tokens`	`int`	Total token count.

Constants

Log type constants

Used by instrumentation plugins to set respan.entity.log_type on spans.

1 from respan_sdk.constants.llm_logging import (
2     LOG_TYPE_WORKFLOW,     # "workflow"
3     LOG_TYPE_AGENT,        # "agent"
4     LOG_TYPE_TOOL,         # "tool"
5     LOG_TYPE_GENERATION,   # "generation"
6     LOG_TYPE_RESPONSE,     # "response"
7     LOG_TYPE_HANDOFF,      # "handoff"
8     LOG_TYPE_GUARDRAIL,    # "guardrail"
9     LOG_TYPE_CUSTOM,       # "custom"
10 )

Constant	Value	Description
`LOG_TYPE_WORKFLOW`	`"workflow"`	Root-level workflow/trace span.
`LOG_TYPE_AGENT`	`"agent"`	Agent execution span.
`LOG_TYPE_TOOL`	`"tool"`	Tool/function call span.
`LOG_TYPE_GENERATION`	`"generation"`	LLM generation (Chat Completions API).
`LOG_TYPE_RESPONSE`	`"response"`	LLM response (Responses API).
`LOG_TYPE_HANDOFF`	`"handoff"`	Agent-to-agent handoff.
`LOG_TYPE_GUARDRAIL`	`"guardrail"`	Guardrail check span.
`LOG_TYPE_CUSTOM`	`"custom"`	Custom user-defined span.

LogType / LogTypeChoices

1 from respan_sdk.constants.llm_logging import LogType, LogTypeChoices
2 
3 # LogType is a Literal type for type checking
4 x: LogType = "chat"
5 
6 # LogTypeChoices is an enum for runtime validation
7 LogTypeChoices.CHAT.value  # "chat"

OTLP constants

Wire-format keys for OTLP JSON serialization. Used by the exporter — not typically needed by integrations.

1 from respan_sdk.constants.otlp_constants import (
2     OTLP_STRING_VALUE,       # "stringValue"
3     OTLP_INT_VALUE,          # "intValue"
4     OTLP_TRACE_ID_KEY,       # "traceId"
5     OTLP_SPAN_ID_KEY,        # "spanId"
6     OTLP_ATTRIBUTES_KEY,     # "attributes"
7     OTLP_RESOURCE_SPANS_KEY, # "resourceSpans"
8     # ... and more
9 )

Tracing constants

1 from respan_sdk.constants.tracing_constants import (
2     RESPAN_TRACING_INGEST_ENDPOINT,    # "/v2/traces"
3     RESPAN_DOGFOOD_HEADER,             # "X-Respan-Dogfood"
4     resolve_tracing_ingest_endpoint,   # function
5 )

Filter types

FilterParamDict

Dict-based filter specification for controlling span export. Used with the export_filter parameter on decorators.

1 from respan_sdk import FilterParamDict
2 
3 # Only export spans where status_code is "ERROR"
4 filter_spec: FilterParamDict = {
5     "status_code": {
6         "operator": "",       # "" means "equals"
7         "value": "ERROR"
8     }
9 }

Supported operators: "" (equals), "not", "gt", "gte", "lt", "lte", "contains", "icontains", "startswith", "endswith", "regex", "in", "not_in", "empty", "not_empty".

MetricFilterParam

Single field filter condition.

1 from respan_sdk import MetricFilterParam
2 
3 condition = MetricFilterParam(
4     field="status_code",
5     operator="gte",
6     value=400
7 )

FilterBundle

Collection of filter conditions with AND logic.

1 from respan_sdk import FilterBundle
2 
3 bundle = FilterBundle(filters=[
4     MetricFilterParam(field="model", operator="contains", value="gpt"),
5     MetricFilterParam(field="status_code", operator="", value=200),
6 ])

Span attributes

RespanSpanAttributes

Enum of Respan-specific span attribute keys.

1 from respan_sdk.respan_types.span_types import RespanSpanAttributes
2 
3 RespanSpanAttributes.RESPAN_CUSTOMER_IDENTIFIER.value
4 # "respan.customer_params.customer_identifier"
5 
6 RespanSpanAttributes.RESPAN_THREAD_IDENTIFIER.value
7 # "respan.threads.thread_identifier"
8 
9 RespanSpanAttributes.RESPAN_METADATA.value
10 # "respan.metadata"
11 
12 RespanSpanAttributes.RESPAN_TRACE_GROUP_ID.value
13 # "respan.trace_group.group_identifier"

RESPAN_SPAN_ATTRIBUTES_MAP

Maps friendly parameter names to their full OTEL attribute keys.

1 from respan_sdk.respan_types.span_types import RESPAN_SPAN_ATTRIBUTES_MAP
2 
3 RESPAN_SPAN_ATTRIBUTES_MAP["customer_identifier"]
4 # "respan.customer_params.customer_identifier"
5 
6 RESPAN_SPAN_ATTRIBUTES_MAP["thread_identifier"]
7 # "respan.threads.thread_identifier"

Base types

RespanBaseModel

All Respan types inherit from RespanBaseModel, which extends Pydantic’s BaseModel with dict-compatible access methods.

1 from respan_sdk.respan_types.base_types import RespanBaseModel

Method	Description
`__contains__(key)`	Check if a field exists: `"model" in params`
`get(key, default)`	Dict-style access: `params.get("model", "unknown")`
`__getitem__(key)`	Bracket access: `params["model"]`
`__setitem__(key, value)`	Bracket assignment: `params["model"] = "gpt-4o"`

This means Respan types work interchangeably with both Pydantic attribute access (params.model) and dict-style access (params["model"]).