cairo-sdk

v2.1.0

Published

6 months ago

Production-Ready Agentic LLM Execution with Intelligent Tool Selection - MCP-RAG technology with 100% accuracy in sub-20ms

0High
0Medium
0Low

cairo.colomboai

ai llm automation mcp rag intelligent-tools semantic-search production-ready typescript nodejs

Cairo-SDK

Production-Ready Agentic LLM Execution with Intelligent Tool Selection

Cairo SDK v2.0 introduces revolutionary MCP-RAG (Model Context Protocol - Retrieval Augmented Generation) technology that achieves 100% accuracy in tool selection with sub-20ms latency. Transform your applications with semantic understanding and intelligent automation.

🚀 Key Features

🧠 Intelligent Tool Selection

100% Accuracy: Perfect precision and recall in tool selection
Semantic Understanding: Advanced embedding-based context awareness
Sub-20ms Queries: Lightning-fast response times (16.5ms average)
Smart Filtering: Automatic relevance threshold and scope detection

⚡ Production-Optimized Performance

Multi-Tier Caching: 4-layer cache system with 95%+ hit rates
Native ChromaDB: Zero Docker dependency with automatic fallbacks
Batch Processing: Efficient embedding computation
Rate Limiting: Token Bucket algorithm prevents API overload
Graceful Degradation: ChromaDB → pgvector → in-memory fallbacks

🏗️ Enterprise Architecture

MCP Protocol Compliance: Full Model Context Protocol mc-1 support
Policy System: Configurable governance and security policies
Smart Type Detection: Automatic UI/API pattern recognition
Production Monitoring: Built-in metrics and health checks

🌐 Supported Technologies

Cairo SDK is a server-side Node.js package that works with:

✅ Next.js (API Routes - Recommended)
✅ Express.js (REST APIs)
✅ Fastify (High-performance APIs)
✅ NestJS (Enterprise applications)
✅ Vanilla Node.js (Custom servers)

⚠️ Important: Cairo SDK runs on the server only. For browser/React usage, create API endpoints that call Cairo SDK.

📦 Installation

npm install cairo-sdk

🔑 Getting Your API Key

Visit platform.colomboai.com
Sign up or log in to your account
Navigate to API Keys section
Generate a new API key for your application
Copy the key and add it to your environment variables

# .env file
CAIRO_API_KEY=sk-your-api-key-here

Why API Key is Required:

Authenticates your application with Cairo services
Tracks usage and billing
Enables skill-first optimization (FREE skills + PAID MC-1 fallback)
Provides access to Cairo's intelligent routing

⚡ Quick Start

Minimal Setup (Production-Ready)

import { Cairo } from 'cairo-sdk';

// Only API key required - everything else is automatic!
const cairo = new Cairo({
  apiKey: process.env.CAIRO_API_KEY  // Get from platform.colomboai.com
});

// That's it! Start using Cairo SDK
const result = await cairo.ask("Your query here");
console.log(result);

Optional Configuration (Advanced)

// Customize caching, database, etc. (all optional)
const cairo = new Cairo({
  apiKey: process.env.CAIRO_API_KEY,
  cache: { type: 'file', maxSize: 5000 },
  database: { enableChromaDB: true }
});

🚀 Integration Guides

Next.js (Recommended)

Step 1: Create API Route

// app/api/cairo/route.ts
import { Cairo } from 'cairo-sdk';
import { NextRequest } from 'next/server';

const cairo = new Cairo({
  apiKey: process.env.CAIRO_API_KEY
});

export async function POST(request: NextRequest) {
  const { query } = await request.json();
  const result = await cairo.ask(query);
  return Response.json(result);
}

Step 2: Call from Frontend

// app/components/ChatInterface.tsx
const response = await fetch('/api/cairo', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ query: userMessage })
});
const result = await response.json();

Express.js

import express from 'express';
import { Cairo } from 'cairo-sdk';

const app = express();
const cairo = new Cairo({ apiKey: process.env.CAIRO_API_KEY });

app.post('/api/cairo', async (req, res) => {
  const result = await cairo.ask(req.body.query);
  res.json(result);
});

app.listen(3000);

🎯 Choosing the Right Method

Use `ask()` for:

// ✅ Automation & Background Jobs
const result = await cairo.ask("Qualify this lead");

// ✅ Batch Processing
const descriptions = await Promise.all(
  properties.map(p => cairo.ask(`Generate description for ${p}`))
);

// ✅ Structured Outputs
const analysis = await cairo.ask("Analyze market trends");
// Returns: { content, actionResults, skillUsed, costSaved }

Use `askStream()` for:

// ✅ Chat Interfaces (Progressive Display)
for await (const chunk of cairo.askStream(userMessage)) {
  displayInChat(chunk.data);  // Show text as it arrives
}

// ✅ Long-Form Content Generation
for await (const chunk of cairo.askStream("Write detailed report")) {
  updateProgress(chunk);  // User sees progress
}

// ✅ Real-Time Feedback
for await (const chunk of cairo.askStream("Generate property listing")) {
  showLivePreview(chunk);  // Live preview as content generates
}

Quick Decision:

Need complete response at once? → ask()
Need progressive display? → askStream()
Background task? → ask()
User waiting and watching? → askStream()

💡 How Cairo SDK Works

Cairo SDK intelligently routes your requests:

Your App → Cairo SDK → Intelligent Routing
                         ↓
                    Skills (FREE) ✅
                         ↓
                    MC-1 API (PAID) 💰

Cost Optimization:

Common queries use FREE skills (cached responses)
Complex queries use PAID MC-1 (advanced LLM)
Cairo SDK automatically chooses the best option
You save money without any extra code!

🔧 Troubleshooting

For End Users

"Invalid API Key" Error

✅ Check API key is correct from platform.colomboai.com
✅ Verify environment variable is loaded: console.log(process.env.CAIRO_API_KEY)
✅ Ensure no extra spaces or quotes in .env file

"Request Timeout" Error

✅ Check your internet connection
✅ Verify Cairo services status at status.colomboai.com
✅ Try increasing timeout: new Cairo({ timeout: 60000 })

"Module not found: cairo-sdk"

✅ Run: npm install cairo-sdk
✅ Restart your development server
✅ Check package.json includes cairo-sdk

Streaming Not Working

✅ Ensure you're using for await loop
✅ Check Node.js version >= 18
✅ Verify API route returns proper stream

🎯 Performance Benchmarks

| Metric | Achievement | Target | Status | |--------|-------------|--------|---------| | Query Latency | 16.5ms | <50ms | ✅ 67% better | | Tool Accuracy | 100% | >85% | ✅ Perfect | | Precision | 100% | >80% | ✅ Perfect | | Cache Hit Rate | 95%+ | >80% | ✅ Excellent | | Memory Usage | <100MB | <200MB | ✅ Optimized |

🔀 Intelligent Endpoint Routing

| Use Case | Recommended Method | Endpoint | Optimization | |----------|-------------------|----------|-------------| | Skills Execution | ask() or askSync() | /api/ask | ✅ Fast & Reliable | | Chat Interfaces | askStream() | /api/stream | ✅ Progressive | | Media Generation | askStream() | /api/stream | ✅ Real-time | | Developer Control | askStreamForced() | /api/stream | ✅ Explicit |

🛠️ For Contributors & Developers

🏗️ Advanced Configuration (Local Development)

const cairo = new Cairo({
  apiKey: process.env.CAIRO_API_KEY,
  backendUrl: 'https://caicairo-services-1-dev-dot-fair-myth-398920.uc.r.appspot.com/',  // For local Cairo Backend development
  
  // Scraping configuration
  scraping: {
    enabled: true,
    refreshInterval: 3600000,
    whitelist: ['https://trusted-domain.com']
  },
  
  // Database configuration
  database: {
    enableChromaDB: true,
    chromaUrl: 'http://localhost:8000',
    enablePgVector: true,
    connectionString: 'postgresql://user:pass@localhost/cairo'
  },
  
  // Cache configuration
  cache: {
    type: 'file',
    filePath: './.cairo-cache.json',
    maxSize: 5000,
    ttl: 7200000
  }
});

🏗️ Technical Architecture (For Contributors)

App → Cairo SDK → Cairo Backend → Skills DB (PostgreSQL)
                       ↓              ↓
                   MC-1 API ←── Skill Match? → Return (FREE)
                       ↓
                   LLM Call → Return (PAID)

Internal Architecture:

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   User Query    │───▶│   MCP-RAG Core   │───▶│  Selected Tools │
│ "login account" │    │  Semantic Engine │    │ [login, email]  │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                              ▼
                    ┌──────────────────┐
                    │  Multi-Tier Cache │
                    │ Hot → Embedding  │ ◄── 95%+ Hit Rate
                    │ Query → Tool     │     <1ms Access
                    └──────────────────┘
                              │
                              ▼
                    ┌──────────────────┐
                    │  Vector Backends │
                    │ Native ChromaDB  │ ◄── Primary (No Docker)
                    │ PostgreSQL       │ ◄── Enterprise Fallback
                    │ In-Memory        │ ◄── Final Fallback
                    └──────────────────┘

Local Development Setup:

Cairo Backend runs on https://caicairo-services-1-dev-dot-fair-myth-398920.uc.r.appspot.com/
Skills stored in PostgreSQL database
MC-1 API at https://mc1.colomboai.com/v1/
See CONTRIBUTING.md for detailed setup

🧪 Testing & Validation

# Run comprehensive production tests
npm run test-production     # Full system validation
npm run test-precision      # Accuracy verification (100%)
npm run test-cache-simple   # Cache performance
npm run test-qwen-chroma    # Embedding integration

# Individual component tests
npm run test-smart-types    # Smart type detection
npm run test-policy         # Policy system
npm run test-pgvector      # PostgreSQL backend
npm run test-rate-limit    # Rate limiting validation

🔧 Troubleshooting (Developers)

Local Cairo Backend Setup

See CONTRIBUTING.md
Requires PostgreSQL, Cairo Backend, MC-1 API access

Build Errors

Run: npm run build
Check TypeScript version >= 5.0
Verify all dependencies installed

🔧 API Reference

Cairo Class

Constructor

new Cairo(config: CairoConfig)

Core Methods

init(appUrl?: string): Promise<void> - Initialize with intelligent tool discovery
ask(prompt: string, options?: AskOptions): Promise<CairoResult> - Smart routing (sync for skills, optimized)
askSync(prompt: string, options?: AskOptions): Promise<CairoResult> - Force sync endpoint (/api/ask)
askStream(prompt: string, options?: AskOptions): AsyncIterator<CairoStreamChunk> - Smart streaming (auto-detects use case)
askStreamForced(prompt: string, options?: AskOptions): AsyncIterator<CairoStreamChunk> - Force streaming (/api/stream)
askWithSkills(prompt: string, options?: AskOptions): Promise<CairoResult> - Skills-first execution
close(): Promise<void> - Cleanup with proper resource management

MCP-RAG Methods (New in v2.0)

searchTools(query: string, options?: { scope?, k? }): Promise<RAGResult[]> - Semantic tool search
explainToolSelection(toolId: string): Promise<any> - Tool selection explanation
getMCPManifest(): object - MCP protocol manifest
getMetrics(): object - Performance metrics

Configuration Types

interface CairoConfig {
  // All fields are optional - SDK provides sensible defaults
  apiKey?: string;              // Default: 'cairo-sdk-token'
  backendUrl?: string;          // Default: 'http://localhost:8000'
  scraping?: ScrapingConfig;
  database?: {
    enableChromaDB?: boolean;      // Native ChromaDB (recommended)
    chromaUrl?: string;            // Optional Docker ChromaDB
    enablePgVector?: boolean;      // PostgreSQL fallback
    connectionString?: string;     // PostgreSQL connection
  };
  cache?: {
    type?: 'memory' | 'file' | 'redis';  // Storage backend (default: memory)
    maxSize?: number;                     // Max entries per tier
    ttl?: number;                        // Time-to-live in ms
    filePath?: string;                   // File-based cache path
  };
}

📚 Documentation

MCP-RAG Enhancement Guide - Comprehensive feature documentation
Rate Limiting Guide - Rate limiting configuration and tuning
Production Readiness Audit - Deployment guide
ChromaDB Setup Guide - Vector database configuration
Security Guide - Security best practices
Changelog - Version history and breaking changes

🚀 Production Deployment

Readiness Checklist

✅ Performance: Sub-20ms query responses
✅ Accuracy: 100% precision and recall
✅ Reliability: Multi-tier fallback systems
✅ Monitoring: Built-in metrics and health checks
✅ Security: Policy-based access control
✅ Scalability: 5000+ tools per cache tier

Enterprise Features

High Availability: Automatic backend failover
Observability: Comprehensive performance tracking
Security: Configurable governance policies
Performance: Multi-tier caching with 95%+ hit rates
Compliance: Full MCP protocol mc-1 support

🤝 Contributing

We welcome contributions! Please see our contributing guidelines and run the test suite:

npm run test-production  # Ensure all tests pass

📄 License

MIT - See LICENSE for details

Cairo SDK v2.0 - Production-Ready Intelligent Automation 🚀