@neureus/sdk
Version:
Neureus Platform SDK - AI-native, edge-first application platform
311 lines (307 loc) • 8.5 kB
TypeScript
import { RAGConfig, RAGPipelineInfo, IngestionRequest, ProcessingResult, BatchProcessingResult, QueryRequest, QueryResponse, QueryStreamChunk } from '@neureus/rag';
export { BatchProcessingResult, Chunk, ChunkMetadata, ChunkingConfig, ChunkingStrategy, ContextResult, Document, DocumentFormat, DocumentMetadata, DocumentProcessingError, DocumentSource, EmbeddingConfig, EmbeddingError, GenerationError, IngestionRequest, ProcessingResult, QueryRequest, QueryResponse, QueryStreamChunk, RAGConfig, RAGError, RAGPipelineInfo, RAGPipelineStatus, RetrievalError } from '@neureus/rag';
/**
* Neureus RAG (Retrieval-Augmented Generation) SDK Client
*
* Provides a simple interface to build and query RAG pipelines on the
* Neureus platform, handling document ingestion, chunking, embedding,
* retrieval, and answer generation automatically.
*
* @example
* ```typescript
* import { RAGClient } from '@neureus/sdk/rag';
*
* const rag = new RAGClient({
* apiKey: 'nru_...',
* baseUrl: 'https://api.neureus.ai'
* });
*
* // Create a RAG pipeline
* await rag.pipelines.create({
* name: 'product-docs',
* embedding: {
* model: 'text-embedding-ada-002',
* provider: 'openai'
* },
* generation: {
* model: 'gpt-4',
* provider: 'openai'
* }
* });
*
* // Ingest documents
* await rag.ingest('product-docs', {
* source: './docs',
* type: 'file',
* format: 'markdown',
* recursive: true
* });
*
* // Query the pipeline
* const response = await rag.query('product-docs', {
* query: 'How do I authenticate users?',
* topK: 5
* });
*
* console.log(response.answer);
* console.log(response.sources);
* ```
*/
/**
* Configuration options for RAGClient
*/
interface RAGClientConfig {
/**
* Neureus API key (required)
* Get your API key from https://app.neureus.ai/settings/api-keys
*/
apiKey: string;
/**
* Base URL for the Neureus API
* @default 'https://api.neureus.ai'
*/
baseUrl?: string;
/**
* Request timeout in milliseconds
* @default 60000 (60 seconds)
*/
timeout?: number;
/**
* Number of retry attempts for failed requests
* @default 3
*/
retries?: number;
/**
* User ID for usage tracking (optional)
* @default ''
*/
userId?: string;
/**
* Team ID for usage tracking (optional)
* @default ''
*/
teamId?: string;
}
/**
* Options for document ingestion
*/
interface IngestOptions extends IngestionRequest {
/**
* Wait for ingestion to complete before returning
* @default false
*/
waitForCompletion?: boolean;
}
/**
* Options for RAG queries
*/
interface QueryOptions extends Omit<QueryRequest, 'streaming'> {
/**
* Enable streaming responses
* @default false
*/
streaming?: boolean;
}
/**
* Main RAG client class
*/
declare class RAGClient {
private http;
private config;
constructor(config: RAGClientConfig);
/**
* Pipeline management API
*/
pipelines: {
/**
* Create a new RAG pipeline
*
* @example
* ```typescript
* await rag.pipelines.create({
* name: 'customer-support',
* description: 'Customer support knowledge base',
* embedding: {
* model: 'text-embedding-ada-002',
* provider: 'openai',
* dimensions: 1536
* },
* chunking: {
* strategy: 'recursive',
* size: 512,
* overlap: 128
* },
* generation: {
* model: 'gpt-4',
* provider: 'openai',
* temperature: 0.1
* }
* });
* ```
*/
create: (config: RAGConfig) => Promise<{
success: boolean;
pipeline: RAGPipelineInfo;
}>;
/**
* List all RAG pipelines
*
* @example
* ```typescript
* const pipelines = await rag.pipelines.list();
* console.log(pipelines); // [{ name: 'docs', status: 'ready', ... }]
* ```
*/
list: () => Promise<{
pipelines: RAGPipelineInfo[];
count: number;
}>;
/**
* Get pipeline information
*
* @example
* ```typescript
* const info = await rag.pipelines.get('product-docs');
* console.log(info.stats.documentsCount, info.stats.totalQueries);
* ```
*/
get: (pipelineName: string) => Promise<RAGPipelineInfo>;
/**
* Update pipeline configuration
*
* @example
* ```typescript
* await rag.pipelines.update('product-docs', {
* generation: {
* temperature: 0.5
* }
* });
* ```
*/
update: (pipelineName: string, updates: Partial<RAGConfig>) => Promise<{
success: boolean;
pipeline: RAGPipelineInfo;
}>;
/**
* Delete a pipeline
*
* @example
* ```typescript
* await rag.pipelines.delete('old-docs');
* ```
*/
delete: (pipelineName: string) => Promise<{
success: boolean;
message: string;
}>;
};
/**
* Ingest documents into a RAG pipeline
*
* @example
* ```typescript
* // Ingest from file
* await rag.ingest('product-docs', {
* source: './docs',
* type: 'file',
* format: 'markdown',
* recursive: true
* });
*
* // Ingest from URL
* await rag.ingest('product-docs', {
* source: 'https://example.com/docs',
* type: 'url',
* format: 'html'
* });
*
* // Ingest text directly
* await rag.ingest('product-docs', {
* source: 'This is my document content...',
* type: 'text',
* metadata: { title: 'Introduction' }
* });
* ```
*/
ingest(pipelineName: string, options: IngestOptions): Promise<ProcessingResult | BatchProcessingResult>;
/**
* Query a RAG pipeline (non-streaming)
*
* @example
* ```typescript
* const response = await rag.query('product-docs', {
* query: 'How do I authenticate users?',
* topK: 5,
* minSimilarity: 0.7,
* includeSource: true
* });
*
* console.log('Answer:', response.answer);
* console.log('Sources:', response.sources);
* console.log('Performance:', response.performance);
* ```
*/
query(pipelineName: string, options: QueryOptions): Promise<QueryResponse>;
/**
* Query a RAG pipeline with streaming response
*
* @example
* ```typescript
* const stream = await rag.queryStream('product-docs', {
* query: 'Explain the authentication flow',
* topK: 5
* });
*
* for await (const chunk of stream) {
* if (chunk.type === 'answer') {
* process.stdout.write(chunk.data.content);
* } else if (chunk.type === 'complete') {
* console.log('\nSources:', chunk.data.sources);
* }
* }
* ```
*/
queryStream(pipelineName: string, options: QueryOptions): Promise<AsyncIterable<QueryStreamChunk>>;
/**
* Get pipeline statistics
*
* @example
* ```typescript
* const stats = await rag.stats('product-docs');
* console.log(`Documents: ${stats.documentsCount}`);
* console.log(`Queries: ${stats.totalQueries}`);
* console.log(`Avg response time: ${stats.avgResponseTime}ms`);
* ```
*/
stats(pipelineName: string): Promise<RAGPipelineInfo['stats']>;
/**
* Clear all documents from a pipeline
*
* @example
* ```typescript
* await rag.clear('product-docs');
* ```
*/
clear(pipelineName: string): Promise<{
success: boolean;
message: string;
}>;
/**
* Parse Server-Sent Events stream into async iterable
*/
private parseSSEStream;
}
/**
* Create a RAG client instance
*
* @example
* ```typescript
* import { createRAGClient } from '@neureus/sdk/rag';
*
* const rag = createRAGClient({
* apiKey: process.env.NEUREUS_API_KEY
* });
* ```
*/
declare function createRAGClient(config: RAGClientConfig): RAGClient;
export { type IngestOptions, type QueryOptions, RAGClient, type RAGClientConfig, createRAGClient };