npm package: @sponge_theory/spt-neo-rag-client
Description: Complete JavaScript/TypeScript client with 100% API coverage for SPT Neo RAG - Advanced RAG platform with knowledge graphs, RAPTOR, BM25, and enterprise features
Author: SPT Neo RAG Team
Latest version: 1.0.0

# SPT Neo RAG JavaScript/TypeScript Client

A comprehensive JavaScript/TypeScript client library for the SPT Neo RAG API with **complete 100% API coverage**. This client provides a fully-typed, async/await-based interface for all Neo RAG features including document management, semantic search, knowledge graphs, RAPTOR, BM25, and enterprise administration.

## Status

**API Coverage:** ✅ 100% (165+ endpoints fully implemented)

**Version:** 1.0.0

## Complete Feature Set

### Core RAG Operations
- ✅ **Authentication & User Management**: Login, register, API keys, password management
- ✅ **Knowledge Bases**: Full CRUD with advanced configuration
- ✅ **Document Management**: Upload, process, scrape web pages, reprocess, content extraction
- ✅ **Query Execution**: Standard, streaming, multiple strategies, source retrieval
- ✅ **Task Monitoring**: Background job tracking and management

### Advanced Retrieval
- ✅ **Knowledge Graph**: Entity extraction, relationship querying, path finding, full graph traversal
- ✅ **RAPTOR Trees**: Hierarchical document clustering and retrieval
- ✅ **BM25 Index**: Hybrid search with keyword-based retrieval
- ✅ **Query Strategies**: Adaptive, conversational, hybrid, and more

### Enterprise Features
- ✅ **Teams**: Multi-user collaboration, member management, knowledge base sharing
- ✅ **API Keys**: Programmatic access management
- ✅ **User Management**: Full user lifecycle and permissions
- ✅ **Webhooks**: Event notifications and integrations
- ✅ **Structured Schemas**: Data extraction templates

### Model & Infrastructure
- ✅ **Model Management**: LLM and embedding model configuration
- ✅ **Admin Operations**: System metrics, maintenance, license management
- ✅ **Dashboard**: Analytics, metrics, usage statistics
- ✅ **System Settings**: Configuration management
- ✅ **Health Checks**: Component monitoring and diagnostics

## Features

- 🎯 **100% API Coverage**: All 165+ endpoints fully implemented and tested
- 🔐 **Multiple Authentication**: API keys, username/password, CSRF tokens
- 📄 **Complete Document Lifecycle**: Upload, process, scrape, reprocess, extract
- 🔍 **Advanced Search**: Vector similarity, BM25, hybrid, knowledge graph queries
- 🧠 **Knowledge Graphs**: Entity extraction, relationship mapping, path finding
- 🌳 **RAPTOR**: Hierarchical retrieval with tree-based clustering
- 👥 **Enterprise Ready**: Teams, permissions, webhooks, admin controls
- 📊 **Background Tasks**: Async processing with real-time monitoring
- 💬 **Streaming**: Real-time query response streaming
- 🎯 **Full TypeScript**: Complete type definitions for all models
- ⚡ **Modern API**: Promise-based async/await throughout
- 🌐 **Cross-platform**: Works in Node.js and browsers

## Installation

```bash
npm install @sponge_theory/spt-neo-rag-client
```

Or with yarn:

```bash
yarn add @sponge_theory/spt-neo-rag-client
```

## Quick Start

### With API Key

```typescript
import { NeoRagClient } from '@sponge_theory/spt-neo-rag-client';

const client = new NeoRagClient(
  'https://your-neorag-instance.com',
  'your-api-key'
);

// Query a knowledge base
const response = await client.query('What is RAG?', {
  knowledgeBaseId: 'kb-id-here',
  topK: 5,
});

console.log(response.result.answer);
```

### With Username/Password

```typescript
import { NeoRagClient } from '@sponge_theory/spt-neo-rag-client';

const client = new NeoRagClient('https://your-neorag-instance.com');

// Login
await client.login('user@example.com', 'password');

// Use the client
const kbs = await client.knowledgeBases.listKnowledgeBases();
console.log(kbs);

// Logout when done
await client.logout();
```

## Usage Examples

### Knowledge Base Management

```typescript
// Create a knowledge base
const kb = await client.knowledgeBases.createKnowledgeBase({
  name: 'My Knowledge Base',
  description: 'A collection of important documents',
  kb_type: 'default',
  config: {
    embedding_model: 'text-embedding-3-small',
    chunk_size: 1000,
    chunk_overlap: 200,
  },
});

// List knowledge bases
const kbs = await client.knowledgeBases.listKnowledgeBases(0, 10);

// Get a specific knowledge base
const kbDetail = await client.knowledgeBases.getKnowledgeBase(kb.id);

// Update knowledge base
const updated = await client.knowledgeBases.updateKnowledgeBase(kb.id, {
  description: 'Updated description',
});

// Delete knowledge base
await client.knowledgeBases.deleteKnowledgeBase(kb.id);
```

### Document Management

```typescript
// Upload a document (Browser)
const fileInput = document.getElementById('file') as HTMLInputElement;
const file = fileInput.files[0];

const doc = await client.documents.uploadDocument(
  file,
  'My Document',
  'kb-id-here',
  {
    description: 'Important research paper',
    source: 'https://example.com/paper.pdf',
    processorType: 'docling',
    metadata: {
      author: 'John Doe',
      year: 2024,
    },
  }
);

// Upload a document (Node.js)
import fs from 'fs';

const fileBuffer = fs.readFileSync('./document.pdf');
const blob = new Blob([fileBuffer], { type: 'application/pdf' });

const doc = await client.documents.uploadDocument(
  blob,
  'My Document',
  'kb-id-here'
);

// List documents
const docs = await client.documents.listDocuments('kb-id-here', 0, 10);

// Get document details
const docDetail = await client.documents.getDocument(doc.id);

// Get document chunks
const chunks = await client.documents.getDocumentChunks(doc.id, 0, 50);

// Get download URL
const downloadUrl = await client.documents.getDocumentDownloadUrl(doc.id);

// Update document
const updatedDoc = await client.documents.updateDocument(doc.id, {
  description: 'Updated description',
  doc_metadata: {
    reviewed: true,
  },
});

// Delete document
await client.documents.deleteDocument(doc.id);
```

### Querying

```typescript
// Basic query
const response = await client.query('What is machine learning?', {
  knowledgeBaseId: 'kb-id-here',
  topK: 5,
  similarityThreshold: 0.7,
});

console.log(response.result.answer);
console.log(response.result.sources);

// Advanced query with multiple knowledge bases
const multiKbResponse = await client.query('Explain neural networks', {
  knowledgeBaseIds: ['kb-id-1', 'kb-id-2'],
  queryStrategy: 'adaptive',
  enableBm25: true,
  bm25Weight: 0.3,
  model: 'claude-3-5-sonnet-20241022',
  provider: 'anthropic',
});

// Query specific documents
const docResponse = await client.query('Summarize the key points', {
  knowledgeBaseId: 'kb-id-here',
  documentsIds: ['doc-id-1', 'doc-id-2'],
  queryConfig: {
    temperature: 0.7,
    max_tokens: 500,
  },
});

// Using the queries endpoint directly
import { QueryRequest } from '@sponge_theory/spt-neo-rag-client';

const payload: QueryRequest = {
  query: 'What are the benefits of RAG?',
  knowledge_base_id: 'kb-id-here',
  top_k: 3,
  query_strategy: 'hybrid',
};

const result = await client.queries.query(payload);

// Get available query strategies
const strategies = await client.queries.getQueryStrategies();
console.log(strategies.strategies);

// Retrieve sources only (no answer generation)
const sources = await client.queries.retrieveSources(payload);
console.log(sources.sources);
```

### Streaming Queries

```typescript
// Stream query responses
const stream = client.streamQuery('Explain quantum computing', {
  knowledgeBaseId: 'kb-id-here',
  topK: 5,
});

for await (const chunk of stream) {
  if (chunk.type === 'text') {
    process.stdout.write(chunk.content);
  } else if (chunk.type === 'sources') {
    console.log('\nSources:', chunk.sources);
  }
}
```

### Task Monitoring

```typescript
// Upload a document and monitor the processing task
const doc = await client.documents.uploadDocument(
  file,
  'Large Document',
  'kb-id-here'
);

// The document object contains a task_id for background processing
if (doc.task_id) {
  let task = await client.tasks.getTask(doc.task_id);

  while (task.status === 'pending' || task.status === 'processing') {
    console.log(`Progress: ${task.progress}%`);
    await new Promise((resolve) => setTimeout(resolve, 2000));
    task = await client.tasks.getTask(doc.task_id);
  }

  if (task.status === 'completed') {
    console.log('Document processing completed!');
  } else {
    console.error('Document processing failed:', task.error);
  }
}
```

### Health Checks

```typescript
// Simple health check
const health = await client.health.healthCheck();
console.log(`Status: ${health.status}, Version: ${health.api_version}`);

// Detailed health check
const detailedHealth = await client.health.detailedHealthCheck();
console.log('Database:', detailedHealth.components.database.status);
console.log('Redis:', detailedHealth.components.redis.status);
console.log('Storage:', detailedHealth.components.storage.status);
```

### User Management

```typescript
// Register a new user
const user = await client.register(
  'newuser@example.com',
  'securepassword',
  'John Doe'
);

// Login
const token = await client.login('newuser@example.com', 'securepassword');

// Get current user info
const currentUser = await client.getCurrentUser();
console.log(currentUser);

// Change password
await client.changePassword('oldpassword', 'newpassword');

// Request password reset
await client.requestPasswordReset('user@example.com');
```

### Error Handling

```typescript
import {
  NeoRagApiError,
  AuthenticationError,
  ConfigurationError,
  NetworkError,
} from '@sponge_theory/spt-neo-rag-client';

try {
  const response = await client.query('Test query', {
    knowledgeBaseId: 'invalid-id',
  });
} catch (error) {
  if (error instanceof NeoRagApiError) {
    console.error(`API Error (${error.statusCode}):`, error.detail);
  } else if (error instanceof AuthenticationError) {
    console.error('Authentication failed:', error.message);
  } else if (error instanceof ConfigurationError) {
    console.error('Configuration error:', error.message);
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
    console.error('Original error:', error.originalError);
  } else {
    console.error('Unexpected error:', error);
  }
}
```

## Advanced Features

### LiteLLM API Key

For deployments using LiteLLM proxy:

```typescript
const client = new NeoRagClient('https://your-neorag-instance.com', 'api-key');

// Set LiteLLM API key
client.setLiteLLMApiKey('litellm-key-here');

// Now all queries will include the LiteLLM API key header
const response = await client.query('Test query', {
  knowledgeBaseId: 'kb-id-here',
});
```

### Custom Timeout

```typescript
// Set a custom timeout (in milliseconds)
const client = new NeoRagClient(
  'https://your-neorag-instance.com',
  'api-key',
  120000 // 2 minutes
);
```

## TypeScript Support

This library is written in TypeScript and provides complete type definitions:

```typescript
import {
  NeoRagClient,
  KnowledgeBaseResponse,
  DocumentResponse,
  QueryResponse,
  QueryRequest,
} from '@sponge_theory/spt-neo-rag-client';

const client = new NeoRagClient(baseUrl, apiKey);

// All responses are fully typed
const kb: KnowledgeBaseResponse = await client.knowledgeBases.createKnowledgeBase({
  name: 'Typed KB',
});

const query: QueryRequest = {
  query: 'Test',
  knowledge_base_id: kb.id,
  top_k: 5,
};

const result: QueryResponse = await client.queries.query(query);
```

## API Reference

### NeoRagClient

Main client class providing access to all API functionality.

#### Constructor

```typescript
new NeoRagClient(baseUrl: string, apiKey?: string, timeout?: number)
```

#### Properties

- `knowledgeBases`: Knowledge base operations
- `queries`: Query operations
- `documents`: Document operations
- `tasks`: Task monitoring
- `health`: Health check operations

#### Methods

- `login(username, password)`: Authenticate with credentials
- `logout()`: End the current session
- `setApiKey(apiKey)`: Set API key authentication
- `getCurrentUser()`: Get current user information
- `register(email, password, name)`: Register new user
- `changePassword(current, new)`: Change user password
- `requestPasswordReset(email)`: Request password reset
- `query(query, options)`: Execute a query (convenience method)
- `streamQuery(query, options)`: Stream query response
- `setLiteLLMApiKey(key)`: Set LiteLLM API key

### Endpoint Classes

Each endpoint class provides specialized methods for a specific domain:

- **KnowledgeBaseEndpoints**: Knowledge base CRUD operations
- **QueryEndpoints**: Query execution and strategy management
- **DocumentEndpoints**: Document upload, management, and retrieval
- **TaskEndpoints**: Background task monitoring
- **HealthEndpoints**: System health checks

## Documentation

- **[API Coverage Analysis](./API_COVERAGE.md)** - ✅ 100% Complete - All 165+ endpoints implemented
- **[Endpoint Verification Report](./ENDPOINT_VERIFICATION.md)** - Verification of correct API mapping
- **[Online Documentation](https://docs.neo-rag.com/clients/javascript-sdk/)** - Full SDK documentation with examples
- **[API Reference](https://docs.neo-rag.com/api/)** - Complete REST API documentation

## Contributing

Contributions are welcome! The SDK now has 100% API coverage.

**Ways to Contribute:**
- Add tests for new endpoints
- Improve documentation and examples
- Report bugs or suggest enhancements
- Add convenience methods
- Improve TypeScript types

**How to Contribute:**
1. Follow the existing patterns in `src/endpoints/`
2. Ensure TypeScript types are properly defined
3. Add tests for new functionality
4. Submit a PR to the main [SPT Neo RAG repository](https://github.com/sponge-theory/spt-neo-rag)

See the main repository for contribution guidelines.

## License

MIT License - see LICENSE file for details.

## Support

- Documentation: [https://docs.neo-rag.com](https://docs.neo-rag.com)
- Repository: [https://github.com/sponge-theory/spt-neo-rag](https://github.com/sponge-theory/spt-neo-rag)
- Issues: [https://github.com/sponge-theory/spt-neo-rag/issues](https://github.com/sponge-theory/spt-neo-rag/issues)
- Email: contact@sponge-theory.ai

## Version

Current version: 1.0.0 ✅ **100% API Coverage**

This client library provides complete parity with the SPT Neo RAG API and matches the Python SDK in functionality.