adaptive-memory-multi-model-router 2.15.4 → 2.15.5

package/packages/agentkit-adapter/src/index.ts

@@ -0,0 +1,36 @@
+/**
+ * A3M Router AgentKit Adapter
+ * 
+ * @example
+ * ```typescript
+ * import { createAgenticModelFromAiAdapter } from "@inngest/agent-kit";
+ * import { createA3MAdapter } from "@a3m/agentkit-adapter";
+ * 
+ * // Create A3M adapter
+ * const a3m = createA3MAdapter({
+ *   baseUrl: "http://localhost:8787",
+ *   parallel: true,  // Enable parallel ensemble mode
+ * });
+ * 
+ * // Wrap as AgentKit model
+ * const model = createAgenticModelFromAiAdapter(a3m as unknown as AiAdapter.Any);
+ * 
+ * // Use with AgentKit agent
+ * const agent = new Agent({
+ *   model,
+ *   tools: [/* your tools *\/],
+ * });
+ * ```
+ */
+
+export { A3MAdapter, createA3MAdapter } from "./adapter";
+export type {
+  A3MConfig,
+  A3MInferenceOptions,
+  A3MMessage,
+  A3MTool,
+  A3MToolCall,
+  A3MStreamChunk,
+  A3MResponse,
+  ToolChoice,
+} from "./types";

package/packages/agentkit-adapter/src/types.ts

@@ -0,0 +1,105 @@
+/**
+ * Types for A3M Router AgentKit Adapter
+ */
+
+import { z } from "zod";
+
+/**
+ * Configuration for A3M Router
+ */
+export interface A3MConfig {
+  /** A3M Router base URL (default: http://localhost:8787) */
+  baseUrl?: string;
+  /** API key for A3M Router (if required) */
+  apiKey?: string;
+  /** Default model to use (optional - A3M will route automatically) */
+  defaultModel?: string;
+  /** Enable parallel ensemble mode */
+  parallel?: boolean;
+  /** Temperature for generation (0-2) */
+  temperature?: number;
+  /** Maximum tokens to generate */
+  maxTokens?: number;
+  /** Additional headers to send with each request */
+  headers?: Record<string, string>;
+}
+
+/**
+ * A3M-specific options for inference
+ */
+export interface A3MInferenceOptions {
+  /** Override the model for this call */
+  model?: string;
+  /** Enable parallel ensemble for this call */
+  parallel?: boolean;
+  /** Temperature (0-2) */
+  temperature?: number;
+  /** Maximum tokens */
+  maxTokens?: number;
+  /** Provider to use (bypass routing) */
+  provider?: string;
+  /** Stop sequences */
+  stop?: string[];
+  /** Retry on failure */
+  retry?: boolean;
+}
+
+/**
+ * Message format compatible with AgentKit
+ */
+export interface A3MMessage {
+  role: "user" | "assistant" | "system" | "tool";
+  content: string;
+  name?: string;
+  toolCallId?: string;
+}
+
+/**
+ * Tool call format for A3M
+ */
+export interface A3MToolCall {
+  id: string;
+  name: string;
+  arguments: Record<string, unknown>;
+}
+
+/**
+ * Tool definition for A3M
+ */
+export interface A3MTool {
+  name: string;
+  description: string;
+  parameters?: z.ZodType<unknown>;
+  strict?: boolean;
+}
+
+/**
+ * Streaming chunk from A3M
+ */
+export interface A3MStreamChunk {
+  type: "text" | "tool_call" | "done" | "error";
+  content?: string;
+  toolCall?: A3MToolCall;
+  error?: string;
+}
+
+/**
+ * Response from A3M inference
+ */
+export interface A3MResponse {
+  content: string;
+  toolCalls?: A3MToolCall[];
+  model?: string;
+  provider?: string;
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+  finishReason?: "stop" | "length" | "tool_calls" | "content_filter";
+}
+
+/**
+ * Tool choice options
+ */
+export type ToolChoice = "auto" | "none" | { type: "function"; function: { name: string } };

package/packages/agentkit-adapter/src/util.ts

@@ -0,0 +1,13 @@
+/**
+ * Utility functions
+ */
+
+export const stringifyError = (err: unknown): string => {
+  if (err instanceof Error) {
+    return err.message;
+  }
+  if (typeof err === "string") {
+    return err;
+  }
+  return JSON.stringify(err);
+};

package/packages/agentkit-adapter/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": false
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "examples"]
+}

package/prometheus.yml

@@ -0,0 +1,8 @@
+global:
+  scrape_interval: 15s
+
+scrape_configs:
+  - job_name: 'a3m-router'
+    static_configs:
+      - targets: ['a3m-router:8787']
+    metrics_path: /metrics

package/python/README.md

@@ -1,101 +1,128 @@
 # A3M Router Python SDK
 
-Python SDK for the A3M Router — an intelligent LLM routing proxy that selects the best model for each query based on complexity, cost, and capability.
+**Intelligent LLM routing — auto-selects the cheapest capable model from 47+ providers.**
 
-## Install
+Routes queries to the best model for your needs — whether it's Groq for simple Q&A ($0.001/1K) or GPT-4o for complex reasoning ($0.15/1K).
+
+## Installation
 
 ```bash
 pip install a3m-router
 ```
 
-Requires Python 3.8+. Only dependency: `httpx`.
-
 ## Quick Start
 
-### Async Client (recommended)
-
 ```python
-import asyncio
 from a3m import A3MRouter
 
-async def main():
-    async with A3MRouter() as router:
-        # Chat with automatic model routing
-        response = await router.chat("What is 2+2?")
-        print(response["choices"][0]["message"]["content"])
+router = A3MRouter(base_url="http://localhost:8787")
+
+# Auto-routes to optimal provider
+response = await router.chat("What is 2+2?")
+# → Routes to Groq, costs ~$0.000001
 
-        # Check routing decision without executing
-        decision = await router.route("Write a Python web scraper")
-        print(decision)  # RoutingDecision(model=groq/llama-3.3-70b, tier=cheap, cost=$0.000000, complexity=0.35)
+# See routing decision before executing
+decision = await router.route("Explain quantum computing")
+print(f"Model: {decision.model}")
+print(f"Tier: {decision.tier}")
+print(f"Cost: ${decision.cost:.6f}")
 
-        # Stream a response
-        async for token in router.stream_chat("Tell me a joke"):
-            print(token, end="", flush=True)
+# Stream responses
+async for token in router.stream_chat("Tell me a story"):
+    print(token, end="", flush=True)
+```
+
+## Key Features
 
-        # List available models
-        models = await router.models()
+- **Auto-routing**: Picks the right model based on query complexity, budget, and requirements
+- **Cost savings**: 70-95% cheaper than always using premium models
+- **47+ providers**: Groq, DeepSeek, GPT-4o, Claude, Mistral, and more
+- **Framework adapters**: Drop-in for LangChain, LlamaIndex, Qdrant, Weaviate
+- **Health monitoring**: Check provider status and availability
+- **Cost analytics**: Track spending and savings
 
-        # Get cost analytics
-        report = await router.cost_report()
-        print(f"Total requests: {report.total_requests}")
-        print(f"Savings: {report.savings_percentage:.1f}%")
+## Framework Adapters
 
-asyncio.run(main())
+| Adapter | Use Case | Install |
+|---------|----------|---------|
+| **LangChain** | Chain-based AI workflows | `pip install a3m-router[langchain]` |
+| **LlamaIndex** | RAG and document QA | `pip install a3m-router[llamaindex]` |
+| **Qdrant** | Vector search + RAG | `pip install a3m-router[qdrant]` |
+| **Weaviate** | Vector search + RAG | `pip install a3m-router[weaviate]` |
+
+All adapters:
+```bash
+pip install a3m-router[all]
 ```
 
-### Sync Client
+## Routing Tiers
 
-```python
-from a3m.sync_client import A3MRouterSync
+| Tier | Providers | Cost | When Used |
+|------|-----------|------|-----------|
+| **free** | Ollama, vLLM | $0 | Local inference |
+| **cheap** | Groq, DeepSeek | ~$0.001/1K | Simple Q&A, short code |
+| **mid** | GPT-4o-mini, Claude-haiku | ~$0.01/1K | Standard tasks |
+| **premium** | GPT-4o, Claude-sonnet | ~$0.15/1K | Complex reasoning |
+
+## API Reference
 
-with A3MRouterSync() as router:
-    response = router.chat("What is 2+2?")
-    print(response["choices"][0]["message"]["content"])
+### A3MRouter
 
-    decision = router.route("Explain quantum computing")
-    print(f"Routed to {decision.model} (tier={decision.tier}, cost=${decision.cost:.6f})")
+```python
+router = A3MRouter(
+    base_url="http://localhost:8787",  # A3M Router server URL
+    timeout=30.0,                       # Request timeout
+)
 ```
 
-### With OpenAI SDK
+| Method | Description |
+|--------|-------------|
+| `chat(message)` | Send chat message with auto-routing |
+| `route(query)` | Get routing decision (no execution) |
+| `route_batch(queries)` | Route multiple queries |
+| `stream_chat(message)` | Stream response tokens |
+| `models()` | List all available models |
+| `health()` | Provider health status |
+| `cost_report()` | Cost analytics |
+
+### LangChain Example
+
+```python
+from a3m import LangChainAdapter
+from langchain.schema import HumanMessage
+
+llm = LangChainAdapter(base_url="http://localhost:8787")
+response = llm([HumanMessage(content="What is RAG?")])
+```
 
-The router is OpenAI-compatible, so you can use the standard OpenAI SDK:
+### LlamaIndex Example
 
 ```python
-from openai import AsyncOpenAI
+from a3m import LlamaIndexAdapter
 
-client = AsyncOpenAI(base_url="http://localhost:8787/v1", api_key="not-needed")
-response = await client.chat.completions.create(
-    model="auto",
-    messages=[{"role": "user", "content": "Hello"}]
-)
+llm = LlamaIndexAdapter()
+response = llm.complete("Explain transformers")
 ```
 
-## API Reference
+## Server Setup
 
-### A3MRouter (async)
+Start the A3M Router server:
 
-| Method | Description |
-|--------|-------------|
-| `chat(message, model="auto", max_tokens=100, temperature=0.7, system=None)` | Send a chat message with automatic routing |
-| `route(query)` | Get routing decision without executing |
-| `route_batch(queries)` | Route multiple queries |
-| `stream_chat(message, model="auto", max_tokens=100)` | Stream response tokens |
-| `models()` | List available models |
-| `health()` | Check router health |
-| `cost_report()` | Get cost analytics |
-
-### RoutingDecision
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `model` | str | Selected model name |
-| `tier` | str | Cost tier (free/cheap/mid/premium) |
-| `cost` | float | Estimated cost per request |
-| `complexity` | float | Query complexity score (0-1) |
-| `reasoning` | str | Why this model was chosen |
-| `fallback_models` | list | Alternative models if primary fails |
-| `is_free` | bool | Property — True if cost is $0 |
-| `is_expert` | bool | Property — True if complexity >= 0.65 |
+```bash
+# Via npm
+npx a3m-router serve
+
+# Via Docker
+docker-compose up -d
+```
+
+Server runs on `http://localhost:8787` by default.
+
+## Links
+
+- **GitHub**: https://github.com/Das-rebel/a3m-router
+- **npm Package**: https://www.npmjs.com/package/adaptive-memory-multi-model-router
+- **Documentation**: https://das-rebel.github.io/a3m-router
 
 ## License
 

package/python/a3m/__init__.py

@@ -1,6 +1,35 @@
 """A3M Router Python SDK"""
-from .client import A3MRouter
+from .client import A3MRouter, A3MRouterError
+from .sync_client import A3MRouterSync
 from .models import RoutingDecision, CostReport
 
-__version__ = "2.1.0"
-__all__ = ["A3MRouter", "RoutingDecision", "CostReport"]
+__version__ = "2.2.1"
+
+__all__ = [
+    "A3MRouter",
+    "A3MRouterSync",
+    "A3MRouterError",
+    "RoutingDecision",
+    "CostReport",
+    # Framework adapters
+    "LangChainAdapter",
+    "LlamaIndexAdapter",
+    "QdrantAdapter",
+    "WeaviateAdapter",
+]
+
+# Lazy-load adapters
+def __getattr__(name: str):
+    if name == "LangChainAdapter":
+        from .adapters.langchain import LangChainAdapter
+        return LangChainAdapter
+    if name == "LlamaIndexAdapter":
+        from .adapters.llamaindex import LlamaIndexAdapter
+        return LlamaIndexAdapter
+    if name == "QdrantAdapter":
+        from .adapters.qdrant import QdrantAdapter
+        return QdrantAdapter
+    if name == "WeaviateAdapter":
+        from .adapters.weaviate import WeaviateAdapter
+        return WeaviateAdapter
+    raise AttributeError(f"module 'a3m' has no attribute '{name}'")

package/python/a3m/adapters/__init__.py

@@ -0,0 +1,21 @@
+"""
+A3M Router framework adapters.
+
+Lazy-loaded adapter classes for popular frameworks:
+- LangChain: from a3m.adapters import LangChainAdapter
+- LlamaIndex: from a3m.adapters import LlamaIndexAdapter
+- Qdrant: from a3m.adapters import QdrantAdapter
+- Weaviate: from a3m.adapters import WeaviateAdapter
+"""
+
+from .langchain import LangChainAdapter
+from .llamaindex import LlamaIndexAdapter
+from .qdrant import QdrantAdapter
+from .weaviate import WeaviateAdapter
+
+__all__ = [
+    "LangChainAdapter",
+    "LlamaIndexAdapter", 
+    "QdrantAdapter",
+    "WeaviateAdapter",
+]

package/python/a3m/adapters/langchain.py

@@ -0,0 +1,190 @@
+"""
+A3M Router LangChain adapter.
+
+Drop-in replacement for ChatOpenAI that routes through A3M Router.
+
+Usage:
+    from langchain.chat_models import ChatOpenAI
+    from a3m.adapters import LangChainAdapter
+    
+    # As replacement for ChatOpenAI
+    llm = LangChainAdapter(
+        base_url="http://localhost:8787",
+        model="auto",
+        temperature=0.7,
+    )
+    
+    from langchain.schema import HumanMessage
+    response = llm([HumanMessage(content="What is 2+2?")])
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional, Type
+
+from pydantic import Field
+
+logger = logging.getLogger(__name__)
+
+LANCHAIN_AVAILABLE = False
+try:
+    from langchain.chat_models import BaseChatModel
+    from langchain.schema import (
+        BaseMessage,
+        ChatResult,
+        AIMessage,
+        HumanMessage,
+        SystemMessage,
+    )
+    from langchain.callbacks.manager import CallbackManagerForLLMRun
+    LANCHAIN_AVAILABLE = True
+except ImportError:
+    logger.warning("LangChain not installed. pip install langchain")
+
+from a3m.client import A3MRouter, A3MRouterError
+
+if LANCHAIN_AVAILABLE:
+    class LangChainAdapter(BaseChatModel):
+        """
+        LangChain chat model that routes through A3M Router.
+        
+        Drop-in replacement for ChatOpenAI with automatic model selection.
+        
+        Args:
+            base_url: A3M Router server URL.
+            model: Model name or "auto" for intelligent routing.
+            temperature: Sampling temperature.
+            max_tokens: Max tokens to generate.
+            parallel_ensemble: Number of providers for ensemble calls.
+            **kwargs: Additional A3MRouter options.
+        """
+
+        base_url: str = Field(default="http://localhost:8787")
+        model: str = Field(default="auto")
+        temperature: float = Field(default=0.7)
+        max_tokens: Optional[int] = Field(default=None)
+        parallel_ensemble: int = Field(default=1)
+        api_key: Optional[str] = Field(default=None)
+
+        class Config:
+            arbitrary_types_allowed = True
+
+        def _get_router(self) -> A3MRouter:
+            """Get or create A3M Router client."""
+            if not hasattr(self, "_router"):
+                self._router = A3MRouter(
+                    base_url=self.base_url,
+                    api_key=self.api_key,
+                    default_model=self.model,
+                    default_temperature=self.temperature,
+                    default_max_tokens=self.max_tokens,
+                    parallel_ensemble=self.parallel_ensemble,
+                )
+            return self._router
+
+        def _convert_messages(
+            self,
+            messages: List[BaseMessage],
+        ) -> List[Dict[str, str]]:
+            """Convert LangChain messages to A3M format."""
+            result = []
+            for msg in messages:
+                if isinstance(msg, HumanMessage):
+                    result.append({"role": "user", "content": msg.content})
+                elif isinstance(msg, AIMessage):
+                    result.append({"role": "assistant", "content": msg.content})
+                elif isinstance(msg, SystemMessage):
+                    result.append({"role": "system", "content": msg.content})
+                else:
+                    result.append({"role": "user", "content": str(msg.content)})
+            return result
+
+        def _convert_response(
+            self,
+            response_content: str,
+        ) -> AIMessage:
+            """Convert A3M response to LangChain message."""
+            return AIMessage(content=response_content)
+
+        @property
+        def _llm_type(self) -> str:
+            return "a3m-router"
+
+        def _generate(
+            self,
+            messages: List[BaseMessage],
+            stop: Optional[List[str]] = None,
+            run_manager: Optional[CallbackManagerForLLMRun] = None,
+            **kwargs: Any,
+        ) -> ChatResult:
+            """Generate a chat response."""
+            router = self._get_router()
+            
+            a3m_messages = self._convert_messages(messages)
+            
+            try:
+                response = router.chat(
+                    messages=a3m_messages,
+                    model=self.model,
+                    temperature=self.temperature,
+                    max_tokens=self.max_tokens,
+                    parallel_ensemble=self.parallel_ensemble,
+                    **kwargs,
+                )
+            except A3MRouterError as e:
+                logger.error(f"A3M Router error: {e}")
+                raise
+            
+            return ChatResult(
+                generations=[{"message": self._convert_response(response.content), "text": response.content}],
+                llm_output={
+                    "provider": response.provider,
+                    "model": response.route.model,
+                    "cost": response.cost,
+                    "route": str(response.route),
+                },
+            )
+
+        async def _agenerate(
+            self,
+            messages: List[BaseMessage],
+            stop: Optional[List[str]] = None,
+            run_manager: Optional[CallbackManagerForLLMRun] = None,
+            **kwargs: Any,
+        ) -> ChatResult:
+            """Async generate a chat response."""
+            router = self._get_router()
+            a3m_messages = self._convert_messages(messages)
+            
+            try:
+                response = await router.achat(
+                    messages=a3m_messages,
+                    model=self.model,
+                    temperature=self.temperature,
+                    max_tokens=self.max_tokens,
+                    parallel_ensemble=self.parallel_ensemble,
+                    **kwargs,
+                )
+            except A3MRouterError as e:
+                logger.error(f"A3M Router error: {e}")
+                raise
+            
+            return ChatResult(
+                generations=[{"message": self._convert_response(response.content), "text": response.content}],
+                llm_output={
+                    "provider": response.provider,
+                    "model": response.route.model,
+                    "cost": response.cost,
+                    "route": str(response.route),
+                },
+            )
+
+else:
+    # Stub class when LangChain is not installed
+    class LangChainAdapter:
+        def __init__(self, *args: Any, **kwargs: Any) -> None:
+            raise ImportError(
+                "LangChain is not installed. "
+                "Install with: pip install langchain"
+            )