> ## Documentation Index
> Fetch the complete documentation index at: https://larkup.de/documentation/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript

> How to install and use the Larkup TypeScript SDK.

## Installation

The SDK is available on npm. You can install it using your preferred package manager:

<CodeGroup>
  ```bash npm theme={null}
  npm install @larkup/sdk
  ```

  ```bash yarn theme={null}
  yarn add @larkup/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @larkup/sdk
  ```
</CodeGroup>

## Initialization

Import and initialize the client. It automatically picks up the `LARKUP_API_URL` and `LARKUP_API_KEY` from your environment.

```typescript theme={null}
import { LarkupClient } from '@larkup/sdk';

const client = new LarkupClient({
  baseUrl: process.env.LARKUP_API_URL,
  apiKey: process.env.LARKUP_API_KEY,
});
```

The base URL defaults to `http://localhost:8080`. When constructor values are omitted, the client reads `LARKUP_API_URL` and `LARKUP_API_KEY`.

## Basic Usage

### Adding a Document

```typescript theme={null}
const response = await client.addDocument({
  id: 'doc-1',
  text: 'Larkup is a flexible, high performance RAG pipeline.',
  title: 'Introduction',
});

console.log('Document added:', response.success);
```

`addDocument()` embeds and stores the document immediately. No second index call is required.

### Bulk Indexing with Progress

`indexDocuments()` accepts sequential and parallel scheduling. It yields a progress event after every server response and a final completion event.

```typescript theme={null}
const documents = [
  { title: 'Guide', text: 'Deployment guide content' },
  { title: 'FAQ', text: 'Frequently asked questions' },
];

for await (const progress of client.indexDocuments(documents, {
  mode: 'parallel',
  concurrency: 4,
  continueOnError: true,
})) {
  console.log(progress.percent, progress.succeeded, progress.failed);
}
```

Use `mode: "sequential"` when request order matters or the embedding provider has a strict rate limit. Parallel mode only controls client request scheduling. The server's semantic, hybrid, vector store, embedding, and chunking configuration remains authoritative.

### Querying

```typescript theme={null}
const results = await client.query('What is Larkup?', 5);

for (const hit of results.hits) {
  console.log(`Score: ${hit.score} | Text: ${hit.text}`);
}
```

### Streaming Chat

Use `chat()` when you want to render tokens as they arrive:

```typescript theme={null}
for await (const event of client.chat({
  messages: [{ role: 'user', content: 'Summarize the deployment guide.' }],
  topK: 4,
})) {
  if (event.type === 'text-delta') {
    process.stdout.write(event.text ?? '');
  }
}
```

Use `chatText()` when you only need the completed answer:

```typescript theme={null}
const answer = await client.chatText('What does the API key protect?');
```

### Agent Server

Use `LarkupAgentClient` when the Larkup Server toggle is set to **Agent**. It exposes the
Agent's loaded tools and consumes its AI SDK UI-message stream.

```typescript theme={null}
import { LarkupAgentClient } from '@larkup/sdk';

const agent = new LarkupAgentClient({
  baseUrl: 'http://localhost:8080',
  apiKey: process.env.LARKUP_API_KEY,
});
for (const capability of await agent.capabilities()) {
  console.log(capability.name, capability.tools);
}
console.log((await agent.configuration()).systemPrompt);
console.log(await agent.sandbox());
for await (const text of agent.streamText('What can you do?')) {
  process.stdout.write(text);
}
```

Use `capabilities()` to inspect grouped integrations—selected built-ins, skills, sandbox, one entry per MCP connection, and plugins. A capability marked `configured` is selected in the Project but is not executable by this runtime; `active` entries are loaded. `tools()` remains available when you need the raw tool list. `configuration()` returns the UI prompt, selected tools, skills, and sandbox configuration; `sandbox()` checks readiness without exposing credentials. Use `chatText()` when you only need the completed answer. Use `chat()` to access the raw AI SDK stream.

### Choose a chat model

Every generated runtime exposes `GET /models`. Use the SDK to inspect the
providers and models that the runtime can actually use, then send `modelId` on
an individual chat request. This does not change the deployment default.

```typescript theme={null}
const catalog = await agent.chatModelCatalog();
console.table(await agent.chatProviders());

const model = (await agent.chatModels('anthropic')).at(0);
if (model) {
  const answer = await agent.chatText({
    messages: [{ role: 'user', content: 'Summarize the project.' }],
    // Optional. Omit it to use catalog.configuredProvider.
    provider: catalog.configuredProvider,
    modelId: model.id,
  });
  console.log(answer);
}
```

An AI Gateway runtime can select any language model returned by its catalog.
A runtime configured with a direct provider accepts only that provider's model
IDs, so its configured API key is never used with another vendor. Browse the
current catalog and provider capabilities in the [Vercel AI Gateway model catalog](https://vercel.com/ai-gateway/models).

### Corpus Inspection and Export

```typescript theme={null}
const summary = await client.corpusSummary();

const corpus = await client.corpus({
  filter: { titleContains: 'deployment' },
  limit: 50,
  includeContent: true,
});

const jsonl = await client.exportCorpus('jsonl');
```

### Media

```typescript theme={null}
const mediaList = await client.listMedia();
const media = await client.getMedia('media-1');
const jobStatus = await client.getMediaJobStatus('job-1');
await client.deleteMedia('media-1');
```

### Marketplace Hub

Tool discovery uses a separate Hub client because Marketplace installation is a local CLI control operation.

```typescript theme={null}
import { LarkupHubClient } from '@larkup/sdk';

const hub = new LarkupHubClient();
const tools = await hub.listTools({ category: 'media', search: 'video' });
const tool = await hub.getTool('video-audio');
```

Install a discovered tool on the Larkup host:

```bash theme={null}
larkup marketplace install video-audio
```

## API Coverage

| SDK method                                                            | RAG server operation                                   |
| --------------------------------------------------------------------- | ------------------------------------------------------ |
| `health()`                                                            | `GET /health`                                          |
| `openApi()`                                                           | `GET /openapi.json`                                    |
| `query()`                                                             | `POST /query`                                          |
| `chat()` / `chatText()`                                               | `POST /chat`                                           |
| `listDocuments()` / `getDocument()`                                   | `GET /documents`                                       |
| `addDocument()` / `indexDocuments()`                                  | `POST /documents`                                      |
| `updateDocument()` / `deleteDocument()`                               | `PUT` / `DELETE /documents/:id`                        |
| `scrape()`                                                            | `POST /scrape`                                         |
| `corpusSummary()` / `corpus()`                                        | `GET /corpus/summary`, `POST /corpus`                  |
| `exportCorpus()`                                                      | `POST /corpus/export`                                  |
| `listMedia()` / `getMedia()` / `deleteMedia()`                        | `GET /media`, `GET /media/:id`, `DELETE /media/:id`    |
| `getMediaJobStatus()` / `approveRefinement()` / `declineRefinement()` | `GET /media/jobs/:id`, `POST /media/jobs/:id/approval` |
| `LarkupAgentClient.tools()`                                           | `GET /agent/tools`                                     |
| `LarkupAgentClient.capabilities()`                                    | `GET /agent/capabilities`                              |
| `LarkupAgentClient.configuration()`                                   | `GET /agent/configuration` (admin)                     |
| `LarkupAgentClient.sandbox()`                                         | `GET /agent/sandbox` (admin)                           |
| `LarkupAgentClient.chat()` / `streamText()` / `chatText()`            | `POST /chat` (Agent profile)                           |

## Local Demo

The repository includes a complete demo configured for `http://localhost:8080`:

```bash theme={null}
pnpm --filter @larkup/sdk build
pnpm --filter @larkup/sdk exec tsx examples/rag-server.ts
```

## Integrations

For connecting to the Vercel AI SDK or LangChain.js, see the dedicated [Vercel AI SDK Integration](/documentation/documentation/sdk/integrations/ai-sdk) and [LangChain Integration](/documentation/documentation/sdk/integrations/langchain) guides.