wauldo 0.9.0

Official Python SDK for Wauldo — Verified AI answers from your documents

Wauldo Python SDK

Verified AI answers from your documents — or no answer at all.

Most RAG APIs guess. Wauldo verifies.

0% hallucination  |  83% accuracy  |  61 eval tasks  |  14 LLMs tested

     

Demo • Docs • Free API Key • Benchmarks

---

Quickstart (30 seconds)

pip install wauldo

Guard — catch hallucinations in 3 lines

from wauldo import HttpClient

client = HttpClient(base_url="https://api.wauldo.com", api_key="YOUR_API_KEY")

result = client.guard(
    text="Returns are accepted within 60 days.",
    source_context="Our policy allows returns within 14 days.",
)
print(result.verdict)       # "rejected"
print(result.claims[0].reason)  # "numerical_mismatch"

Verified RAG — upload, ask, verify

client.rag_upload(content="Our refund policy allows returns within 60 days...", filename="policy.txt")

result = client.rag_query("What is the refund policy?")
print(result.answer)        # Verified answer with sources
print(result.sources)       # [RagSource(document_id='...', score=0.95)]

Deployed Agents — create, run, stream

from wauldo import AgentsClient

agents = AgentsClient(
    base_url="https://api.wauldo.com",
    api_key="YOUR_API_KEY",
    tenant="my-tenant",
)

agent = agents.create(
    name="support-bot",
    description="Answers refund questions",
    wauldo_toml='[agent]\nname = "support-bot"\n[model]\nprovider = "openrouter"\nname = "auto"',
    preset="general_task",  # or "rust_backend_architect", "rag_data_engineer", etc.
)

run = agents.run(agent.id, input="Can I return a shirt 30 days after purchase?")

# Stream reasoning live as each workflow state completes
for event in agents.stream_task(run.task_id):
    print(f"  {event.state_name}: {event.duration_ms}ms  ({event.completion_tokens} tok)")

# Or poll for the final verified result
task = agents.wait_for_task(run.task_id, timeout_sec=120)
print(task.result)                         # The answer
print(task.verification.verdict)           # SAFE | UNVERIFIED | BLOCK | …
print(task.verification.trust_score)       # 0.0 – 1.0
print(task.verification.message)           # Human-readable context when non-SAFE

Try the demo | Get a free API key

---

Why Wauldo (and not standard RAG)

Typical RAG pipeline

retrieve → generate → hope it's correct

Wauldo pipeline

retrieve → extract facts → generate → verify → return or refuse

If the answer can't be verified, it returns "insufficient evidence" instead of guessing.

See the difference

Document: "Refunds are processed within 60 days"

Typical RAG:  "Refunds are processed within 30 days"     ← wrong
Wauldo:       "Refunds are processed within 60 days"     ← verified
              or "insufficient evidence" if unclear       ← safe

---

Examples

Upload a PDF and ask questions

result = client.upload_file("contract.pdf", title="Q3 Contract")
print(f"Extracted {result.chunks_count} chunks")

result = client.rag_query("What are the payment terms?")
print(f"Answer: {result.answer}")
print(f"Confidence: {result.get_confidence():.0%}")

Chat (OpenAI-compatible)

reply = client.chat_simple("auto", "Explain Python decorators")
print(reply)

Streaming

from wauldo import ChatRequest, HttpChatMessage

request = ChatRequest(model="auto", messages=[HttpChatMessage.user("Hello!")])
for chunk in client.chat_stream(request):
    print(chunk, end="", flush=True)

---

Features

• Pre-generation fact extraction — numbers, dates, limits injected as constraints before the LLM call
• Post-generation grounding check — every answer verified against sources
• Guard API — verify any claim against any source (3 modes: lexical, hybrid, semantic)
• Native PDF/DOCX upload — server-side extraction with quality scoring
• Smart model routing — auto-selects cheapest model that meets quality
• OpenAI-compatible — swap your base_url, keep your existing code
• Sync — simple, synchronous API

---

Built For

• Production RAG systems that need reliable answers
• Teams where "confidently wrong" is unacceptable
• Legal, finance, healthcare, support automation
• Anyone replacing "hope-based" RAG

---

Benchmarks

Metric	Result
Hallucination rate	0%
Accuracy	83% (17% = correct refusals)
Eval tasks	61
LLMs tested	14 models, 3 runs each
Avg latency	~1.2s

---

Error Handling

from wauldo import WauldoError, ServerError, AgentTimeoutError

try:
    response = client.chat(ChatRequest.quick("auto", "Hello"))
except ServerError as e:
    print(f"Server error: {e}")
except AgentTimeoutError:
    print("Request timed out")
except WauldoError as e:
    print(f"SDK error: {e}")

---

RapidAPI

client = HttpClient(
    base_url="https://api.wauldo.com",
    headers={
        "X-RapidAPI-Key": "YOUR_RAPIDAPI_KEY",
        "X-RapidAPI-Host": "smart-rag-api.p.rapidapi.com",
    },
)

Free tier (300 req/month): RapidAPI

---

Contributing

PRs welcome. Check the good first issues.

Contributors

• @qorexdev — async client

License

MIT — see LICENSE