adaptive-memory-multi-model-router 1.6.0 → 1.7.0

package/docs/INTEGRATIONS.md

@@ -0,0 +1,420 @@
+# A3M Router - Integration Guide
+
+## Overview
+
+A3M Router includes **116 integrations** across multiple categories:
+
+| Category | Count | Examples |
+|----------|-------|----------|
+| Project Management | 15+ | Asana, Trello, Linear, ClickUp, Monday |
+| CRM & Support | 8+ | HubSpot, Salesforce, Zendesk, Intercom |
+| Marketing | 6+ | Mailchimp, SendGrid, Segment |
+| Analytics | 6+ | Mixpanel, Amplitude, PostHog, Datadog |
+| Communication | 10+ | Slack, Teams, Twilio, Zoom |
+| AI & Vector DBs | 8+ | Pinecone, Weaviate, Qdrant, Chroma |
+| Storage | 5+ | S3, GCS, Azure Blob, Dropbox |
+| Payments | 5+ | Stripe, Square, Braintree, Shopify |
+| Social | 4+ | Twitter, Instagram, LinkedIn |
+| IoT | 5+ | Hue, Wemo, Sonos |
+| DevOps | 10+ | Jenkins, GitLab, Bitbucket, Vercel |
+
+---
+
+## Quick Start
+
+```javascript
+import { createIntegration } from 'adaptive-memory-multi-model-router/integrations';
+
+// GitHub
+const github = createIntegration('github', { apiKey: 'your-token' });
+await github.createIssue('owner', 'repo', 'Bug fix', 'Description');
+
+// Slack
+const slack = createIntegration('slack', { webhookUrl: 'https://hooks.slack.com/...' });
+await slack.sendMessage('#alerts', 'Build complete!');
+```
+
+---
+
+## Project Management Integrations
+
+### Asana
+
+```javascript
+import { AsanaIntegration } from 'adaptive-memory-multi-model-router/integrations/asana';
+
+const asana = new AsanaIntegration(process.env.ASANA_API_KEY);
+
+// Create task
+await asana.createTask(
+  workspaceId = '123456',
+  projectId = '789012',
+  name = 'Implement feature',
+  notes = 'Description here'
+);
+
+// Get tasks
+const tasks = await asana.getTasks(projectId);
+```
+
+### Trello
+
+```javascript
+import { TrelloIntegration } from 'adaptive-memory-multi-model-router/integrations/trello';
+
+const trello = new TrelloIntegration(
+  process.env.TRELLO_API_KEY,
+  process.env.TRELLO_TOKEN
+);
+
+await trello.createCard(boardId, listId, 'New Card', 'Description');
+```
+
+### Linear
+
+```javascript
+import { LinearIntegration } from 'adaptive-memory-multi-model-router/integrations/linear';
+
+const linear = new LinearIntegration(process.env.LINEAR_API_KEY);
+
+await linear.createIssue('Fix bug', 'team-id');
+const teams = await linear.getTeams();
+```
+
+### Monday
+
+```javascript
+import { MondayIntegration } from 'adaptive-memory-multi-model-router/integrations/monday';
+
+const monday = new MondayIntegration(process.env.MONDAY_API_KEY);
+
+const boards = await monday.getBoards();
+await monday.createItem(boardId, 'New Item');
+```
+
+---
+
+## CRM & Customer Support
+
+### HubSpot
+
+```javascript
+import { HubSpotIntegration } from 'adaptive-memory-multi-model-router/integrations/hubspot';
+
+const hubspot = new HubSpotIntegration(process.env.HUBSPOT_API_KEY);
+
+const contacts = await hubspot.getContacts(100);
+await hubspot.createContact('customer@example.com', { firstName: 'John' });
+await hubspot.createDeal('New Deal', { amount: 5000 });
+```
+
+### Salesforce
+
+```javascript
+import { SalesforceIntegration } from 'adaptive-memory-multi-model-router/integrations/salesforce';
+
+const sf = new SalesforceIntegration(
+  'https://your-instance.salesforce.com',
+  process.env.SF_ACCESS_TOKEN
+);
+
+const contacts = await sf.query("SELECT Id, Name FROM Contact LIMIT 10");
+await sf.createRecord('Contact', { Email: 'test@example.com', LastName: 'Test' });
+```
+
+### Zendesk
+
+```javascript
+import { ZendeskIntegration } from 'adaptive-memory-multi-model-router/integrations/zendesk';
+
+const zendesk = new ZendeskIntegration(
+  'your-company',
+  'agent@example.com',
+  process.env.ZENDESK_API_TOKEN
+);
+
+const tickets = await zendesk.getTickets();
+await zendesk.createTicket('Help needed', 'Description of the issue');
+```
+
+---
+
+## Communication
+
+### Slack
+
+```javascript
+import { SlackIntegration } from 'adaptive-memory-multi-model-router/integrations/slack';
+
+const slack = new SlackIntegration(process.env.SLACK_WEBHOOK_URL);
+
+await slack.sendMessage('#dev-team', 'Deployment complete! 🚀');
+await slack.sendMessage('#alerts', { text: 'High latency detected', icon_emoji: ':warning:' });
+```
+
+### Twilio
+
+```javascript
+import { TwilioIntegration } from 'adaptive-memory-multi-model-router/integrations/twilio';
+
+const twilio = new TwilioIntegration(
+  process.env.TWILIO_ACCOUNT_SID,
+  process.env.TWILIO_AUTH_TOKEN
+);
+
+await twilio.sendMessage('+1234567890', 'Your code is ready!');
+```
+
+### Zoom
+
+```javascript
+import { ZoomIntegration } from 'adaptive-memory-multi-model-router/integrations/zoom';
+
+const zoom = new ZoomIntegration(
+  process.env.ZOOM_API_KEY,
+  process.env.ZOOM_API_SECRET
+);
+
+const meeting = await zoom.createMeeting('Team Standup', 30);
+console.log('Join URL:', meeting.join_url);
+```
+
+---
+
+## AI & Vector Databases
+
+### Pinecone
+
+```javascript
+import { PineconeIntegration } from 'adaptive-memory-multi-model-router/integrations/pinecone';
+
+const pinecone = new PineconeIntegration(
+  process.env.PINECONE_API_KEY,
+  'us-west-2'
+);
+
+await pinecone.createIndex('my-index', 1536);
+await pinecone.upsertVectors('my-index', [
+  { id: 'vec1', vector: [...], metadata: { text: 'hello' } }
+]);
+
+const results = await pinecone.query('my-index', vector, 10);
+```
+
+### Weaviate
+
+```javascript
+import { WeaviateIntegration } from 'adaptive-memory-multi-model-router/integrations/weaviate';
+
+const weaviate = new WeaviateIntegration(
+  'http://localhost:8080',
+  process.env.WEAVIATE_API_KEY
+);
+
+await weaviate.createObject('Article', { title: 'Hello', content: 'World' });
+const articles = await weaviate.getObjects('Article');
+```
+
+---
+
+## Storage
+
+### S3
+
+```javascript
+import { S3Integration } from 'adaptive-memory-multi-model-router/integrations/s3';
+
+const s3 = new S3Integration(
+  process.env.AWS_ACCESS_KEY_ID,
+  process.env.AWS_SECRET_ACCESS_KEY,
+  'us-east-1'
+);
+
+await s3.putObject('my-bucket', 'path/to/file.txt', 'Hello World');
+const data = await s3.getObject('my-bucket', 'path/to/file.txt');
+```
+
+### Dropbox
+
+```javascript
+import { DropboxIntegration } from 'adaptive-memory-multi-model-router/integrations/dropbox';
+
+const dropbox = new DropboxIntegration(process.env.DROPBOX_ACCESS_TOKEN);
+
+await dropbox.uploadFile('/path/to/file.txt', 'File content');
+const content = await dropbox.downloadFile('/path/to/file.txt');
+```
+
+---
+
+## Payments
+
+### Stripe
+
+```javascript
+import { StripeIntegration } from 'adaptive-memory-multi-model-router/integrations/stripe';
+
+const stripe = new StripeIntegration(process.env.STRIPE_API_KEY);
+
+const charge = await stripe.createCharge(1999, 'usd', 'cus_123');
+const charges = await stripe.getCharges(10);
+```
+
+### Shopify
+
+```javascript
+import { ShopifyIntegration } from 'adaptive-memory-multi-model-router/integrations/shopify';
+
+const shopify = new ShopifyIntegration(
+  'my-store.myshopify.com',
+  process.env.SHOPIFY_ACCESS_TOKEN
+);
+
+const products = await shopify.getProducts(50);
+const order = await shopify.createOrder([
+  { variant_id: 123, quantity: 2 }
+]);
+```
+
+---
+
+## Analytics & Monitoring
+
+### Mixpanel
+
+```javascript
+import { MixpanelIntegration } from 'adaptive-memory-multi-model-router/integrations/mixpanel';
+
+const mixpanel = new MixpanelIntegration(process.env.MIXPANEL_TOKEN);
+
+await mixpanel.track('Purchase', { 
+  userId: 'user-123', 
+  value: 99.99,
+  item: 'Premium Plan'
+});
+```
+
+### Datadog
+
+```javascript
+import { DataDogIntegration } from 'adaptive-memory-multi-model-router/integrations/datadog';
+
+const datadog = new DataDogIntegration(
+  process.env.DD_API_KEY,
+  process.env.DD_APP_KEY
+);
+
+await datadog.postMetric('app.latency', 150);
+const metrics = await datadog.getMetrics('app.latency');
+```
+
+---
+
+## DevOps
+
+### GitHub
+
+```javascript
+import { GitHubIntegration } from 'adaptive-memory-multi-model-router/integrations/github';
+
+const github = new GitHubIntegration(process.env.GITHUB_TOKEN);
+
+const repo = await github.getRepo('owner', 'repo');
+await github.createIssue('owner', 'repo', 'Bug', 'Description');
+await github.createPR('owner', 'repo', 'Feature', 'feature-branch', 'main');
+```
+
+### GitLab
+
+```javascript
+import { GitLabIntegration } from 'adaptive-memory-multi-model-router/integrations/gitlab';
+
+const gitlab = new GitLabIntegration(process.env.GITLAB_TOKEN);
+
+const projects = await gitlab.getProjects();
+await gitlab.createMR('project-id', 'feature-branch', 'main');
+```
+
+### Jenkins
+
+```javascript
+import { JenkinsIntegration } from 'adaptive-memory-multi-model-router/integrations/jenkins';
+
+const jenkins = new JenkinsIntegration(
+  'https://jenkins.example.com',
+  'admin',
+  process.env.JENKINS_API_TOKEN
+);
+
+const jobs = await jenkins.getJobs();
+await jenkins.buildJob('my-job');
+```
+
+---
+
+## Using OAuth Manager
+
+```javascript
+import { OAuthManager } from 'adaptive-memory-multi-model-router/oauth';
+
+const oauth = new OAuthManager();
+
+// Configure OAuth for Slack
+oauth.configure('slack', {
+  clientId: process.env.SLACK_CLIENT_ID,
+  clientSecret: process.env.SLACK_CLIENT_SECRET,
+  redirectUri: 'https://myapp.com/callback/slack'
+});
+
+// Get authorization URL
+const authUrl = oauth.getAuthUrl('slack');
+
+// In your callback handler
+const tokens = await oauth.handleCallback('slack', code, state);
+
+// Make authenticated requests
+oauth.apiRequest('slack', '/chat.postMessage', {
+  method: 'POST',
+  body: JSON.stringify({ channel: '#general', text: 'Hello!' })
+});
+```
+
+---
+
+## Error Handling
+
+```javascript
+import { createIntegration } from 'adaptive-memory-multi-model-router/integrations';
+
+const github = createIntegration('github', { apiKey: 'invalid' });
+
+try {
+  await github.createIssue('owner', 'repo', 'Title', 'Body');
+} catch (error) {
+  console.error('GitHub API Error:', error.message);
+  // Handle: retry, fallback, or alert
+}
+```
+
+---
+
+## Integration Factory
+
+Use `createIntegration` for quick setup:
+
+```javascript
+import { createIntegration } from 'adaptive-memory-multi-model-router/integrations';
+
+// All integrations available via string name
+const integration = createIntegration('stripe', { apiKey: 'sk_...' });
+const integration2 = createIntegration('slack', { webhookUrl: 'https://...' });
+const integration3 = createIntegration('pinecone', { apiKey: '...', environment: 'us-west-2' });
+
+// Supported integration names:
+// github, slack, telegram, notion, linear, jira, gmail, discord, airtable,
+// google-calendar, asana, trello, stripe, shopify, intercom, sendgrid,
+// mailchimp, hubspot, salesforce, zendesk, mixpanel, amplitude, segment,
+// posthog, datadog, newrelic, sentry, grafana, pagerduty, aws-s3, gcs,
+// azureblob, dropbox, jenkins, gitlab, bitbucket, vercel, netlify, pinecone,
+// weaviate, qdrant, chromadb, and 70+ more!
+```

package/docs/QUICKSTART.md

@@ -0,0 +1,271 @@
+# A3M Router - Quick Start Guide
+
+## 5-Minute Setup
+
+### Step 1: Install
+
+```bash
+npm install adaptive-memory-multi-model-router
+```
+
+### Step 2: Basic Usage
+
+```javascript
+import { createA3MRouter } from 'adaptive-memory-multi-model-router';
+
+const router = createA3MRouter({
+  memory: true,
+  costBudget: 0.05
+});
+
+// Route a request
+const result = await router.route({
+  prompt: 'Explain quantum entanglement'
+});
+
+console.log(result.output);
+console.log('Provider:', result.provider);
+console.log('Cost:', result.cost);
+```
+
+### Step 3: Add Integrations
+
+```javascript
+import { createIntegration } from 'adaptive-memory-multi-model-router/integrations';
+
+// GitHub
+const github = createIntegration('github', { apiKey: process.env.GITHUB_TOKEN });
+await github.createIssue('owner', 'repo', 'Bug', 'Fix this');
+
+// Slack
+const slack = createIntegration('slack', { webhookUrl: process.env.SLACK_WEBHOOK });
+await slack.sendMessage('#team', 'Build complete!');
+```
+
+---
+
+## Examples
+
+### Example 1: Smart Routing with Memory
+
+```javascript
+import { createA3MRouter } from 'adaptive-memory-multi-model-router';
+
+const router = createA3MRouter({
+  memory: true,        // Enable memory tree
+  costBudget: 0.05,    // Max $0.05 per request
+  providers: ['openai', 'groq', 'anthropic', 'cerebras']
+});
+
+async function handleUserQuery(query) {
+  // Route with context from memory
+  const result = await router.route({
+    prompt: query,
+    context: {
+      type: detectIntent(query),
+      history: memory.getContext(2000)
+    }
+  });
+  
+  // Learn from this interaction
+  memory.add({ query, response: result.output, provider: result.provider });
+  
+  return result;
+}
+```
+
+### Example 2: Batch Processing
+
+```javascript
+import { batchProcess } from 'adaptive-memory-multi-model-router';
+
+const tasks = [
+  'Analyze this data',
+  'Write unit tests',
+  'Document API',
+  'Review PR',
+  'Write release notes'
+];
+
+const results = await batchProcess(tasks, {
+  maxParallel: 3,
+  provider: 'openai'
+});
+
+results.forEach((result, i) => {
+  console.log(`Task ${i+1}: ${result.output.slice(0, 50)}...`);
+});
+```
+
+### Example 3: Cost-Optimized Routing
+
+```javascript
+import { createA3MRouter } from 'adaptive-memory-multi-model-router';
+
+const router = createA3MRouter({
+  costBudget: 0.02,  // Very low budget
+  providers: ['groq', 'cerebras']  // Fast + free tier
+});
+
+// Simple queries go to fast free providers
+// Complex queries route to best available
+
+const queries = [
+  'What is 2+2?',           // → Groq (fast, free)
+  'Explain black holes',      // → Cerebras (free tier)
+  'Debug my 10k line program'  // → Cerebras (best available)
+];
+
+for (const query of queries) {
+  const result = await router.route({ prompt: query });
+  console.log(`${query.slice(0, 30)}... → ${result.provider} ($${result.cost.toFixed(4)})`);
+}
+```
+
+### Example 4: Auto-Fetch for Context
+
+```javascript
+import { AutoFetch } from 'adaptive-memory-multi-model-router/autofetch';
+import { MemoryTree } from 'adaptive-memory-multi-model-router/memory';
+
+const fetcher = new AutoFetch({
+  intervalMs: 20 * 60 * 1000,  // 20 minutes
+  targets: ['github', 'notion', 'slack']
+});
+
+const memory = new MemoryTree();
+
+fetcher.start();
+
+// On each sync, memory automatically updated
+fetcher.on('sync', (target, data) => {
+  memory.add(data);
+  console.log(`${target} synced, memory now has ${memory.getStats().totalChunks} chunks`);
+});
+
+// Now routing has fresh context
+const result = await router.route({
+  prompt: userQuery,
+  context: { context: memory.getContext(3000) }
+});
+```
+
+### Example 5: Compression for Large Contexts
+
+```javascript
+import { EnhancedCompression } from 'adaptive-memory-multi-model-router/compression';
+
+const compressor = new EnhancedCompression();
+
+// Compress HTML content
+const htmlContent = `
+  <html><body>
+    <h1>Document Title</h1>
+    <p>This is a very long paragraph with a very long URL: 
+    https://example.com/very/very/very/very/very/long/path/that/should/be/shortened</p>
+  </body></html>
+`;
+
+const compressed = compressor.compress(htmlContent);
+// Output: '# Document Title\n\nThis is a very long paragraph with a URL: example.com/...'
+
+console.log('Reduced from', htmlContent.length, 'to', compressed.length, 'chars');
+```
+
+### Example 6: Obsidian Vault for Audit Trail
+
+```javascript
+import { ObsidianVault } from 'adaptive-memory-multi-model-router/vault';
+import { createA3MRouter } from 'adaptive-memory-multi-model-router';
+
+const vault = new ObsidianVault({ path: './my-vault' });
+const router = createA3MRouter();
+
+router.on('route', async (request, result) => {
+  // Save every routing decision
+  await vault.saveDecision({
+    id: generateId(),
+    timestamp: Date.now(),
+    prompt: request.prompt,
+    selectedProvider: result.provider,
+    selectedModel: result.model,
+    reasoning: result.reasoning,
+    cost: result.cost,
+    latency: result.latency
+  });
+});
+
+// Later, review routing decisions in Obsidian
+const recent = vault.getRecentDecisions(50);
+// Open ./my-vault/routing-index.md in Obsidian to browse
+```
+
+---
+
+## CLI Quick Reference
+
+```bash
+# Route a query
+a3m-router route "Explain quantum computing"
+
+# Parallel execution
+a3m-router parallel "task1" "task2" "task3"
+
+# Compare models
+a3m-router compare "Write a haiku"
+
+# Cost summary
+a3m-router cost
+
+# Token counting
+a3m-router count "Your text here"
+
+# Compress text
+a3m-router compress "<html>content</html>"
+
+# Local Ollama
+a3m-router local "Write Python hello world"
+```
+
+---
+
+## Environment Variables
+
+```bash
+# LLM Providers
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+GROQ_API_KEY=gsk_...
+CEREBRAS_API_KEY=...
+
+# Integrations
+GITHUB_TOKEN=ghp_...
+SLACK_WEBHOOK=https://hooks.slack.com/...
+PINECONE_API_KEY=...
+STRIPE_API_KEY=sk_...
+
+# Optional
+LOG_LEVEL=info
+CACHE_TTL=3600
+```
+
+---
+
+## Next Steps
+
+1. **Read the full [API Documentation](API.md)**
+2. **Explore [116 Integrations](INTEGRATIONS.md)**
+3. **Deploy to production** with proper monitoring
+4. **Join the community** for support
+
+---
+
+## Performance Tips
+
+| Tip | Impact |
+|-----|--------|
+| Use memory tree | 10x faster routing |
+| Enable compression | 2-5x less tokens |
+| Use batch processing | 3x throughput |
+| Configure cost budgets | 40% cost savings |
+| Use provider caching | 5x fewer API calls |