npm package: @neureus/sdk
Description: Neureus Platform SDK - AI-native, edge-first application platform
Author: Neureus
Latest version: 0.2.1

# @neureus/sdk

Official TypeScript/JavaScript SDK for the Neureus AI Platform

[![npm version](https://badge.fury.io/js/@neureus%2Fsdk.svg)](https://www.npmjs.com/package/@neureus/sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Overview

The Neureus SDK provides a unified interface to interact with the Neureus AI Platform's services:

- **AI Gateway**: Multi-provider LLM routing with automatic fallback
- **Vector Database**: Lightning-fast vector search powered by HNSW
- **RAG Pipeline**: Complete document Q&A with retrieval-augmented generation

## Installation

```bash
npm install @neureus/sdk
# or
pnpm add @neureus/sdk
# or
yarn add @neureus/sdk
```

## Quick Start

### Unified Client

```typescript
import { NeureusClient } from '@neureus/sdk';

const neureus = new NeureusClient({
  apiKey: process.env.NEUREUS_API_KEY
});

// AI Gateway - Chat with any LLM
const response = await neureus.ai.chat.create([
  { role: 'user', content: 'What is Neureus?' }
]);

// Vector Database - Semantic search
const results = await neureus.vector.search({
  vector: embedding,
  topK: 5,
  minSimilarity: 0.7
});

// RAG Pipeline - Document Q&A
const answer = await neureus.rag.query('knowledge-base', {
  query: 'How do I deploy my application?'
});
```

### Individual Clients

You can also import and use each client independently:

```typescript
import { AIClient, VectorClient, RAGClient } from '@neureus/sdk';

const ai = new AIClient({ apiKey: process.env.NEUREUS_API_KEY });
const vector = new VectorClient({ apiKey: process.env.NEUREUS_API_KEY });
const rag = new RAGClient({ apiKey: process.env.NEUREUS_API_KEY });
```

## AI Gateway

### Chat Completions

```typescript
import { AIClient } from '@neureus/sdk/ai';

const ai = new AIClient({
  apiKey: process.env.NEUREUS_API_KEY
});

// Non-streaming
const response = await ai.chat.create([
  { role: 'system', content: 'You are a helpful assistant.' },
  { role: 'user', content: 'Explain quantum computing simply.' }
], {
  model: 'gpt-4',
  temperature: 0.7,
  maxTokens: 500
});

console.log(response.choices[0].message.content);
console.log(`Tokens used: ${response.usage.totalTokens}`);
console.log(`Cost: $${response.cost?.total.toFixed(4)}`);
```

### Streaming Completions

```typescript
// Streaming
const stream = await ai.chat.stream([
  { role: 'user', content: 'Write a short story about AI.' }
], {
  model: 'gpt-4'
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content;
  if (content) {
    process.stdout.write(content);
  }
}
```

### Multi-Provider Support

```typescript
// Automatic fallback across providers
const response = await ai.chat.create(messages, {
  model: 'gpt-4',
  fallback: ['claude-3-sonnet', 'gemini-pro']
});

// OpenAI, Anthropic, Google, Cloudflare, and AWS Bedrock supported
```

### Caching & Cost Optimization

```typescript
// Automatic caching for identical requests
const response = await ai.chat.create(messages, {
  cache: true  // Default: true
});

if (response.cached) {
  console.log(`Cache hit! Saved ${response.cost?.total.toFixed(4)} USD`);
}
```

## Vector Database

### Index Management

```typescript
import { VectorClient } from '@neureus/sdk/vector';

const vectors = new VectorClient({
  apiKey: process.env.NEUREUS_API_KEY
});

// Create an index
await vectors.indices.create({
  name: 'product-docs',
  dimension: 1536,  // OpenAI ada-002
  metric: 'cosine',
  indexType: 'hnsw'
});

// List all indices
const { indices } = await vectors.indices.list();
```

### Vector Operations

```typescript
// Upsert vectors
await vectors.upsert({
  vectors: [
    {
      id: 'doc-1',
      vector: embedding,  // [0.1, 0.2, ..., 0.5]
      metadata: {
        title: 'Getting Started',
        section: 'installation',
        page: 1
      }
    }
  ],
  indexName: 'product-docs'
});

// Get a vector by ID
const vector = await vectors.get('doc-1');
```

### Similarity Search

```typescript
// Vector search
const results = await vectors.search({
  vector: queryEmbedding,
  topK: 10,
  minSimilarity: 0.7,
  filter: {
    section: 'installation'
  },
  includeMetadata: true
});

for (const result of results.matches) {
  console.log(`${result.id}: ${result.score} - ${result.metadata.title}`);
}
```

### Hybrid Search

```typescript
// Combine vector and keyword search
const results = await vectors.hybridSearch({
  vector: queryEmbedding,
  query: 'installation guide',
  topK: 10,
  alpha: 0.7  // 70% vector, 30% keyword
});
```

## RAG Pipeline

### Create a Pipeline

```typescript
import { RAGClient } from '@neureus/sdk/rag';

const rag = new RAGClient({
  apiKey: process.env.NEUREUS_API_KEY
});

// Create a RAG pipeline
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,
    maxTokens: 1000
  }
});
```

### Ingest Documents

```typescript
// From files
await rag.ingest('customer-support', {
  source: './docs',
  type: 'file',
  format: 'markdown',
  recursive: true
});

// From URL
await rag.ingest('customer-support', {
  source: 'https://example.com/docs',
  type: 'url',
  format: 'html'
});

// From text
await rag.ingest('customer-support', {
  source: 'This is my document content...',
  type: 'text',
  metadata: { title: 'Product Guide' }
});
```

### Query with RAG

```typescript
// Non-streaming query
const response = await rag.query('customer-support', {
  query: 'How do I reset my password?',
  topK: 5,
  minSimilarity: 0.7,
  includeSource: true
});

console.log('Answer:', response.answer);
console.log('Sources:', response.sources);
console.log('Performance:', response.performance);
```

### Streaming RAG Responses

```typescript
// Streaming query
const stream = await rag.queryStream('customer-support', {
  query: 'Explain the authentication flow'
});

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

## Configuration

### Client Options

```typescript
const neureus = new NeureusClient({
  apiKey: 'nru_...',
  baseUrl: 'https://api.neureus.ai',  // Optional, default shown
  timeout: 60000,  // ms, default: 60000
  retries: 3,      // default: 3
  userId: 'user-123',  // Optional, for usage tracking
  teamId: 'team-456',  // Optional, for usage tracking
  defaultVectorIndex: 'default',  // Optional
  defaultVectorNamespace: ''      // Optional
});
```

## Error Handling

```typescript
import {
  AIGatewayError,
  RateLimitError,
  VectorDBError,
  RAGError
} from '@neureus/sdk';

try {
  const response = await ai.chat.create(messages);
} catch (error) {
  if (error instanceof RateLimitError) {
    console.error('Rate limited, retry after:', error.metadata.retryAfter);
  } else if (error instanceof AIGatewayError) {
    console.error('AI Gateway error:', error.code, error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}
```

## TypeScript Support

The SDK is written in TypeScript and includes full type definitions:

```typescript
import type {
  ChatMessage,
  ChatCompletionResponse,
  VectorEntry,
  VectorSearchResponse,
  QueryResponse,
  RAGConfig
} from '@neureus/sdk';
```

## Advanced Usage

### Custom HTTP Client

```typescript
// The SDK uses `ky` internally for HTTP requests
// All clients accept standard ky configuration options
```

### Batch Operations

```typescript
// Batch vector upserts
await vectors.upsert({
  vectors: [...Array(1000)].map((_, i) => ({
    id: `doc-${i}`,
    vector: generateEmbedding(),
    metadata: { index: i }
  }))
});
```

### Concurrent Requests

```typescript
// Parallel AI requests
const [response1, response2, response3] = await Promise.all([
  ai.chat.create(messages1),
  ai.chat.create(messages2),
  ai.chat.create(messages3)
]);
```

## Examples

Check out the `/examples` directory for complete working examples:

- Chat application with streaming
- Document Q&A with RAG
- Semantic search
- Multi-provider fallback
- Cost optimization strategies

## API Reference

Full API documentation available at: https://docs.neureus.ai/sdk

## Support

- Documentation: https://docs.neureus.ai
- GitHub Issues: https://github.com/Neureus/Neureus/issues
- Discord Community: https://discord.gg/neureus
- Email: support@neureus.ai

## License

MIT © Neureus

---

**Note**: Requires an API key from https://app.neureus.ai