SDK Reference

Complete API reference for the ZenRay Python SDK.

Decorators

@ @xray.pipeline(name, version?) Entry point decorator

Marks a function as a pipeline entry point. Each invocation creates a new run that groups all steps together.

Parameters

Parameter	Type	Description
`name`	`str`	Unique identifier for this pipeline
`version`	`str`	Optional version string for A/B testing

Example

@xray.pipeline("search-pipeline", version="v2.0")
def search(query: str):
    results = retrieve(query)
    ranked = rank(results)
    return filter(ranked)

@ @xray.step(kind) Step decorator

Marks a function as a pipeline step. Automatically tracks input/output counts and duration.

Step Kinds

Kind	Use Case
`RETRIEVE`	Vector search, database queries, API calls
`FILTER`	Removing candidates based on rules
`RANK`	Scoring and sorting candidates
`LLM_CALL`	Calls to language model APIs
`JUDGE`	LLM-as-judge evaluation steps
`TRANSFORM`	Data transformation, preprocessing
`SELECT`	Selection, sampling, deduplication
`TOOL_CALL`	External tool or function calls

Example

@xray.step("FILTER")
def filter_by_score(items):
    for item in items:
        if item.score < 0.5:
            xray.drop(item, "low_score")
            continue
        yield item

Helper Functions

f xray.drop(item, reason) Track dropped candidates

Record that a candidate was dropped and why. This is the key function for understanding pipeline behavior.

Parameters

Parameter	Type	Description
`item`	`Any`	The candidate being dropped (serialized to JSON)
`reason`	`str`	Human-readable reason for dropping

Example

for item in items:
    if item.score < 0.3:
        xray.drop(item, "low_score")
        continue
    if not item.available:
        xray.drop(item, "out_of_stock")
        continue
    yield item

f xray.score(item, value) Record candidate scores

Record a score for a candidate. Builds histograms for analysis in the dashboard.

Example

for item in items:
    relevance = compute_relevance(item, query)
    xray.score(item, relevance)
    item.score = relevance

f xray.metric(key, value) Log key-value metrics

Record arbitrary key-value metrics for the current step. Useful for tracking model names, token counts, latencies.

Example

xray.metric("model", "gpt-4")
xray.metric("tokens", 1234)
xray.metric("latency_ms", 450)
xray.metric("cache_hit", True)

f xray.artifact(name, content) Store prompts and responses

Store artifacts like prompts, responses, or configurations for later inspection.

Example

xray.artifact("prompt", prompt_text)
xray.artifact("response", llm_response)
xray.artifact("config", {"temperature": 0.7, "model": "gpt-4"})

f xray.tag(key, value) Add searchable tags

Add searchable tags to the current run. Use for filtering runs in the dashboard.

Example

xray.tag("user_id", user.id)
xray.tag("experiment", "v2-embeddings")
xray.tag("environment", "production")

Configuration

⚙ xray.init(**kwargs) SDK initialization

Initialize the SDK with custom settings. Call once at application startup.

Example

xray.init(
    api_key="your-api-key",
    disabled=False,
    sample_rate=1.0,
    batch_size=10,
    flush_interval=1.0,
    top_k=10,
)

Options

Parameter	Default	Description
`api_key`	`None`	Your X-Ray API key
`disabled`	`False`	Disable all tracing
`sample_rate`	`1.0`	Fraction of runs to trace
`batch_size`	`10`	Events to batch before sending
`flush_interval`	`1.0`	Seconds between flushes
`top_k`	`10`	Top candidates to capture