npm package: @kitiumai/agents
Description: 🚀 Zero-cost multi-provider AI agent framework. Support for OpenAI, Claude, Ollama + smart routing, cost tracking & RAG.
Author: Kitium AI
Latest version: 1.0.0

# @kitiumai/agents

**Zero-cost, multi-provider AI agent framework**

## 🎯 Overview

This is a lightweight, open-source framework for building cost-effective AI agents with support for multiple LLM providers. Perfect for startups and teams building AI products on a budget.

### Key Features

- ✅ **Zero-cost core** - Provider abstraction layer with no vendor lock-in
- ✅ **Multi-provider support** - OpenAI, Claude, Ollama, custom providers
- ✅ **Smart routing** - Route requests based on task complexity and cost
- ✅ **Cost tracking** - Monitor spending across providers
- ✅ **Production-ready** - TypeScript, ESM/CJS, full type safety
- ✅ **RAG support** - Retrieval-Augmented Generation with Qdrant
- ✅ **Extensible** - Easy to add new providers and agents

## 📦 Installation

```bash
npm install @kitiumai/agents
# or
yarn add @kitiumai/agents
```

## 🚀 Quick Start

### 1. Basic Setup

```typescript
import { LLMGateway, DefaultProviderRegistry } from '@kitiumai/agents/core';
import { OpenAIProvider } from '@kitiumai/agents/providers/openai';

// Register providers
const registry = getProviderRegistry();
registry.register('openai', new OpenAIProvider({
  apiKey: process.env.OPENAI_API_KEY
}));

// Create gateway
const gateway = new LLMGateway({
  defaultProvider: 'openai',
  defaultModel: 'gpt-3.5-turbo',
  costOptimization: true,
});

// Use it
const response = await gateway.chat([
  { role: 'user', content: 'Hello, how can I use this framework?' }
]);

console.log(response.content);
console.log(`Cost: $${response.cost}`);
```

### 2. Multi-Provider Setup

```typescript
import { LLMGateway } from '@kitiumai/agents/core';
import { OpenAIProvider } from '@kitiumai/agents/providers/openai';
import { ClaudeProvider } from '@kitiumai/agents/providers/claude';
import { OllamaProvider } from '@kitiumai/agents/providers/ollama';

const registry = getProviderRegistry();

// Register multiple providers
registry.register('openai', new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }));
registry.register('claude', new ClaudeProvider({ apiKey: process.env.CLAUDE_API_KEY }));
registry.register('ollama', new OllamaProvider({ baseURL: 'http://localhost:11434' }));

// Smart routing based on task complexity
const response = await gateway.chatWithSmartRouting(
  [{ role: 'user', content: 'Complex reasoning task' }],
  'reasoning' // Uses Claude Opus
);
```

### 3. Cost Optimization

```typescript
// Smart routing minimizes costs
const simpleTask = await gateway.chatWithSmartRouting(
  messages,
  'simple' // Uses local Ollama (FREE)
);

const mediumTask = await gateway.chatWithSmartRouting(
  messages,
  'medium' // Uses GPT-3.5 ($0.0005/1K tokens)
);

const complexTask = await gateway.chatWithSmartRouting(
  messages,
  'complex' // Uses Claude Sonnet ($0.003/1M input tokens)
);

// Track spending
console.log(gateway.getCosts());
console.log(`Total: $${gateway.getTotalCost()}`);
```

### 4. Health Check

```typescript
const health = await gateway.healthCheck();
console.log(health);
// Output: { openai: true, claude: true, ollama: true }
```

## 🏗️ Architecture

```
Your Application
       ↓
   LLMGateway (Unified Interface)
       ↓
   Provider Registry
       ↓
   ┌─────────┬─────────┬────────┐
   ↓         ↓         ↓        ↓
OpenAI    Claude    Ollama   Custom
```

## 📊 Cost Breakdown (Zero-cost)

| Scenario | Cost | Notes |
|----------|------|-------|
| **Development** | $0 | Free tier credits + local Ollama |

## 🔌 Providers

### OpenAI
```typescript
import { OpenAIProvider } from '@kitiumai/agents/providers';

const registry = getProviderRegistry();
registry.register('openai', new OpenAIProvider({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: 'https://api.openai.com/v1', // Optional
  organization: 'your-org-id', // Optional
}));

// Supported models: gpt-3.5-turbo, gpt-4, gpt-4-turbo, gpt-4-vision
```

**Pricing:** GPT-3.5 Turbo: $0.0005/1K input tokens | GPT-4: $0.03/1K input

### Claude (Anthropic)
```typescript
import { ClaudeProvider } from '@kitiumai/agents/providers';

const registry = getProviderRegistry();
registry.register('claude', new ClaudeProvider({
  apiKey: process.env.ANTHROPIC_API_KEY,
}));

// Supported models: claude-3-haiku, claude-3-sonnet, claude-3-opus, claude-3.5-sonnet
```

**Pricing:** Haiku: $0.0008/1K input | Sonnet: $0.003/1K | Opus: $0.015/1K

### Ollama (Local - FREE)
```typescript
import { OllamaProvider } from '@kitiumai/agents/providers';

const registry = getProviderRegistry();
registry.register('ollama', new OllamaProvider({
  baseURL: 'http://localhost:11434',
}));

// Install: https://ollama.ai
// Pull models: ollama pull mistral
// Supported models: mistral, neural-chat, orca-mini, llama2, codellama, etc.
```

**Pricing:** FREE (only pay for compute) | Perfect for development

### Custom Provider
```typescript
import { LLMProvider, ChatMessage, ChatResponse, ChatOptions } from '@kitiumai/agents/core';

class MyCustomProvider implements LLMProvider {
  readonly name = 'custom' as const;

  async chat(
    messages: ChatMessage[],
    model: string,
    options?: ChatOptions
  ): Promise<ChatResponse> {
    // Your implementation
    return {
      content: 'response',
      model,
      provider: 'custom',
      cost: 0.01,
    };
  }

  async countTokens(text: string, model: string): Promise<number> {
    return Math.ceil(text.length / 4); // Rough estimate
  }

  getCost(inputTokens: number, outputTokens: number, model: string): number {
    return (inputTokens + outputTokens) * 0.0001;
  }

  async listModels(): Promise<string[]> {
    return ['custom-model-1', 'custom-model-2'];
  }

  async health(): Promise<boolean> {
    return true;
  }
}

const registry = getProviderRegistry();
registry.register('custom', new MyCustomProvider());
```

## 🔄 RAG (Retrieval-Augmented Generation)

```typescript
import { RAGSystem } from '@kitiumai/agents/rag';

const rag = new RAGSystem({
  vectorStoreUrl: 'http://localhost:6333', // Qdrant
});

// Add documents
await rag.addDocuments([
  { id: '1', content: 'Document 1' },
  { id: '2', content: 'Document 2' },
]);

// Retrieve and generate
const answer = await rag.generate(
  'What is in document 1?',
  gateway // Pass gateway for LLM
);

console.log(answer);
```

## 💡 Use Cases

- **Startups** - Zero-cost MVP with multi-provider flexibility
- **Teams** - Unified interface across different LLMs
- **Cost-sensitive** - Automatic routing to cheapest appropriate provider
- **Privacy** - Use local models for sensitive data
- **Experimentation** - Easy A/B testing between providers

## 🛡️ Features

- ✅ Full TypeScript support
- ✅ Comprehensive error handling
- ✅ Health checks and monitoring
- ✅ Cost tracking and optimization
- ✅ Tested with major providers
- ✅ ESM and CommonJS support

## 📄 License

MIT

## 🤝 Contributing

Contributions welcome! This is the open-source core. Extended agent implementations remain private within kitium-agents repo.

## 📝 Note

This is the **open-source zero-cost core** that can be used in any project. The full `kitium-agents` repository extends this with:
- Private agent implementations
- Custom fine-tuned models
- Proprietary agent logic

For the full version, see the private `kitium-agents` repo.

---

Built with ❤️ by [Kitium AI](https://kitium.ai)