sdk/typescript/README.md

@kerdos/rag-client

TypeScript/JavaScript client for the Kerdos RAG REST API. Zero runtime dependencies — works in Node.js ≥ 18 and modern browsers.

---

Installation

# npm
npm install @kerdos/rag-client

# pnpm
pnpm add @kerdos/rag-client

# yarn
yarn add @kerdos/rag-client

---

Quick Start

import { KerdosRAGClient } from "@kerdos/rag-client";

const client = new KerdosRAGClient({
  baseUrl: "http://localhost:8000",
  apiKey: "your-secret", // optional — only if server has API_KEY set
});

// 1. Index documents
const result = await client.indexFiles([
  new File([pdfBuffer], "policy.pdf"),
  new File([txtContent], "manual.txt"),
]);
console.log("Indexed:", result.indexed);
console.log("Skipped:", result.skipped);

// 2. Stream an answer
let answer = "";
for await (const token of client.chat("What is the refund policy?")) {
  answer = token; // each yield is the full cumulative answer
  process.stdout.write("\r" + answer);
}

// 3. Multi-turn conversation
const history = [
  { role: "user", content: "What is the refund policy?" },
  { role: "assistant", content: answer },
];
for await (const token of client.chat("Who do I contact for refunds?", {
  history,
})) {
  process.stdout.write("\r" + token);
}

// 4. Status & reset
const status = await client.status();
console.log("Chunks:", status.chunk_count);

await client.reset();

---

API Reference

new KerdosRAGClient(options)

Option	Type	Default	Description
baseUrl	string	—	Server URL (e.g. http://localhost:8000)
apiKey	string	undefined	Sent as X-Api-Key header
timeoutMs	number	30000	Request timeout in ms

Methods

Method	Returns	Description
health()	Promise<HealthResponse>	Liveness probe
status()	Promise<StatusResponse>	KB metadata
indexFiles(files)	Promise<IndexResult>	Upload & index files
chat(query, opts?)	AsyncGenerator<string>	Stream answer tokens
reset()	Promise<{ok, message}>	Clear knowledge base

---

Server Setup

Start the REST server (Python backend required):

pip install kerdos-rag
kerdos-rag api --port 8000

Or with Docker:

docker build --build-arg MODE=api -t kerdos-rag .
docker run -p 8000:8000 -e HF_TOKEN=hf_... kerdos-rag

---

Error Handling

import { KerdosAPIError } from "@kerdos/rag-client";

try {
  for await (const token of client.chat("...")) { ... }
} catch (err) {
  if (err instanceof KerdosAPIError) {
    console.error(`API ${err.statusCode}:`, err.message);
  }
}

---

© 2024–2026 Kerdos Infrasoft Private Limited | kerdos.in