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

package/python/a3m/adapters/weaviate.py

@@ -0,0 +1,263 @@
+"""
+A3M Router Weaviate adapter.
+
+Enables A3M Router as the embedding layer for Weaviate vector search.
+
+Usage:
+    import weaviate
+    from a3m.adapters import WeaviateAdapter
+    
+    # Create A3M-powered Weaviate client
+    client = WeaviateAdapter(
+        a3m_base_url="http://localhost:8787",
+        weaviate_url="http://localhost:8080",
+    )
+    
+    # Generate embeddings via A3M
+    query_embedding = client.embed_query("What is AI?")
+    
+    # Search Weaviate
+    results = client.query.get("Article", ["title", "content"]).with_near_vector({
+        "vector": query_embedding
+    }).with_limit(5).do()
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+WEAVIATE_AVAILABLE = False
+try:
+    import weaviate
+    from weaviate import Client as WeaviateClient
+    from weaviate.types import NUMBERS
+    WEAVIATE_AVAILABLE = True
+except ImportError:
+    logger.warning("Weaviate client not installed. pip install weaviate-client")
+
+from a3m.client import A3MRouter, A3MRouterError
+
+if WEAVIATE_AVAILABLE:
+    class WeaviateAdapter(WeaviateClient):
+        """
+        Weaviate client wrapper that uses A3M Router for embeddings.
+        
+        Provides intelligent embedding generation for Weaviate's
+        vector search with automatic model selection.
+        
+        Args:
+            a3m_base_url: A3M Router server URL (for embeddings).
+            embed_model: Embedding model ("auto" for A3M selection).
+            weaviate_url: Weaviate server URL.
+            weaviate_client: Existing Weaviate client (for hybrid use).
+            **kwargs: Additional WeaviateClient options.
+        """
+
+        def __init__(
+            self,
+            a3m_base_url: str = "http://localhost:8787",
+            embed_model: str = "auto",
+            weaviate_url: Optional[str] = None,
+            weaviate_client: Optional[WeaviateClient] = None,
+            **kwargs: Any,
+        ) -> None:
+            # Initialize Weaviate client if URL provided
+            if weaviate_client:
+                # Copy internal state from provided client
+                self._connection = weaviate_client._connection
+                self._batch = weaviate_client._batch
+                self._schema = weaviate_client._schema
+            elif weaviate_url:
+                super().__init__(url=weaviate_url, **kwargs)
+            else:
+                # Initialize with empty client for embedding-only use
+                self._connection = None
+                self._batch = None
+                self._schema = None
+            
+            self._a3m_router = A3MRouter(base_url=a3m_base_url, default_model=embed_model)
+            self._embed_model = embed_model
+
+        def embed_query(
+            self,
+            query: str,
+            **kwargs: Any,
+        ) -> List[float]:
+            """
+            Generate embedding for a query string.
+            
+            Args:
+                query: Text to embed.
+                
+            Returns:
+                Embedding vector (list of floats).
+            """
+            try:
+                response = self._a3m_router.embed(texts=[query], model=self._embed_model)
+                return response.embedding
+            except A3MRouterError as e:
+                logger.error(f"A3M Router embedding error: {e}")
+                raise
+
+        def embed_texts(
+            self,
+            texts: List[str],
+            **kwargs: Any,
+        ) -> List[List[float]]:
+            """
+            Generate embeddings for multiple texts.
+            
+            Args:
+                texts: List of texts to embed.
+                
+            Returns:
+                List of embedding vectors.
+            """
+            try:
+                response = self._a3m_router.embed(texts=texts, model=self._embed_model)
+                if isinstance(response, list):
+                    return [r.embedding for r in response]
+                return [response.embedding]
+            except A3MRouterError as e:
+                logger.error(f"A3M Router embedding error: {e}")
+                raise
+
+        def with_near_text(
+            self,
+            query: str,
+            **kwargs: Any,
+        ) -> "WeaviateNearText":
+            """
+            Create a near-text search using A3M embeddings.
+            
+            Args:
+                query: Text to search for.
+                
+            Returns:
+                WeaviateNearText object ready for .do()
+            """
+            embedding = self.embed_query(query)
+            return WeaviateNearText(
+                client=self,
+                text=query,
+                embedding=embedding,
+                **kwargs,
+            )
+
+        def rag_search(
+            self,
+            query: str,
+            class_name: str,
+            properties: List[str],
+            limit: int = 5,
+            **kwargs: Any,
+        ) -> Dict[str, Any]:
+            """
+            Perform RAG search: embed query + Weaviate search + context build.
+            
+            Args:
+                query: User query string.
+                class_name: Weaviate class to search.
+                properties: Properties to return.
+                limit: Number of results.
+                
+            Returns:
+                Dict with 'chunks', 'context', 'answer', 'provider'.
+            """
+            # 1. Embed query via A3M
+            query_embedding = self.embed_query(query)
+            
+            # 2. Search Weaviate
+            try:
+                results = (
+                    self.query
+                    .get(class_name, properties)
+                    .with_near_vector({"vector": query_embedding})
+                    .with_limit(limit)
+                    .do()
+                )
+            except Exception as e:
+                logger.warning(f"Weaviate search error: {e}")
+                results = {"data": {"Get": {class_name: []}}}
+            
+            # 3. Extract chunks
+            data = results.get("data", {}).get("Get", {}).get(class_name, [])
+            chunks = []
+            for item in data:
+                text = " ".join([str(item.get(p, "")) for p in properties if p in item])
+                chunks.append(text)
+            
+            context = "\n\n".join(chunks)
+            
+            # 4. Generate answer via A3M
+            answer = None
+            provider = None
+            if chunks:
+                try:
+                    response = self._a3m_router.chat(
+                        messages=[{
+                            "role": "user",
+                            "content": f"Context:\n{context}\n\nQuestion: {query}\n\nAnswer concisely:"
+                        }],
+                        model=self._embed_model,
+                    )
+                    answer = response.content
+                    provider = response.provider
+                except A3MRouterError:
+                    answer = chunks[0] if chunks else ""
+                    provider = "weaviate"
+            
+            return {
+                "chunks": chunks,
+                "context": context,
+                "answer": answer,
+                "provider": provider,
+            }
+
+    class WeaviateNearText:
+        """Helper class for near-text search with A3M embeddings."""
+        
+        def __init__(
+            self,
+            client: WeaviateAdapter,
+            text: str,
+            embedding: List[float],
+            certainty: Optional[float] = None,
+            distance: Optional[float] = None,
+        ) -> None:
+            self._client = client
+            self._text = text
+            self._embedding = embedding
+            self._certainty = certainty
+            self._distance = distance
+            
+        def with_limit(self, limit: int) -> "WeaviateNearText":
+            """Set result limit."""
+            self._limit = limit
+            return self
+            
+        def do(self) -> Dict[str, Any]:
+            """Execute the search."""
+            near_vector = {"vector": self._embedding}
+            if self._certainty is not None:
+                near_vector["certainty"] = self._certainty
+            if self._distance is not None:
+                near_vector["distance"] = self._distance
+            
+            return self._client.query.get(
+                self._class_name,
+                self._properties
+            ).with_near_vector(near_vector).with_limit(
+                getattr(self, "_limit", 10)
+            ).do()
+
+else:
+    class WeaviateAdapter:
+        def __init__(self, *args: Any, **kwargs: Any) -> None:
+            raise ImportError(
+                "Weaviate client not installed. "
+                "Install with: pip install weaviate-client"
+            )

package/python/a3m/client.py

@@ -188,3 +188,8 @@ class A3MRouter:
 
     async def __aexit__(self, *args):
         await self.close()
+
+
+class A3MRouterError(Exception):
+    """Base exception for A3MRouter errors."""
+    pass

package/python/a3m_router.egg-info/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: a3m-router
+Version: 2.2.2
+Summary: Auto-selects cheapest capable LLM from 47+ providers — 70-95% cost savings
+License: MIT
+Project-URL: Homepage, https://github.com/Das-rebel/a3m-router
+Project-URL: Documentation, https://das-rebel.github.io/a3m-router
+Project-URL: Repository, https://github.com/Das-rebel/a3m-router
+Project-URL: Changelog, https://github.com/Das-rebel/a3m-router/releases
+Keywords: llm,routing,openai,proxy,ai-gateway,routellm,litellm,multi-llm,model-selection,cost-optimization,langchain,llamaindex,rag,vector-search,embeddings,parallel,ensemble,router
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: langchain
+Requires-Dist: langchain>=0.1.0; extra == "langchain"
+Provides-Extra: llamaindex
+Requires-Dist: llamaindex>=0.9.0; extra == "llamaindex"
+Provides-Extra: qdrant
+Requires-Dist: qdrant-client>=1.7.0; extra == "qdrant"
+Provides-Extra: weaviate
+Requires-Dist: weaviate-client>=4.0.0; extra == "weaviate"
+Provides-Extra: adapters
+Requires-Dist: langchain>=0.1.0; extra == "adapters"
+Requires-Dist: llamaindex>=0.9.0; extra == "adapters"
+Requires-Dist: qdrant-client>=1.7.0; extra == "adapters"
+Requires-Dist: weaviate-client>=4.0.0; extra == "adapters"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+
+# A3M Router Python SDK
+
+**Intelligent LLM routing — auto-selects the cheapest capable model from 47+ providers.**
+
+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
+```
+
+## Quick Start
+
+```python
+from a3m import A3MRouter
+
+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
+
+# 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 responses
+async for token in router.stream_chat("Tell me a story"):
+    print(token, end="", flush=True)
+```
+
+## Key Features
+
+- **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
+
+## Framework Adapters
+
+| 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]
+```
+
+## Routing Tiers
+
+| 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
+
+### A3MRouter
+
+```python
+router = A3MRouter(
+    base_url="http://localhost:8787",  # A3M Router server URL
+    timeout=30.0,                       # Request timeout
+)
+```
+
+| 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?")])
+```
+
+### LlamaIndex Example
+
+```python
+from a3m import LlamaIndexAdapter
+
+llm = LlamaIndexAdapter()
+response = llm.complete("Explain transformers")
+```
+
+## Server Setup
+
+Start the A3M Router server:
+
+```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
+
+MIT

package/python/a3m_router.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+setup.py
+a3m/__init__.py
+a3m/client.py
+a3m/models.py
+a3m/sync_client.py
+a3m/adapters/__init__.py
+a3m/adapters/langchain.py
+a3m/adapters/llamaindex.py
+a3m/adapters/qdrant.py
+a3m/adapters/weaviate.py
+a3m_router.egg-info/PKG-INFO
+a3m_router.egg-info/SOURCES.txt
+a3m_router.egg-info/dependency_links.txt
+a3m_router.egg-info/requires.txt
+a3m_router.egg-info/top_level.txt

package/python/a3m_router.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

package/python/a3m_router.egg-info/requires.txt

@@ -0,0 +1,24 @@
+httpx>=0.24.0
+
+[adapters]
+langchain>=0.1.0
+llamaindex>=0.9.0
+qdrant-client>=1.7.0
+weaviate-client>=4.0.0
+
+[dev]
+pytest>=7.4.0
+pytest-asyncio>=0.21.0
+black>=23.0.0
+
+[langchain]
+langchain>=0.1.0
+
+[llamaindex]
+llamaindex>=0.9.0
+
+[qdrant]
+qdrant-client>=1.7.0
+
+[weaviate]
+weaviate-client>=4.0.0

package/python/a3m_router.egg-info/top_level.txt

@@ -0,0 +1 @@
+a3m

package/python/build_verify.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# Build and verify Python SDK
+set -e
+
+echo "=== Building A3M Router Python SDK v2.2.0 ==="
+cd "$(dirname "$0")"
+
+echo "1. Installing build dependencies..."
+pip install build twine 2>/dev/null || pip3 install build twine
+
+echo "2. Cleaning old builds..."
+rm -rf dist/ build/ *.egg-info
+
+echo "3. Building package..."
+python -m build
+
+echo "4. Checking package..."
+python -m twine check dist/*
+
+echo "5. Listing built files..."
+ls -lh dist/
+
+echo ""
+echo "=== Build complete! ==="
+echo "To publish to Test PyPI:"
+echo "  cd python && python -m twine upload --repository testpypi dist/*"
+echo ""
+echo "To publish to PyPI:"
+echo "  cd python && python -m twine upload dist/*"
+echo ""
+echo "To install locally:"
+echo "  pip install dist/a3m_router-*.whl"