Quickstart (30 seconds)

npm install wauldo

import { HttpClient } from 'wauldo';

const client = new HttpClient({ baseUrl: 'https://api.wauldo.com', apiKey: 'YOUR_API_KEY' });

// Upload a document
await client.ragUpload('Our refund policy allows returns within 60 days...', 'policy.txt');

// Ask a question — answer is verified against the source
const result = await client.ragQuery('What is the refund policy?');
console.log(result.answer);
console.log(result.sources);

Output:
Answer: Returns are accepted within 60 days of purchase.
Sources: policy.txt — "Our refund policy allows returns within 60 days"
Grounded: true | Confidence: 0.92

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

// Upload — text extraction + quality scoring happens server-side
const upload = await client.uploadFile(filePath, { title: 'Q3 Contract' });
console.log(`Extracted ${upload.chunks_count} chunks, quality: ${upload.quality_label}`);

// Query
const result = await client.ragQuery('What are the payment terms?');
console.log(`Answer: ${result.answer}`);
console.log(`Confidence: ${Math.round(result.audit.confidence * 100)}%`);
console.log(`Grounded: ${result.audit.grounded}`);

Guard — fact-check any LLM output

const result = await client.guard(
  'Returns are accepted within 60 days.',
  'Our policy allows returns within 14 days.',
  'lexical',
);
console.log(result.verdict);          // "rejected"
console.log(result.action);           // "block"
console.log(result.claims[0].reason); // "numerical_mismatch"

Deployed Agents — create, run, stream

import { AgentsClient } from 'wauldo';

const agents = new AgentsClient({
  baseUrl: 'https://api.wauldo.com',
  apiKey: 'YOUR_API_KEY',
  tenant: 'my-tenant',
});

const agent = await agents.create({
  name: 'support-bot',
  description: 'Answers refund questions',
  wauldoToml: `[agent]\nname = "support-bot"\n[model]\nprovider = "openrouter"\nname = "auto"`,
  preset: 'general_task', // or 'rust_backend_architect', 'rag_data_engineer', ...
});

const run = await agents.run(agent.id, 'Can I return a shirt 30 days after purchase?');

// Stream reasoning live as each workflow state completes
for await (const event of agents.streamTask(run.task_id)) {
  console.log(`  ${event.state_name}: ${event.duration_ms}ms  (${event.completion_tokens} tok)`);
}

// Or poll for the final verified result
const task = await agents.waitForTask(run.task_id, { timeoutMs: 120_000 });
console.log(task.result);                     // The answer
console.log(task.verification?.verdict);      // SAFE | UNVERIFIED | BLOCK | …
console.log(task.verification?.trust_score);  // 0.0 – 1.0
console.log(task.verification?.message);      // Human-readable context when non-SAFE

Chat (OpenAI-compatible)

const reply = await client.chatSimple('auto', 'Explain async/await in TypeScript');
console.log(reply);

Streaming

const stream = client.chatStream({
  model: 'auto',
  messages: [{ role: 'user', content: 'Hello!' }],
});
for await (const chunk of stream) {
  process.stdout.write(chunk);
}

Conversation

const conv = client.conversation({ system: 'You are an expert on TypeScript.', model: 'auto' });
const reply = await conv.say('What are generics?');
const followUp = await conv.say('Give me an example');

Features

• Pre-generation fact extraction — numbers, dates, limits injected as constraints
• 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 baseUrl, keep your existing code
• Zero dependencies — uses Node 18+ built-in APIs (fetch, ReadableStream)

Error Handling

import { HttpClient, ServerError } from 'wauldo';

try {
  const response = await client.chat({ model: 'auto', messages: [{ role: 'user', content: 'Hello' }] });
} catch (error) {
  if (error instanceof ServerError) {
    console.error(`Server error [${error.code}]: ${error.message}`);
  }
}

RapidAPI

const client = new HttpClient({
  baseUrl: '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

Website | Docs | Demo | Benchmarks

Contributing

PRs welcome. Check the good first issues.

License

MIT — see LICENSE