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

package/adapters/README.md

@@ -0,0 +1,36 @@
+# A3M Router Adapters
+
+Drop-in adapters for LangChain and LlamaIndex to integrate with A3M Router for intelligent model routing.
+
+## Installation
+
+```bash
+pip install a3m_adapter
+```
+
+Or install with extras:
+
+```bash
+pip install a3m_adapter[langchain]  # With LangChain support
+pip install a3m_adapter[llamaindex]  # With LlamaIndex support
+```
+
+## Usage
+
+### LangChain
+
+```python
+from a3m_adapter import A3MLangChainAdapter
+
+llm = A3MLangChainAdapter(model="auto", temperature=0.7)
+result = llm.invoke("What is the capital of France?")
+```
+
+### LlamaIndex
+
+```python
+from a3m_adapter import A3MLlamaIndexAdapter
+
+llm = A3MLlamaIndexAdapter(model="auto")
+response = llm.complete("What is the capital of France?")
+```

package/adapters/__init__.py

@@ -0,0 +1,25 @@
+"""
+A3M Router Adapter Package
+
+This package provides drop-in adapters to integrate A3M Router
+with popular LLM frameworks including LangChain, LlamaIndex, and more.
+
+Usage:
+    from adapters import A3MLangChainAdapter, A3MLlamaIndexAdapter, A3MConfig
+    
+    # LangChain
+    llm = A3MLangChainAdapter(model="auto", temperature=0.7)
+    
+    # LlamaIndex
+    llm = A3MLlamaIndexAdapter(model="auto")
+    
+    # Configuration
+    config = A3MConfig(model="auto", parallel_ensemble=2)
+"""
+
+from .a3m_adapter.adapter.langchain import A3MLangChainAdapter
+from .a3m_adapter.adapter.llamaindex import A3MLlamaIndexAdapter
+from .a3m_adapter.adapter.config import A3MConfig
+
+__all__ = ['A3MLangChainAdapter', 'A3MLlamaIndexAdapter', 'A3MConfig']
+__version__ = '1.0.0'

package/adapters/a3m_adapter/__init__.py

@@ -0,0 +1,15 @@
+"""
+A3M Router Adapters for LLM Frameworks.
+
+Provides drop-in adapters for:
+- LangChain (A3MLangChainAdapter)
+- LlamaIndex (A3MLlamaIndexAdapter)
+- Configuration management (A3MConfig)
+"""
+
+from .adapter.langchain import A3MLangChainAdapter
+from .adapter.llamaindex import A3MLlamaIndexAdapter
+from .adapter.config import A3MConfig
+
+__all__ = ['A3MLangChainAdapter', 'A3MLlamaIndexAdapter', 'A3MConfig']
+__version__ = '1.0.0'

package/adapters/a3m_adapter/adapter/__init__.py

@@ -0,0 +1,7 @@
+"""A3M Router adapter implementations."""
+
+from .langchain import A3MLangChainAdapter
+from .llamaindex import A3MLlamaIndexAdapter
+from .config import A3MConfig
+
+__all__ = ['A3MLangChainAdapter', 'A3MLlamaIndexAdapter', 'A3MConfig']

package/adapters/a3m_adapter/adapter/config.py

@@ -0,0 +1,100 @@
+"""
+Configuration management for A3M Router adapters.
+
+Provides settings for:
+- Default model selection strategy
+- Cost optimization thresholds
+- Parallel ensemble settings
+- Provider priority lists
+
+Usage:
+    from a3m_adapter_config import A3MConfig
+    
+    config = A3MConfig.from_file("a3m_config.yaml")
+    llm = A3MChatModel(**config.to_dict())
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass, field, asdict
+from typing import Any, Dict, List, Optional, Union
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class A3MConfig:
+    """Configuration for A3M Router adapters."""
+
+    # Model selection
+    model: str = "auto"
+    
+    # Sampling parameters
+    temperature: float = 0.0
+    max_tokens: Optional[int] = 4096
+    top_p: float = 1.0
+    frequency_penalty: float = 0.0
+    presence_penalty: float = 0.0
+
+    # Routing strategy
+    parallel_ensemble: int = 1
+    fallback_enabled: bool = True
+    cost_threshold: float = 0.05  # Max $ per 1k tokens
+    
+    # Provider preferences (highest priority first)
+    preferred_providers: List[str] = field(default_factory=lambda: [
+        "openai", "anthropic", "google", "azure_openai", 
+        "azure_ais", "litellm", "groq", "together"
+    ])
+    
+    # Excluded providers (never use)
+    excluded_providers: List[str] = field(default_factory=lambda: [])
+    
+    # API configuration
+    api_endpoint: str = "http://localhost:8787/v1"
+    api_key: Optional[str] = None
+
+    # Budget controls
+    monthly_budget_usd: Optional[float] = None
+    daily_budget_usd: Optional[float] = None
+
+    @classmethod
+    def from_file(cls, path: str) -> "A3MConfig":
+        """Load configuration from YAML file."""
+        try:
+            import yaml
+            with open(path, 'r') as f:
+                data = yaml.safe_load(f)
+            return cls(**data)
+        except ImportError:
+            logger.warning("PyYAML not installed, using JSON")
+            return cls.from_json(path)
+
+    @classmethod
+    def from_json(cls, path: str) -> "A3MConfig":
+        """Load configuration from JSON file."""
+        with open(path, 'r') as f:
+            data = json.load(f)
+        return cls(**data)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return asdict(self)
+
+    def to_json(self, path: Optional[str] = None) -> Optional[str]:
+        """Convert to JSON string or save to file."""
+        data = json.dumps(self.to_dict(), indent=2)
+        if path:
+            with open(path, 'w') as f:
+                f.write(data)
+        return data
+
+    def update_budget_limits(self, remaining_usd: float) -> None:
+        """Update budget limits based on remaining funds."""
+        if self.daily_budget_usd is not None:
+            remaining_pct = remaining_usd / self.daily_budget_usd
+            if remaining_pct < 0.1:
+                logger.warning("Low daily budget: %s remaining", remaining_usd)
+                self.parallel_ensemble = 1  # Reduce to single-provider

package/adapters/a3m_adapter/adapter/langchain.py

@@ -0,0 +1,155 @@
+"""
+A3M Router Adapter for LangChain.
+
+Drop-in replacement for LangChain's ChatOpenAI that routes through A3M Router
+for intelligent, cost-optimized model selection across 47+ providers.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+# Check availability
+LANGCHAIN_AVAILABLE = False
+try:
+    from langchain_core.language_models import BaseChatModel
+    from langchain_core.messages import AIMessage, BaseMessage, HumanMessage, SystemMessage, ToolMessage
+    from langchain_core.outputs import ChatGeneration, ChatResult, LLMResult
+    LANGCHAIN_AVAILABLE = True
+except ImportError:
+    logger.warning("LangChain not installed. Install with: pip install langchain langchain-core")
+
+A3M_AVAILABLE = False
+try:
+    from a3m.router import A3MRouter, RouteResponse
+    A3M_AVAILABLE = True
+except ImportError:
+    logger.warning("A3M Router not installed. Install with: pip install adaptive-memory-multi-model-router")
+
+
+class A3MLangChainAdapter:
+    """
+    A3M Router adapter for LangChain's ChatOpenAI interface.
+
+    Routes prompts through A3M Router to automatically select the cheapest
+    capable model across 47+ LLM providers.
+    """
+
+    def __init__(
+        self,
+        model: str = "auto",
+        temperature: float = 0.0,
+        max_tokens: Optional[int] = 4096,
+        parallel_ensemble: int = 1,
+        api_key: Optional[str] = None,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Initialize A3M Router adapter.
+
+        Args:
+            model: Model name or "auto" for automatic routing
+            temperature: Sampling temperature
+            max_tokens: Maximum tokens to generate
+            parallel_ensemble: Number of providers to run in parallel
+            api_key: A3M API key (optional)
+        """
+        self.model = model
+        self.temperature = temperature
+        self.max_tokens = max_tokens
+        self.parallel_ensemble = parallel_ensemble
+        self.api_key = api_key
+        self._a3m_router = None
+        self._initialized = False
+
+    def _ensure_router(self) -> None:
+        """Lazily initialize the A3M router."""
+        if self._initialized:
+            return
+        
+        if not A3M_AVAILABLE:
+            raise ImportError(
+                "A3M Router is not installed. "
+                "Install with: pip install adaptive-memory-multi-model-router"
+            )
+        
+        self._a3m_router = A3MRouter(
+            model=self.model,
+            temperature=self.temperature,
+            parallel_ensemble=self.parallel_ensemble,
+        )
+        self._initialized = True
+        logger.info(
+            "A3M Router initialized: model=%s, ensemble=%d",
+            self.model,
+            self.parallel_ensemble,
+        )
+
+    @property
+    def _llm_type(self) -> str:
+        return "a3m_router"
+
+    def _generate(
+        self,
+        messages: List[BaseMessage],
+        stop: Optional[List[str]] = None,
+        run_manager: Any = None,
+        **kwargs: Any,
+    ) -> LLMResult:
+        """Generate a response using A3M Router."""
+        self._ensure_router()
+        
+        # Convert messages
+        a3m_messages = self._convert_messages(messages)
+
+        # Route through A3M
+        import asyncio
+        loop = asyncio.get_event_loop()
+        route_result = loop.run_in_executor(
+            None,
+            lambda: self._a3m_router.route(
+                messages=a3m_messages,
+                temperature=self.temperature,
+                max_tokens=self.max_tokens,
+                stop=stop,
+                **kwargs,
+            ),
+        )
+
+        ai_message = AIMessage(content=route_result.content)
+        generation = ChatGeneration(message=ai_message)
+        return LLMResult(generations=[[generation]])
+
+    def _convert_messages(self, messages: List[BaseMessage]) -> List[Dict[str, Any]]:
+        """Convert LangChain messages to A3M format."""
+        a3m_messages = []
+        for msg in messages:
+            if isinstance(msg, SystemMessage):
+                a3m_messages.append({"role": "system", "content": msg.content})
+            elif isinstance(msg, HumanMessage):
+                a3m_messages.append({"role": "user", "content": msg.content})
+            elif isinstance(msg, AIMessage):
+                a3m_messages.append({"role": "assistant", "content": msg.content})
+            elif isinstance(msg, ToolMessage):
+                a3m_messages.append(
+                    {"role": "tool", "content": msg.content, "tool_call_id": msg.tool_call_id}
+                )
+            else:
+                a3m_messages.append({"role": "user", "content": str(msg)})
+        return a3m_messages
+
+    def bind_tools(self, tools: List[Dict[str, Any]], **kwargs: Any) -> "A3MLangChainAdapter":
+        """Bind tools for function calling."""
+        return self
+
+    def __repr__(self) -> str:
+        return (
+            f"A3MLangChainAdapter("
+            f"model={self.model!r}, "
+            f"temperature={self.temperature}, "
+            f"max_tokens={self.max_tokens}, "
+            f"ensemble={self.parallel_ensemble})"
+        )

package/adapters/a3m_adapter/adapter/llamaindex.py

@@ -0,0 +1,162 @@
+"""
+A3M Router Adapter for LlamaIndex.
+
+Drop-in replacement for LlamaIndex's BaseLLM that routes through A3M Router
+for intelligent, cost-optimized model selection.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional, Sequence
+
+logger = logging.getLogger(__name__)
+
+# Check availability
+LLAMAINDEX_AVAILABLE = False
+_llama_metadata_class = None
+try:
+    from llama_index.core.base.llms.base import BaseLLM, CompletionResponse
+    from llama_index.core.base.llms.types import ChatMessage
+    LLAMAINDEX_AVAILABLE = True
+    try:
+        from llama_index.core.base.llms.base import LLMMetadata
+        _llama_metadata_class = LLMMetadata
+    except ImportError:
+        pass
+except ImportError:
+    logger.warning("LlamaIndex not installed. Install with: pip install llama-index")
+
+A3M_AVAILABLE = False
+try:
+    from a3m.router import A3MRouter, RouteResponse
+    A3M_AVAILABLE = True
+except ImportError:
+    logger.warning("A3M Router not installed. Install with: pip install adaptive-memory-multi-model-router")
+
+
+class A3MLlamaIndexAdapter:
+    """
+    A3M Router adapter for LlamaIndex's BaseLLM interface.
+
+    Routes prompts through A3M Router to automatically select the cheapest
+    capable model across 47+ LLM providers.
+    """
+
+    def __init__(
+        self,
+        model: str = "auto",
+        temperature: float = 0.0,
+        max_tokens: Optional[int] = 4096,
+        parallel_ensemble: int = 1,
+        api_key: Optional[str] = None,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Initialize A3M Router adapter.
+        """
+        self.model = model
+        self.temperature = temperature
+        self.max_tokens = max_tokens
+        self.parallel_ensemble = parallel_ensemble
+        self.api_key = api_key
+        self._a3m_router = None
+        self._initialized = False
+
+    def _ensure_router(self) -> None:
+        """Lazily initialize the A3M router."""
+        if self._initialized:
+            return
+        
+        if not A3M_AVAILABLE:
+            raise ImportError(
+                "A3M Router is not installed. "
+                "Install with: pip install adaptive-memory-multi-model-router"
+            )
+        
+        self._a3m_router = A3MRouter(
+            model=self.model,
+            temperature=self.temperature,
+            parallel_ensemble=self.parallel_ensemble,
+        )
+        self._initialized = True
+        logger.info(
+            "A3M Router initialized: model=%s, ensemble=%d",
+            self.model,
+            self.parallel_ensemble,
+        )
+
+    @property
+    def metadata(self) -> Dict[str, Any]:
+        """Return LLM metadata as a dict (framework-agnostic)."""
+        return {
+            "context_window": 128000,
+            "num_output": self.max_tokens or 4096,
+            "model_name": self.model,
+            "is_chat_model": True,
+        }
+
+    def complete(self, prompt: str, **kwargs: Any) -> CompletionResponse:
+        """Complete a prompt using A3M Router."""
+        self._ensure_router()
+        
+        messages = [{"role": "user", "content": prompt}]
+        
+        import asyncio
+        loop = asyncio.get_event_loop()
+        route_result = loop.run_in_executor(
+            None,
+            lambda: self._a3m_router.route(
+                messages=messages,
+                temperature=self.temperature,
+                max_tokens=self.max_tokens,
+                **kwargs,
+            ),
+        )
+        
+        return CompletionResponse(text=route_result.content, raw=route_result)
+
+    def chat(self, messages: Sequence[ChatMessage], **kwargs: Any) -> CompletionResponse:
+        """Chat completion using A3M Router."""
+        self._ensure_router()
+        
+        a3m_messages = self._convert_messages(messages)
+        
+        import asyncio
+        loop = asyncio.get_event_loop()
+        route_result = loop.run_in_executor(
+            None,
+            lambda: self._a3m_router.route(
+                messages=a3m_messages,
+                temperature=self.temperature,
+                max_tokens=self.max_tokens,
+                **kwargs,
+            ),
+        )
+        
+        return CompletionResponse(text=route_result.content, raw=route_result)
+
+    def _convert_messages(self, messages: Sequence[ChatMessage]) -> List[Dict[str, Any]]:
+        """Convert LlamaIndex ChatMessages to A3M format."""
+        a3m_messages = []
+        for msg in messages:
+            role = msg.role.value if hasattr(msg.role, 'value') else str(msg.role).lower()
+            role_map = {
+                "system": "system",
+                "user": "user", 
+                "assistant": "assistant",
+                "tool": "tool",
+                "function": "function",
+            }
+            a3m_role = role_map.get(role, "user")
+            a3m_messages.append({"role": a3m_role, "content": msg.content})
+        return a3m_messages
+
+    def __repr__(self) -> str:
+        return (
+            f"A3MLlamaIndexAdapter("
+            f"model={self.model!r}, "
+            f"temperature={self.temperature}, "
+            f"max_tokens={self.max_tokens}, "
+            f"ensemble={self.parallel_ensemble})"
+        )

package/adapters/a3m_adapter/tests/__init__.py

@@ -0,0 +1 @@
+"""Tests for A3M adapters."""

package/adapters/a3m_adapter/tests/test_adapters.py

@@ -0,0 +1,120 @@
+"""
+Test script for A3M Router adapters.
+
+Tests the LangChain and LlamaIndex adapters to ensure they:
+1. Initialize correctly
+2. Route requests properly
+3. Return expected response types
+4. Handle errors gracefully
+"""
+
+import sys
+import os
+import logging
+
+# Add current directory to path
+sys.path.insert(0, '.')
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+def test_langchain_adapter():
+    """Test LangChain adapter."""
+    print("Testing LangChain adapter...")
+    
+    try:
+        from a3m_llm_adapter import A3MChatModel
+        
+        # Initialize
+        llm = A3MChatModel(model="auto", temperature=0.7)
+        print(f"��✅ Initialized: {llm}")
+        
+        # Test simple generation
+        # Note: This would make actual API calls - we'll skip for now
+        # In a real test, we'd mock the A3M router
+        print("��✅ LangChain adapter structure OK")
+        return True
+        
+    except Exception as e:
+        print(f"��❌ LangChain adapter failed: {e}")
+        return False
+
+def test_llamaindex_adapter():
+    """Test LlamaIndex adapter."""
+    print("Testing LlamaIndex adapter...")
+    
+    try:
+        from a3m_llama_index_adapter import A3MLlamaIndexLLM
+        
+        # Initialize
+        llm = A3MLlamaIndexLLM(model="auto", temperature=0.5)
+        print(f"��✅ Initialized: {llm}")
+        
+        # Check metadata
+        metadata = llm.metadata
+        print(f"��✅ Metadata: {metadata.model_name}, tokens: {metadata.num_output}")
+        return True
+        
+    except Exception as e:
+        print(f"��❌ LlamaIndex adapter failed: {e}")
+        return False
+
+def test_config():
+    """Test configuration."""
+    print("Testing configuration...")
+    
+    try:
+        from a3m_adapter_config import A3MConfig
+        
+        # Test defaults
+        config = A3MConfig()
+        print(f"��✅ Default config: model={config.model}")
+        
+        # Test to_dict
+        data = config.to_dict()
+        assert 'model' in data
+        print("��✅ Config to_dict works")
+        
+        # Test JSON serialization
+        json_str = config.to_json()
+        assert '"model"' in json_str
+        print("��✅ Config JSON serialization works")
+        
+        return True
+        
+    except Exception as e:
+        print(f"��❌ Config test failed: {e}")
+        return False
+
+def main():
+    """Run all tests."""
+    print("=" * 50)
+    print("A3M Router Adapter Tests")
+    print("=" * 50)
+    
+    tests = [
+        test_config,
+        test_langchain_adapter,
+        test_llamaindex_adapter,
+    ]
+    
+    passed = 0
+    total = len(tests)
+    
+    for test in tests:
+        if test():
+            passed += 1
+        print()
+    
+    print("=" * 50)
+    print(f"Results: {passed}/{total} tests passed")
+    
+    if passed == total:
+        print("���🎉 All tests passed!")
+        return 0
+    else:
+        print("��❌ Some tests failed")
+        return 1
+
+if __name__ == "__main__":
+    sys.exit(main())

package/adapters/setup.py

@@ -0,0 +1,23 @@
+from setuptools import setup, find_packages
+import os
+
+setup(
+    name="a3m_adapter",
+    version="1.0.0",
+    description="A3M Router adapters for LangChain, LlamaIndex, and other LLM frameworks",
+    long_description=open("README.md").read() if os.path.exists("README.md") else "",
+    long_description_content_type="text/markdown",
+    author="A3M Team",
+    author_email="hello@a3m.ai",
+    packages=find_packages(),
+    install_requires=[
+        "requests>=2.25.1",
+        "pydantic>=1.9.0",
+    ],
+    extras_require={
+        "langchain": ["langchain>=0.0.365", "langchain-core>=0.0.365"],
+        "llamaindex": ["llama-index>=0.8.0"],
+        "dev": ["pytest>=6.0"],
+    },
+    python_requires=">=3.8",
+)

package/articles/CHINESE_DIRECTORIES.md

@@ -67,12 +67,12 @@ Name: A3M Router
 Tagline: #1 LLM Routing Benchmark — 130× cheaper than GPT-5
 
 Description:
-A3M Router is an open-source LLM routing proxy that ranks #1 on RouterArena (verified by independent benchmark)
+A3M Router is an open-source LLM routing proxy that ranks #1 on RouterArena
 (arXiv:2510.00202) with a 0.9404 / 96.77% at $0.0768 per 1K queries — 130× cheaper
 than GPT-5.
 
 Key Features:
-- #1 on RouterArena (verified by independent benchmark) benchmark (96.77%/19 routers)
+- #1 on RouterArena benchmark (96.77%/19 routers)
 - $0.0768/1K queries — 130× cheaper than GPT-5
 - <1ms routing decision, no GPU required
 - 47+ providers: OpenAI, Anthropic, Groq, Cerebras, DeepSeek, Gemini, Mistral