traceroai 0.2.0

Python SDK for sending RAG traces to TraceroAI

TraceroAI Python SDK

Send RAG traces to TraceroAI — a RAG observability and evaluation platform. Instrument any RAG pipeline (LangChain, LlamaIndex, or your own) and every answer becomes a debuggable trace.

Install

pip install traceroai

Usage

Context manager (recommended)

Times the block and sends the trace automatically:

from traceroai import TraceroClient

client = TraceroClient(
    base_url="https://traceroai.onrender.com",
    api_key="your_project_key",
)

with client.trace("How long does a refund take?") as t:
    t.log_retrieval(chunks, strategy="hybrid", config={"final_top_k": 3})
    t.log_prompt(prompt_text, version="grounded_v1")
    t.log_generation(answer, model="gpt-4o-mini")

print(t.trace_id)

Decorator

For a function that returns (answer, chunks):

@client.traced(model="gpt-4o-mini", strategy="hybrid")
def answer(query: str):
    chunks = retrieve(query)
    return generate(query, chunks), chunks

answer("What is the maximum file upload size?")  # traced automatically

Low-level

client.log_trace(
    query={"original": question},
    retrieval={"strategy": "hybrid", "chunks": chunks},
    generation={"model": "gpt-4o-mini", "answer": answer},
)

Authentication (multi-tenant)

Pass your project API key; the server attributes traces to your project:

client = TraceroClient(base_url="https://traceroai.onrender.com", api_key="your_project_key")

Self-healing recovery (optional)

pip install "traceroai[recovery]"

RecoveryAgent (built on LangGraph) retries the RAG stage that TraceroAI diagnoses as broken — re-retrieving on a retrieval miss, re-generating with a stricter prompt on an unsupported claim — until the answer is healthy or it escalates to review. You supply your own retrieve/generate; every attempt is traced.

from traceroai.recovery import RecoveryAgent

agent = RecoveryAgent(client, retrieve=my_retrieve, generate=my_generate, max_attempts=3)
result = agent.run("How long does a refund take?")
# result["answer"], result["diagnosis"], result["attempts"], result["trace_ids"]