TypeScript

Installation

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

npm install @larkup/sdk

yarn add @larkup/sdk

pnpm add @larkup/sdk

Initialization

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

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

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.

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

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:

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:

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.

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.

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.

Corpus Inspection and Export

const summary = await client.corpusSummary();

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

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

Media

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.

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:

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:

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 and LangChain Integration guides.

Overview

Official

Integrations

Installation

Initialization

Basic Usage

Adding a Document

Bulk Indexing with Progress

Querying

Streaming Chat

Agent Server

Choose a chat model

Corpus Inspection and Export

Media

Marketplace Hub

API Coverage

Local Demo

Integrations

​Installation

​Initialization

​Basic Usage

​Adding a Document

​Bulk Indexing with Progress

​Querying

​Streaming Chat

​Agent Server

​Choose a chat model

​Corpus Inspection and Export

​Media

​Marketplace Hub

​API Coverage

​Local Demo

​Integrations

Installation

Initialization

Basic Usage

Adding a Document

Bulk Indexing with Progress

Querying

Streaming Chat

Agent Server

Choose a chat model

Corpus Inspection and Export

Media

Marketplace Hub

API Coverage

Local Demo

Integrations