Documentation Index
Fetch the complete documentation index at: https://docs.valiqor.com/llms.txt
Use this file to discover all available pages before exploring further.
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. |
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. |
| 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 |
