RAG Agent SDK for TypeScript/JavaScript

A comprehensive TypeScript SDK for interacting with RAG Agent API services.

Installation

npm install @rag-agent/sdk
# or
yarn add @rag-agent/sdk
# or
pnpm add @rag-agent/sdk

Quick Start

import { RagAgentClient } from '@rag-agent/sdk';

const client = new RagAgentClient({
  baseUrl: 'http://localhost:9621',
  apiKey: 'your-api-key',
});

// Create a dataset
const dataset = await client.datasets.create({
  name: 'my-knowledge-base',
  description: 'My first knowledge base',
});
console.log(`Created dataset: ${dataset.dataset_uuid}`);

// Upload a document
const file = new File(['document content'], 'doc.txt', { type: 'text/plain' });
const result = await client.documents.upload(dataset.dataset_uuid, file);
console.log(`Upload status: ${result.status}`);

// Query the dataset
const response = await client.query.query(
  dataset.dataset_uuid,
  'What is this document about?',
  { mode: 'mix' }
);
console.log(`Answer: ${response.response}`);

Authentication

The SDK supports multiple authentication methods:

API Key Authentication

const client = new RagAgentClient({
  baseUrl: 'http://localhost:9621',
  apiKey: 'your-api-key',
});

JWT Token Authentication

const client = new RagAgentClient({
  baseUrl: 'http://localhost:9621',
  jwtToken: 'your-jwt-token',
});

Supabase Authentication

const client = new RagAgentClient({
  baseUrl: 'http://localhost:9621',
  supabaseUrl: 'https://xxx.supabase.co',
  supabaseAnonKey: 'your-anon-key',
  supabaseAccessToken: 'user-access-token',
});

Username/Password Authentication

const client = new RagAgentClient({
  baseUrl: 'http://localhost:9621',
  username: 'admin',
  password: 'password',
});

Features

Dataset Management

// List datasets
const datasets = await client.datasets.list({ page: 1, pageSize: 20 });

// Get dataset by ID
const dataset = await client.datasets.get('dataset-uuid');

// Update dataset
const updated = await client.datasets.update('dataset-uuid', {
  description: 'Updated description',
});

// Delete dataset
await client.datasets.delete('dataset-uuid');

Document Processing

// Upload file
const result = await client.documents.upload(datasetId, file);

// Insert text
const result = await client.documents.insertText(
  datasetId,
  'Your text content here',
  'manual-input'
);

// Batch insert
const result = await client.documents.insertBatch(
  datasetId,
  ['Text 1', 'Text 2', 'Text 3'],
  ['source1', 'source2', 'source3']
);

// List documents
const docs = await client.documents.list(datasetId);

// Delete document
await client.documents.delete(datasetId, docId);

RAG Queries

// Basic query
const response = await client.query.query(
  datasetId,
  'What is the main topic?',
  { mode: 'mix', topK: 10 }
);

// Streaming query
for await (const chunk of client.query.queryStream(
  datasetId,
  'Explain the concept in detail'
)) {
  process.stdout.write(chunk);
}

// Cross-dataset query
const response = await client.query.crossDatasetQuery(
  'Compare the topics',
  ['uuid1', 'uuid2'],
  { enableRerank: true }
);

// Get context only (without LLM response)
const context = await client.query.getContext(
  datasetId,
  'Find relevant information'
);
console.log(`Entities: ${context.entities?.length}`);
console.log(`Chunks: ${context.chunks?.length}`);

Knowledge Graph

// Get knowledge graph
const graph = await client.graph.getKnowledgeGraph(
  datasetId,
  'Person',
  { maxDepth: 2, maxNodes: 100 }
);

// Get all labels
const labels = await client.graph.getLabels(datasetId);

// Check entity exists
const exists = await client.graph.checkEntityExists(datasetId, 'John Doe');

// Edit entity
await client.graph.editEntity(
  datasetId,
  'John Doe',
  { description: 'Updated description' },
  false // allowRename
);

Error Handling

import {
  RagAgentError,
  AuthenticationError,
  AuthorizationError,
  DatasetNotFoundError,
  ValidationError,
} from '@rag-agent/sdk';

try {
  const dataset = await client.datasets.get('non-existent-id');
} catch (error) {
  if (error instanceof DatasetNotFoundError) {
    console.log(`Dataset not found: ${error.datasetId}`);
  } else if (error instanceof AuthenticationError) {
    console.log('Authentication failed - check your credentials');
  } else if (error instanceof AuthorizationError) {
    console.log('Permission denied');
  } else if (error instanceof RagAgentError) {
    console.log(`API error: ${error.message} (status: ${error.statusCode})`);
  }
}

Configuration Options

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | baseUrl | string | required | RAG Agent server URL | | apiKey | string | - | API key for authentication | | jwtToken | string | - | JWT token for authentication | | timeout | number | 30000 | Request timeout in milliseconds | | maxRetries | number | 3 | Maximum retry attempts | | retryDelay | number | 1000 | Initial delay between retries (ms) |

TypeScript Support

This SDK is written in TypeScript and provides full type definitions out of the box.

import type {
  Dataset,
  Document,
  QueryResponse,
  QueryMode,
  Entity,
  Relation,
} from '@rag-agent/sdk';

Browser Support

This SDK works in modern browsers and Node.js environments. It uses the native fetch API.

License

MIT License