Trace, RAG & Async Models

Async Job Models

`AsyncJobHandle`

Generic async job handle used by failure analysis and other modules. Wraps polling, cancellation, and result retrieval.

Property/Method	Return Type	Description
`job_id`	`str`	Job identifier.
`job_type`	`str`	Job type string.
`status()`	`AsyncJobStatus`	Poll current status.
`is_running()`	`bool`	Whether still running.
`is_completed()`	`bool`	Whether completed.
`cancel()`	`Dict[str, Any]`	Cancel the job.
`result()`	`Any`	Block until complete and return result. Raises `RuntimeError` if failed.
`wait(poll_interval, timeout, on_progress)`	`AsyncJobStatus`	Poll with progress callback. Raises `TimeoutError` if exceeded.

wait() parameters:

Parameter	Type	Default	Description
`poll_interval`	`float`	`2.0`	Seconds between polls.
`timeout`	`Optional[float]`	`None`	Max wait time in seconds. `None` = no timeout.
`on_progress`	`Optional[Callable]`	`None`	Callback receiving `AsyncJobStatus`.

`AsyncJobStatus`

Field	Type	Description
`job_id`	`str`	Job identifier.
`job_type`	`str`	Job type.
`status`	`str`	`"queued"`, `"running"`, `"processing"`, `"completed"`, `"failed"`, `"cancelled"`.
`progress_percent`	`float`	Progress (0–100).
`current_item`	`int`	Current item.
`total_items`	`int`	Total items.
`started_at`	`Optional[str]`	ISO timestamp.
`finished_at`	`Optional[str]`	ISO timestamp.
`error`	`Optional[str]`	Error message.

Properties: is_running, is_completed, is_failed.

Trace Models

`TraceRecord`

A trace summary in a list response.

Field	Type	Description
`trace_id`	`str`	Trace identifier.
`project_id`	`str`	Project ID.
`status`	`str`	Trace status.
`session_id`	`Optional[str]`	Session identifier.
`project_name`	`Optional[str]`	Project name.
`app_name`	`Optional[str]`	Application name.
`duration_ms`	`Optional[float]`	Total duration in milliseconds.
`total_cost`	`Optional[float]`	Estimated cost in USD.
`total_tokens`	`Optional[int]`	Total tokens used.
`llm_calls`	`Optional[int]`	Number of LLM calls.
`tool_calls`	`Optional[int]`	Number of tool calls.
`input_preview`	`Optional[str]`	Truncated input text.
`output_preview`	`Optional[str]`	Truncated output text.
`eval_available`	`bool`	Whether evaluation data exists.
`created_at`	`Optional[str]`	ISO timestamp.

`TraceListResponse`

Paginated list of traces. Supports len() and iteration.

Field	Type
`traces`	`List[TraceRecord]`
`total`	`int`
`page`	`int`
`page_size`	`int`

`TraceOverview`

Basic trace information.

Field	Type
`trace_id`	`str`
`status`	`str`
`duration_ms`	`Optional[float]`
`total_cost`	`Optional[float]`
`llm_calls`	`Optional[int]`
`tool_calls`	`Optional[int]`

`TraceSummary`

Detailed trace summary with full metadata.

Field	Type	Description
`trace_id`	`str`	Trace identifier.
`project_id`	`str`	Project ID.
`status`	`str`	Trace status.
`duration_ms`	`Optional[float]`	Duration in milliseconds.
`total_cost`	`Optional[float]`	Estimated cost.
`total_tokens`	`Optional[int]`	Total tokens.
`input_tokens`	`Optional[int]`	Input tokens.
`output_tokens`	`Optional[int]`	Output tokens.
`llm_calls`	`Optional[int]`	LLM call count.
`tool_calls`	`Optional[int]`	Tool call count.
`retrieval_calls`	`Optional[int]`	Retrieval call count.
`message_count`	`int`	Number of messages.
`span_count`	`int`	Number of spans.
`tags`	`Optional[List[str]]`	Trace tags.
`custom_fields`	`Optional[Dict]`	Custom metadata.

`TraceMessage`

A message in a trace’s conversation.

Field	Type
`role`	`str`
`content`	`str`
`timestamp`	`Optional[str]`
`tool_calls`	`Optional[List[Dict]]`
`tool_call_id`	`Optional[str]`
`name`	`Optional[str]`

`TraceSpan`

A span in a trace’s execution tree.

Field	Type
`span_id`	`str`
`name`	`str`
`kind`	`str`
`parent_span_id`	`Optional[str]`
`start_time`	`Optional[str]`
`end_time`	`Optional[str]`
`duration_ms`	`Optional[float]`
`status`	`Optional[str]`
`attributes`	`Dict[str, Any]`
`events`	`List[Dict[str, Any]]`

`TraceFullResult`

Complete trace data including messages, spans, retrievals, and execution tree.

Field	Type
`trace_id`	`str`
`metadata`	`Dict[str, Any]`
`summary`	`Dict[str, Any]`
`messages`	`List[Dict[str, Any]]`
`spans`	`Dict[str, Any]`
`retrievals`	`List[Dict[str, Any]]`
`diagnostics`	`Optional[Dict]`
`execution_tree`	`Optional[Dict]`

`TraceEvalStep`

An evaluation step computed from a trace.

Field	Type
`metric`	`str`
`score`	`Optional[float]`
`explanation`	`Optional[str]`
`status`	`str`
`input_text`	`Optional[str]`
`output_text`	`Optional[str]`
`context`	`Optional[str]`

RAG Models

`DocumentHit`

A document match from a retrieval step.

Field	Type	Description
`doc_id`	`str`	Document identifier.
`rank`	`int`	Rank position.
`score`	`float`	Similarity/relevance score.
`span`	`Optional[List[int]]`	`[start, end]` character positions.
`snippet_preview`	`Optional[str]`	First 200 characters.
`metadata`	`Optional[Dict]`	Custom document metadata.

`RetrievalInfo`

Information about a retrieval step.

Field	Type	Description
`retriever`	`str`	Retriever type: `"vectordb"`, `"bm25"`, `"api"`, `"hybrid"`.
`embedding_model`	`Optional[str]`	Embedding model used.
`chunk_size`	`Optional[int]`	Chunk size in tokens.
`chunk_overlap`	`Optional[int]`	Chunk overlap.
`top_k`	`Optional[int]`	Number of results requested.
`similarity_threshold`	`Optional[float]`	Minimum similarity score.
`query`	`Optional[str]`	The retrieval query.
`hits`	`Optional[List[DocumentHit]]`	Retrieved documents.
`latency_ms`	`Optional[float]`	Retrieval latency.

`Citation`

A citation linking a generated answer to a source document.

Field	Type
`doc_id`	`str`
`span`	`Optional[List[int]]`
`confidence`	`Optional[float]`
`relevance_score`	`Optional[float]`

`GenerationInfo`

Information about a generation step.

Field	Type	Description
`answer`	`str`	Generated answer.
`citations`	`Optional[List[Citation]]`	Source citations.
`format_check`	`Optional[FormatCheck]`	Output format analysis.
`model_used`	`Optional[str]`	Model used.
`prompt_template`	`Optional[str]`	Template used.
`context_length`	`Optional[int]`	Context window used.
`generation_latency_ms`	`Optional[float]`	Generation latency.
`reasoning_trace`	`Optional[List[str]]`	Reasoning steps.

`FormatCheck`

Output format analysis.

Field	Type	Default
`is_complete`	`bool`	`True`
`length_tokens`	`Optional[int]`	`None`
`length_chars`	`Optional[int]`	`None`
`refusal`	`bool`	`False`
`contains_citations`	`bool`	`False`
`citation_count`	`Optional[int]`	`None`
`language`	`Optional[str]`	`None`
`format_type`	`Optional[str]`	`None`

TraceQueryClient — Methods returning trace models
Tracer — Methods using RAG models
Evaluation Models — Eval data models

Client

Modules

Utilities

Trace, RAG & Async Models

Async Job Models

`AsyncJobHandle`

`AsyncJobStatus`

Trace Models

`TraceRecord`

`TraceListResponse`

`TraceOverview`

`TraceSummary`

`TraceMessage`

`TraceSpan`

`TraceFullResult`

`TraceEvalStep`

RAG Models

`DocumentHit`

`RetrievalInfo`

`Citation`

`GenerationInfo`

`FormatCheck`

​Async Job Models

​AsyncJobHandle

​AsyncJobStatus

​Trace Models

​TraceRecord

​TraceListResponse

​TraceOverview

​TraceSummary

​TraceMessage

​TraceSpan

​TraceFullResult

​TraceEvalStep

​RAG Models

​DocumentHit

​RetrievalInfo

​Citation

​GenerationInfo

​FormatCheck

​Related

Async Job Models

`AsyncJobHandle`

`AsyncJobStatus`

Trace Models

`TraceRecord`

`TraceListResponse`

`TraceOverview`

`TraceSummary`

`TraceMessage`

`TraceSpan`

`TraceFullResult`

`TraceEvalStep`

RAG Models

`DocumentHit`

`RetrievalInfo`

`Citation`

`GenerationInfo`

`FormatCheck`

Related