# `@kerdos/rag-client`

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

---

## Installation

```bash
# npm
npm install @kerdos/rag-client

# pnpm
pnpm add @kerdos/rag-client

# yarn
yarn add @kerdos/rag-client
```

---

## Quick Start

```typescript
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):

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

Or with Docker:

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

---

## Error Handling

```typescript
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](https://kerdos.in)_