@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

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

🚀 Quick Start

1. Basic Setup

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

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

// 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

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

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)

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)

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

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)

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