onairos/SDK-README.md

The Onairos Library is a collection of functions that enable Applications to connect and communicate data with Onairos Identities via User Authorization. Integration for developers is seamless, simple and effective for all applications. LLM SDK capabiliti

# Onairos SDK

A unified SDK that wraps OpenAI, Anthropic Claude, and Google Gemini APIs with built-in RAG (Retrieval-Augmented Generation) capabilities for personalized AI interactions.

## 🚀 Features

- **Unified API**: Single interface for OpenAI, Anthropic, and Google Gemini
- **RAG Enhancement**: Automatic memory storage and retrieval for personalized responses
- **Drop-in Replacement**: Minimal code changes from existing OpenAI implementations
- **Session Management**: JWT-based user authentication and isolation
- **Privacy-Focused**: Stores selected memory data, not raw conversations
- **Multi-Provider Support**: Seamlessly switch between different LLM providers
- **Memory Management**: Built-in vector storage with Pinecone integration

## 📦 Installation

```bash
npm install onairos
```

## 🔧 Setup

### Environment Variables

Create a `.env` file with your API keys:

```env
OPENAI_API_KEY=your-openai-api-key
ANTHROPIC_API_KEY=your-anthropic-api-key
GOOGLE_API_KEY=your-google-api-key
PINECONE_API_KEY=your-pinecone-api-key
PINECONE_ENVIRONMENT=your-pinecone-environment
JWT_SECRET=your-super-secret-jwt-key
```

### Basic Setup

```javascript
import { OnairosClient } from 'onairos';

const onairos = new OnairosClient({
  openaiApiKey: process.env.OPENAI_API_KEY,
  anthropicApiKey: process.env.ANTHROPIC_API_KEY, // Optional
  googleApiKey: process.env.GOOGLE_API_KEY, // Optional
  pineconeApiKey: process.env.PINECONE_API_KEY,
  pineconeEnvironment: process.env.PINECONE_ENVIRONMENT,
  jwtSecret: process.env.JWT_SECRET
});

// Initialize the SDK
await onairos.initialize();
```

## 🔄 Migration from OpenAI

### Before (OpenAI)
```javascript
import OpenAI from 'openai';
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [
    { role: 'user', content: 'What is artificial intelligence?' }
  ]
});
```

### After (Onairos)
```javascript
import { OnairosClient } from 'onairos';
const onairos = new OnairosClient(config);

const userId = 'user-123';
const sessionToken = onairos.generateSessionToken(userId);

const response = await onairos.completions({
  model: 'gpt-4', // or 'claude-3-sonnet-20240229' or 'gemini-pro'
  messages: [
    { role: 'user', content: 'What is artificial intelligence?' }
  ],
  userId,
  sessionToken
});
```

## 🎯 Usage Examples

### Basic Completion

```javascript
const response = await onairos.completions({
  model: 'gpt-4',
  messages: [
    { role: 'user', content: 'Hello, how are you?' }
  ],
  userId: 'user-123',
  sessionToken: sessionToken,
  options: {
    temperature: 0.7,
    max_tokens: 150
  }
});

console.log(response.choices[0].message.content);
```

### Multi-Provider Usage

```javascript
// OpenAI GPT-4
const gptResponse = await onairos.completions({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Explain quantum computing' }],
  userId, sessionToken
});

// Anthropic Claude
const claudeResponse = await onairos.completions({
  model: 'claude-3-sonnet-20240229',
  messages: [{ role: 'user', content: 'Explain quantum computing' }],
  userId, sessionToken
});

// Google Gemini
const geminiResponse = await onairos.completions({
  model: 'gemini-pro',
  messages: [{ role: 'user', content: 'Explain quantum computing' }],
  userId, sessionToken
});
```

### RAG Memory Enhancement

The SDK automatically stores and retrieves relevant user context:

```javascript
// First interaction - stores user preference
await onairos.completions({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'My favorite programming language is Python' }],
  userId, sessionToken
});

// Later interaction - automatically uses stored context
const response = await onairos.completions({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'What language should I use for my next project?' }],
  userId, sessionToken
});
// Response will consider the user's Python preference
```

### Memory Management

```javascript
// Get user's stored memories
const memories = await onairos.getUserMemory(userId);
console.log(`User has ${memories.length} stored memories`);

// Clear user's memory
await onairos.clearUserMemory(userId);

// Store custom memory
await onairos.memoryManager.storeCustomMemory(
  userId, 
  "User prefers concise explanations", 
  "preference"
);
```

### Session Management

```javascript
// Generate session token
const sessionToken = onairos.generateSessionToken(userId, {
  expiresIn: '24h',
  additionalClaims: { role: 'premium' }
});

// Validate session
try {
  const decoded = await onairos.sessionManager.validateSession(sessionToken);
  console.log('Valid session for user:', decoded.userId);
} catch (error) {
  console.log('Invalid session:', error.message);
}

// Generate guest token
const guestToken = onairos.sessionManager.generateGuestToken();
```

## 🤖 Supported Models

### OpenAI
- `gpt-4`
- `gpt-4-turbo`
- `gpt-3.5-turbo`
- `o1-preview`
- `o1-mini`

### Anthropic
- `claude-3-opus-20240229`
- `claude-3-sonnet-20240229`
- `claude-3-haiku-20240307`
- `claude-3-5-sonnet-20241022`

### Google
- `gemini-pro`
- `gemini-pro-vision`
- `gemini-1.5-pro`
- `gemini-1.5-flash`

## 🧠 How RAG Works

1. **Memory Extraction**: After each interaction, the SDK extracts meaningful information (preferences, goals, context) rather than storing raw conversations
2. **Vector Storage**: Extracted memories are embedded and stored in Pinecone vector database
3. **Context Retrieval**: Before each new query, relevant memories are retrieved using semantic search
4. **Prompt Enhancement**: Retrieved context is automatically injected into the prompt
5. **Privacy Protection**: Only selected, meaningful data is stored, ensuring user privacy

## 🔒 Security Features

- **JWT Authentication**: Secure session management with configurable expiration
- **User Isolation**: Each user's memory is completely isolated
- **Privacy-First**: Only meaningful insights are stored, not raw conversations
- **Session Validation**: All requests require valid session tokens
- **API Key Management**: Secure handling of multiple provider API keys

## 📊 Response Format

The SDK returns responses in OpenAI-compatible format:

```javascript
{
  "id": "onairos-1234567890",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "gpt-4",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Response content here..."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}
```

## 🛠️ Advanced Configuration

### Custom Memory Extraction

```javascript
import { extractMemory } from 'onairos';

// Custom memory extraction logic
const customMemory = extractMemory({
  query: "I love hiking in the mountains",
  response: "That's great! Mountain hiking is excellent exercise..."
});
```

### Direct Component Access

```javascript
import { LLMWrapper, MemoryManager, SessionManager } from 'onairos';

// Use components independently
const llm = new LLMWrapper({ openaiApiKey: 'your-key' });
const memory = new MemoryManager({ pineconeApiKey: 'your-key' });
const session = new SessionManager({ jwtSecret: 'your-secret' });
```

## 🧪 Testing

Run the test suite:

```bash
node test-sdk.js
```

Or run the simple example:

```bash
node example-usage.js
```

## 📝 TypeScript Support

The SDK includes full TypeScript definitions:

```typescript
import { OnairosClient, CompletionParams, CompletionResponse } from 'onairos';

const client: OnairosClient = new OnairosClient(config);

const params: CompletionParams = {
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello' }],
  userId: 'user-123',
  sessionToken: 'token'
};

const response: CompletionResponse = await client.completions(params);
```

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the Apache-2.0 License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support

- 📧 Email: support@onairos.uk
- 🌐 Website: https://onairos.uk
- 📚 Documentation: https://docs.onairos.uk
- 🐛 Issues: https://github.com/zd819/onairos-npm/issues

## 🎉 Benefits

✅ **Unified API** - One interface for all major LLM providers  
✅ **RAG Enhancement** - Automatic personalization with memory  
✅ **Drop-in Replacement** - Minimal migration effort  
✅ **Privacy-Focused** - Selective memory storage  
✅ **Session Security** - JWT-based authentication  
✅ **Multi-Provider** - Switch between models seamlessly  
✅ **Production Ready** - Built for scale and reliability  

---

Made with ❤️ by the Onairos team