adaptive-memory-multi-model-router 2.13.18 → 2.13.20

package/integrations/langchain/example.ts

@@ -0,0 +1,287 @@
+/**
+ * A3M Router — LangChain Integration Example
+ *
+ * Run with: npx ts-node integrations/langchain/example.ts
+ * Or: npx tsx integrations/langchain/example.ts
+ *
+ * Prerequisites:
+ *   npm install @langchain/core
+ *   export GROQ_API_KEY=gsk_your_key_here
+ *   export OPENAI_API_KEY=sk-your-key-here
+ */
+
+// ============================================================
+// Example 1: Basic Usage (Single Provider Routing)
+// ============================================================
+
+import { A3MLLM, A3M_DEFAULT_PROVIDERS } from './a3m_langchain';
+
+async function exampleBasic() {
+  console.log('\n=== Example 1: Basic Routing ===\n');
+
+  const llm = new A3MLLM({
+    providers: {
+      groq: {
+        ...A3M_DEFAULT_PROVIDERS.groq,
+        apiKey: process.env.GROQ_API_KEY,
+      },
+    },
+    temperature: 0.7,
+  });
+
+  const response = await llm.invoke('What is the capital of France?');
+  console.log('Response:', response);
+}
+
+// ============================================================
+// Example 2: Multi-Provider with Cost-Based Routing
+// ============================================================
+
+async function exampleMultiProvider() {
+  console.log('\n=== Example 2: Multi-Provider Cost-Based Routing ===\n');
+
+  const llm = new A3MLLM({
+    providers: {
+      groq: {
+        ...A3M_DEFAULT_PROVIDERS.groq,
+        apiKey: process.env.GROQ_API_KEY,
+      },
+      openai: {
+        ...A3M_DEFAULT_PROVIDERS.openai,
+        apiKey: process.env.OPENAI_API_KEY,
+      },
+      nvidia: {
+        ...A3M_DEFAULT_PROVIDERS.nvidia,
+        apiKey: process.env.NVIDIA_API_KEY,
+      },
+    },
+    routingStrategy: 'cheapest', // Auto-pick the cheapest available provider
+    fallbackEnabled: true,       // Fall back to next provider on failure
+    onRoute: (info) => {
+      console.log(`[Route] ${info.strategy} → ${info.provider}/${info.model}`);
+    },
+    onError: (info) => {
+      console.log(`[Error] ${info.provider}: ${info.error} (fallback: ${info.willFallback})`);
+    },
+  });
+
+  const { text, metadata } = await llm.invokeWithMetadata(
+    'Explain quantum entanglement in simple terms.',
+  );
+
+  console.log('Response:', text.slice(0, 200), '...');
+  console.log('Routing Metadata:', JSON.stringify(metadata, null, 2));
+}
+
+// ============================================================
+// Example 3: Ensemble Mode (Parallel Execution)
+// ============================================================
+
+async function exampleEnsemble() {
+  console.log('\n=== Example 3: Ensemble Mode (Parallel Execution) ===\n');
+
+  const llm = new A3MLLM({
+    providers: {
+      groq: {
+        ...A3M_DEFAULT_PROVIDERS.groq,
+        apiKey: process.env.GROQ_API_KEY,
+      },
+      openai: {
+        ...A3M_DEFAULT_PROVIDERS.openai,
+        apiKey: process.env.OPENAI_API_KEY,
+      },
+    },
+    routingStrategy: 'priority',
+    priorityOrder: ['groq', 'openai'],
+  });
+
+  // Run both providers in parallel, return the longest response
+  const result = await llm.ensembleInvoke(
+    'Write a haiku about artificial intelligence.',
+    {
+      ensemble: 'longest',
+    },
+  );
+
+  console.log('Merged Response:', result.text);
+  console.log('Ensemble Metadata:', JSON.stringify(result.metadata, null, 2));
+}
+
+// ============================================================
+// Example 4: LangChain Chain Integration
+// ============================================================
+
+import { PromptTemplate } from '@langchain/core/prompts';
+import { StringOutputParser } from '@langchain/core/output_parsers';
+
+async function exampleChain() {
+  console.log('\n=== Example 4: LangChain Chain Integration ===\n');
+
+  const llm = new A3MLLM({
+    providers: {
+      groq: {
+        ...A3M_DEFAULT_PROVIDERS.groq,
+        apiKey: process.env.GROQ_API_KEY,
+      },
+    },
+    temperature: 0.7,
+  });
+
+  // Create a chain with prompt template
+  const prompt = PromptTemplate.fromTemplate(
+    'You are a {role}. Answer the following question:\n{question}',
+  );
+
+  // Chain: prompt → LLM → string output parser
+  const chain = prompt.pipe(llm as any).pipe(new StringOutputParser());
+
+  const response = await chain.invoke({
+    role: 'physics professor',
+    question: 'Why is the sky blue?',
+  });
+
+  console.log('Chain Response:', response);
+}
+
+// ============================================================
+// Example 5: Custom Provider Configuration
+// ============================================================
+
+async function exampleCustomProvider() {
+  console.log('\n=== Example 5: Custom Provider Configuration ===\n');
+
+  const llm = new A3MLLM({
+    providers: {
+      ollama: {
+        name: 'Ollama Local',
+        baseUrl: 'http://127.0.0.1:11434/v1/chat/completions',
+        models: ['llama3', 'mistral'],
+        tier: 'free',
+        cost: { input: 0, output: 0 },
+      },
+      lmstudio: {
+        name: 'LM Studio',
+        baseUrl: 'http://127.0.0.1:1234/v1/chat/completions',
+        models: ['local-model'],
+        tier: 'free',
+        cost: { input: 0, output: 0 },
+      },
+    },
+    routingStrategy: 'priority',
+    priorityOrder: ['ollama', 'lmstudio'],
+  });
+
+  console.log('Trying local provider...');
+  try {
+    const response = await llm.invoke('Hello, who are you?');
+    console.log('Response:', response);
+  } catch (error) {
+    console.log('Local provider unavailable (expected if Ollama is not running).');
+  }
+}
+
+// ============================================================
+// Example 6: Access Routing Metadata
+// ============================================================
+
+async function exampleMetadata() {
+  console.log('\n=== Example 6: Accessing Routing Metadata ===\n');
+
+  const llm = new A3MLLM({
+    providers: {
+      groq: {
+        ...A3M_DEFAULT_PROVIDERS.groq,
+        apiKey: process.env.GROQ_API_KEY,
+      },
+    },
+    onRoute: (info) => {
+      console.log(`Routing to: ${info.provider} → ${info.model}`);
+    },
+  });
+
+  // Use invokeWithMetadata to get full routing info
+  const { text, metadata } = await llm.invokeWithMetadata(
+    'What is 2 + 2?',
+  );
+
+  console.log('Response:', text);
+  console.log('--- Routing Metadata ---');
+  console.log(`Provider:     ${metadata.provider}`);
+  console.log(`Model:        ${metadata.model}`);
+  console.log(`Latency:      ${metadata.latencyMs}ms`);
+  console.log(`Cost:         $${metadata.costUsd}`);
+  console.log(`Tier:         ${metadata.tier}`);
+  console.log(`Ensemble:     ${metadata.ensemble}`);
+  if (metadata.tokensUsed) {
+    console.log(`Tokens Used:  ${metadata.tokensUsed.total} (${metadata.tokensUsed.input} in / ${metadata.tokensUsed.output} out)`);
+  }
+}
+
+// ============================================================
+// Example 7: Factory Function (Quick Start)
+// ============================================================
+
+import { createA3MProvider, createA3MRouter } from './a3m_langchain';
+
+async function exampleFactory() {
+  console.log('\n=== Example 7: Factory Functions ===\n');
+
+  // Quick single-provider LLM
+  const groq = createA3MProvider('groq', {
+    apiKey: process.env.GROQ_API_KEY,
+  });
+  const response1 = await groq.invoke('Say hello!');
+  console.log('Single provider:', response1);
+
+  // Auto-routing across multiple providers
+  const router = createA3MRouter({
+    groq: { apiKey: process.env.GROQ_API_KEY },
+    nvidia: { apiKey: process.env.NVIDIA_API_KEY },
+  });
+
+  const { text, metadata } = await router.invokeWithMetadata(
+    'What is the speed of light?',
+  );
+  console.log('Auto-routed response:', text.slice(0, 100));
+  console.log('Selected provider:', metadata.provider);
+  console.log('Cost: $' + metadata.costUsd);
+}
+
+// ============================================================
+// Run All Examples
+// ============================================================
+
+async function main() {
+  console.log('A3M Router — LangChain Integration Examples');
+  console.log('==========================================');
+  console.log('Requires at least one API key (GROQ_API_KEY, OPENAI_API_KEY, etc.)');
+
+  try {
+    // Run examples that don't require API keys first
+    // (they'll error gracefully if no provider is available)
+
+    // Example 5 (custom) runs even without external API keys
+    if (process.env.GROQ_API_KEY) {
+      await exampleBasic();
+      await exampleMultiProvider();
+      await exampleChain();
+      await exampleMetadata();
+      await exampleFactory();
+    }
+
+    if (process.env.GROQ_API_KEY && process.env.OPENAI_API_KEY) {
+      await exampleEnsemble();
+    }
+
+    await exampleCustomProvider();
+  } catch (error) {
+    console.error('Example failed:', error);
+  }
+
+  console.log('\nDone!');
+}
+
+// Run if executed directly
+if (require.main === module) {
+  main().catch(console.error);
+}

package/integrations/vercel-ai-sdk/README.md

@@ -0,0 +1,49 @@
+# A3M Router x Vercel AI SDK
+
+Use A3M Router's smart routing with Vercel AI SDK's `generateText` and `streamText`.
+
+## Install
+
+```bash
+npm install ai adaptive-memory-multi-model-router
+```
+
+## Quick Start
+
+```typescript
+import { createA3M } from './a3m_provider';
+import { generateText } from 'ai';
+
+const a3m = createA3M({ strategy: 'cheapest' });
+
+const result = await generateText({
+  model: a3m('auto'),
+  prompt: 'Hello!',
+});
+```
+
+## Strategies
+
+| Strategy  | Behavior                          |
+| --------- | --------------------------------- |
+| `cheapest`| Routes to lowest-cost provider    |
+| `fastest` | Routes to lowest-latency provider |
+| `auto`    | Balances cost and quality         |
+
+## Configuration
+
+- `A3M_API_KEY` env variable or pass in constructor
+- Point to self-hosted proxy via `baseUrl`
+
+```typescript
+const a3m = createA3M({
+  strategy: 'fastest',
+  baseUrl: 'http://localhost:8787/v1',
+  apiKey: 'my-key',
+});
+```
+
+## Files
+
+- `a3m_provider.ts` -- the custom provider implementation
+- `example.ts` -- usage example with `generateText` and `streamText`

package/integrations/vercel-ai-sdk/a3m_provider.ts

@@ -0,0 +1,78 @@
+/**
+ * A3M Router — Vercel AI SDK Custom Provider
+ *
+ * A lightweight custom provider that routes through A3M's smart router
+ * using Vercel AI SDK's `generateText` and `streamText`.
+ *
+ * Usage:
+ * ```ts
+ * import { createA3M } from './a3m_provider';
+ * import { generateText } from 'ai';
+ *
+ * const a3m = createA3M({ strategy: 'cheapest' });
+ * const result = await generateText({
+ *   model: a3m('auto'),
+ *   prompt: 'Hello'
+ * });
+ * ```
+ */
+
+interface A3MConfig {
+  strategy?: 'cheapest' | 'fastest' | 'auto';
+  apiKey?: string;
+  baseUrl?: string;
+}
+
+interface A3MProvider {
+  (modelId: string): {
+    specVersion: 'v1';
+    provider: string;
+    modelId: string;
+    defaultObjectGenerationMode: 'object';
+    supportsStructuredOutputs: boolean;
+    doGenerate: (options: any) => Promise<any>;
+  };
+}
+
+export function createA3M(config: A3MConfig = {}): A3MProvider {
+  const strategy = config.strategy || 'auto';
+  const baseUrl = config.baseUrl || 'http://localhost:8787/v1';
+
+  return (modelId: string) => ({
+    specVersion: 'v1' as const,
+    provider: 'a3m-router',
+    modelId,
+    defaultObjectGenerationMode: 'object' as const,
+    supportsStructuredOutputs: true,
+
+    async doGenerate(options: any) {
+      const response = await fetch(`${baseUrl}/chat/completions`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${config.apiKey || process.env.A3M_API_KEY || ''}`,
+        },
+        body: JSON.stringify({
+          model: modelId,
+          messages: options.prompt,
+          temperature: options.temperature ?? 0.7,
+          max_tokens: options.maxTokens ?? 2048,
+        }),
+      });
+
+      if (!response.ok) {
+        throw new Error(`A3M: ${response.status} ${await response.text()}`);
+      }
+
+      const data = await response.json();
+      return {
+        text: data.choices?.[0]?.message?.content || '',
+        finishReason: data.choices?.[0]?.finish_reason || 'stop',
+        usage: {
+          promptTokens: data.usage?.prompt_tokens || 0,
+          completionTokens: data.usage?.completion_tokens || 0,
+        },
+      };
+    },
+  });
+}

package/integrations/vercel-ai-sdk/example.ts

@@ -0,0 +1,25 @@
+import { createA3M } from './a3m_provider';
+import { generateText, streamText } from 'ai';
+
+// Quick route (cheapest provider)
+const a3m = createA3M({ strategy: 'cheapest' });
+
+async function main() {
+  // Non-streaming
+  const result = await generateText({
+    model: a3m('auto'),
+    prompt: 'Explain quantum computing in one sentence',
+  });
+  console.log(result.text);
+
+  // Streaming
+  const stream = await streamText({
+    model: a3m('auto'),
+    prompt: 'Write a haiku about AI routing',
+  });
+  for await (const chunk of stream.textStream) {
+    process.stdout.write(chunk);
+  }
+}
+
+main().catch(console.error);

package/llms-full.txt

@@ -182,3 +182,46 @@ npx adaptive-memory-multi-model-router
 # Quick start: docs/QUICK_START.md
 # Benchmarks: docs/BENCHMARK.md
 ```
+
+## Additional Resources
+
+### Docs
+- [BENCHMARK.md](./docs/BENCHMARK.md) — Independent benchmark data
+- [API.md](./docs/API.md) — API reference
+- [CORE_VISION_PRD.md](./docs/CORE_VISION_PRD.md) — Product requirements
+- [CONFIGURATION.md](./docs/CONFIGURATION.md) — Configuration reference
+- [ENGINEERING_SPEC.md](./docs/ENGINEERING_SPEC.md) — Engineering specification
+- [INTEGRATIONS.md](./docs/INTEGRATIONS.md) — Integration guide
+- [QUICK_START.md](./docs/QUICK_START.md) — Quick start guide
+- [ARCHITECTURAL-IMPROVEMENTS.md](./docs/ARCHITECTURAL-IMPROVEMENTS-2025.md) — Architecture docs
+
+### Integrations
+- [LangChain](./integrations/langchain/) — LangChain integration adapter
+- [Vercel AI SDK](./integrations/vercel-ai-sdk/) — Vercel AI SDK integration (use with @ai-sdk packages)
+
+### Servers & Tools
+- [MCP Server](./mcp-server/) — Model Context Protocol server
+- [Demo](./demo/) — Interactive demo application
+- [Proxy](./proxy/) — OpenAI-compatible proxy server
+
+### Community
+- [GitHub Discussions](https://github.com/Das-rebel/a3m-router/discussions) — Community Q&A, ideas, and show-and-tell
+
+### Documentation Site
+- [GitHub Pages](https://das-rebel.github.io/A3M-Router-Parallel-multi-LLM-Gateway/) — Full documentation website
+- [Benchmark Results](https://das-rebel.github.io/A3M-Router-Parallel-multi-LLM-Gateway/benchmark) — Independent benchmark data
+- [Quick Start](https://das-rebel.github.io/A3M-Router-Parallel-multi-LLM-Gateway/quick-start) — Getting started guide
+- [API Reference](https://das-rebel.github.io/A3M-Router-Parallel-multi-LLM-Gateway/api) — SDK and CLI reference
+
+### Docs
+- [ARCHITECTURE.md](./ARCHITECTURE.md) — Codebase architecture
+- [CHANGELOG.md](./CHANGELOG.md) — Version history
+- [docs/comparison.md](./docs/comparison.md) — Competitor comparison
+- [docs/cli-cheatsheet.md](./docs/cli-cheatsheet.md) — CLI quick reference
+- [docs/curl-examples.md](./docs/curl-examples.md) — One-liner curl examples
+- [docs/openapi.yaml](./docs/openapi.yaml) — OpenAPI specification
+- [docs/BENCHMARK.md](./docs/BENCHMARK.md) — Detailed benchmark data
+
+### Deployments
+- [Docker](https://github.com/Das-rebel/a3m-router) — Multi-stage Dockerfile and docker-compose
+- [npm](https://www.npmjs.com/package/adaptive-memory-multi-model-router) — npm package (install: npm install -g adaptive-memory-multi-model-router)

package/llms.txt

@@ -52,3 +52,12 @@ Parallel ensemble execution: runs N providers simultaneously, scores results on
 - 10,024 npm downloads in 14 days
 - 72 versions published
 - Zero marketing budget
+
+## Links
+- Docs: `docs/` ([BENCHMARK.md](./docs/BENCHMARK.md), [API.md](./docs/API.md), [ARCHITECTURAL-IMPROVEMENTS.md](./docs/ARCHITECTURAL-IMPROVEMENTS-2025.md), [CORE_VISION_PRD.md](./docs/CORE_VISION_PRD.md), [CONFIGURATION.md](./docs/CONFIGURATION.md), [ENGINEERING_SPEC.md](./docs/ENGINEERING_SPEC.md), [INTEGRATIONS.md](./docs/INTEGRATIONS.md), [QUICK_START.md](./docs/QUICK_START.md))
+- Integration: LangChain (`integrations/langchain/`)
+- Integration: Vercel AI SDK (`integrations/vercel-ai-sdk/`)
+- MCP Server: `mcp-server/`
+- Demo: `demo/`
+- Proxy: `proxy/`
+- Community: [GitHub Discussions](https://github.com/Das-rebel/a3m-router/discussions)

package/mcp-server/README.md

@@ -0,0 +1,188 @@
+# A3M Router MCP Server
+
+MCP (Model Context Protocol) server for [A3M Router](https://github.com/Das-rebel/a3m-router) — parallel multi-LLM execution for AI agents.
+
+Allows any MCP-compatible AI agent (Claude Code, Cursor, Windsurf, etc.) to use A3M's routing and ensemble execution directly.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `a3m_route` | Route a query to the optimal LLM provider (model selection + reasoning, no execution) |
+| `a3m_ensemble` | Execute a query across multiple providers in parallel and merge results |
+| `a3m_classify` | Classify a query by type (fast/creative/deep/code) and get provider recommendations |
+| `a3m_providers` | List all configured providers with models, cost, and availability |
+
+## Installation
+
+```bash
+# Install globally
+npm install -g @a3m/mcp-server
+
+# Or from the repo
+cd mcp-server
+npm install
+```
+
+## Configuration
+
+Set API keys as environment variables for the providers you want to use:
+
+```bash
+# Required for at least one provider
+export GROQ_API_KEY=gsk_...
+export GOOGLE_API_KEY=AIza...
+export CEREBRAS_API_KEY=csk-...
+export MISTRAL_API_KEY=...
+export MINIMAX_API_KEY=...
+
+# Optional: Custom A3M config
+export A3M_CONFIG_PATH=~/.config/a3m-router/providers.json
+```
+
+## Usage
+
+### Claude Code
+
+Add to your `~/.claude.json` or project `.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "a3m-router": {
+      "command": "npx",
+      "args": ["@a3m/mcp-server"],
+      "env": {
+        "GROQ_API_KEY": "gsk_...",
+        "GOOGLE_API_KEY": "AIza..."
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+In Cursor Settings -> Features -> MCP Servers, add:
+
+```
+Name: A3M Router
+Type: command
+Command: npx @a3m/mcp-server
+```
+
+### Direct MCP Client
+
+```bash
+# Start the server
+npx @a3m/mcp-server
+
+# Pipe stdin/stdout for MCP protocol
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | npx @a3m/mcp-server
+```
+
+### Testing the Server
+
+```bash
+# Clone and install
+git clone https://github.com/Das-rebel/a3m-router.git
+cd a3m-router/mcp-server
+npm install
+npx tsc
+
+# Run directly (pipe test)
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js
+
+# Or use the MCP inspector
+npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+## Examples
+
+### Route a query
+
+```
+Tool: a3m_route
+Input: { "query": "Write a Python function to sort a list" }
+Output:
+{
+  "model": "groq/llama-3.3-70b-versatile",
+  "tier": "cheap",
+  "provider": "groq",
+  "confidence": 0.85,
+  "reasoning": "Code query detected, routing to fast coding provider",
+  "estimated_cost": 0.000012,
+  "classification": "code"
+}
+```
+
+### Ensemble execution
+
+```
+Tool: a3m_ensemble
+Input: { "query": "Explain quantum computing in 3 sentences" }
+Output:
+{
+  "query": "Explain quantum computing in 3 sentences",
+  "parallel_responses": [
+    { "provider": "groq", "confidence": 0.92, "content": "..." },
+    { "provider": "google", "confidence": 0.88, "content": "..." },
+    { "provider": "cerebras", "confidence": 0.85, "content": "..." }
+  ],
+  "best_answer": "...",
+  "stats": {
+    "total_providers": 4,
+    "successful": 3,
+    "failed": 1,
+    "total_cost": 0.000031
+  }
+}
+```
+
+## Protocol
+
+The server uses standard MCP transport via stdio:
+
+```
+Client -> Server: JSON-RPC request (stdin)
+Server -> Client: JSON-RPC response (stdout)
+Server -> Stderr: Logs (for debugging)
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│             MCP Client (Claude Code, Cursor)     │
+└──────────────────┬──────────────────────────────┘
+                   │ MCP Protocol (stdio)
+┌──────────────────▼──────────────────────────────┐
+│           A3M MCP Server (mcp-server)            │
+│                                                   │
+│  a3m_route   a3m_ensemble   a3m_classify  providers│
+└──────────────────┬──────────────────────────────┘
+                   │ Internal API
+┌──────────────────▼──────────────────────────────┐
+│        A3M Router (adaptive-memory-multi-        │
+│           model-router)                          │
+│                                                   │
+│  routeQuery()  extractQueryFeatures()  providers  │
+└───────┬────────────┬────────────┬────────────────┘
+        │            │            │
+   ┌────▼───┐  ┌────▼───┐  ┌────▼───┐
+   │  Groq  │  │ Google │  │Cerebras│  ...
+   └────────┘  └────────┘  └────────┘
+```
+
+## Development
+
+```bash
+cd mcp-server
+npm install
+npm run build    # npx tsc
+npm start        # node dist/index.js
+```
+
+## License
+
+MIT