@aliyun-rds/rag-agent-sdk 0.1.1

package/README.md

@@ -0,0 +1,253 @@
+# RAG Agent SDK for TypeScript/JavaScript
+
+A comprehensive TypeScript SDK for interacting with RAG Agent API services.
+
+## Installation
+
+```bash
+npm install @rag-agent/sdk
+# or
+yarn add @rag-agent/sdk
+# or
+pnpm add @rag-agent/sdk
+```
+
+## Quick Start
+
+```typescript
+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
+
+```typescript
+const client = new RagAgentClient({
+  baseUrl: 'http://localhost:9621',
+  apiKey: 'your-api-key',
+});
+```
+
+### JWT Token Authentication
+
+```typescript
+const client = new RagAgentClient({
+  baseUrl: 'http://localhost:9621',
+  jwtToken: 'your-jwt-token',
+});
+```
+
+### Supabase Authentication
+
+```typescript
+const client = new RagAgentClient({
+  baseUrl: 'http://localhost:9621',
+  supabaseUrl: 'https://xxx.supabase.co',
+  supabaseAnonKey: 'your-anon-key',
+  supabaseAccessToken: 'user-access-token',
+});
+```
+
+### Username/Password Authentication
+
+```typescript
+const client = new RagAgentClient({
+  baseUrl: 'http://localhost:9621',
+  username: 'admin',
+  password: 'password',
+});
+```
+
+## Features
+
+### Dataset Management
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+```typescript
+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.
+
+```typescript
+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