axel-protocol 2.1.0__py3-none-any.whl

axel/__init__.py

@@ -0,0 +1,80 @@
+"""
+axel — Agent eXchange Language
+================================
+A universal protocol for multi-LLM networks.
+
+Quick start:
+    from axel import AXELClient, AXELAgent, AXELServer
+
+    # Start the hub (with optional auth + persistence)
+    server = AXELServer(key="secret", db="axel.db")
+    server.start_background()
+
+    # Connect an agent
+    client = AXELClient("http://localhost:7331", "my_agent",
+                        model="claude-3-5-haiku", provider="anthropic",
+                        caps=["research", "summarize"],
+                        key="secret")
+
+    # Execute a task on another agent
+    result = client.execute("writer", "draft_content", {"topic": "AI"})
+
+Testing:
+    from axel.testing import MockServer, MessageCapture
+
+    with MockServer() as url:
+        c = AXELClient(url, "tester", model="x", provider="mock", caps=[])
+        ...
+"""
+
+from axel.core import AXELBuilder, AXELMessage
+from axel.client import AXELClient, AXELAgent
+from axel.server import AXELServer
+from axel.universal import SmartMemory
+from axel.adapters import (
+    # bundled
+    MockAdapter, AnthropicAdapter, OpenAIAdapter, OllamaAdapter, OpenRouterAdapter,
+    # optional (lazy-loaded)
+    GeminiAdapter, MistralAdapter, GroqAdapter,
+    TogetherAdapter, CohereAdapter, LiteLLMAdapter, BedrockAdapter,
+    # factory
+    make_adapter, get_adapter,
+)
+
+__version__ = "2.1.0"
+__author__  = "Sector X"
+__license__ = "MIT"
+
+__all__ = [
+    # Core message types
+    "AXELMessage",
+    "AXELBuilder",
+    # Client SDK
+    "AXELClient",
+    "AXELAgent",
+    # Server
+    "AXELServer",
+    # Memory
+    "SmartMemory",
+    # Adapters — bundled
+    "MockAdapter",
+    "AnthropicAdapter",
+    "OpenAIAdapter",
+    "OllamaAdapter",
+    "OpenRouterAdapter",
+    # Adapters — optional providers
+    "GeminiAdapter",
+    "MistralAdapter",
+    "GroqAdapter",
+    "TogetherAdapter",
+    "CohereAdapter",
+    "LiteLLMAdapter",
+    "BedrockAdapter",
+    # Factory helpers
+    "make_adapter",
+    "get_adapter",
+    # Testing utilities
+    "testing",
+    # Persistence
+    "persistence",
+]

axel/adapters/__init__.py

@@ -0,0 +1,148 @@
+"""
+axel.adapters — LLM provider adapters for the AXEL network
+===========================================================
+
+All adapters share the same interface: instantiate with an agent_id + model,
+then call adapter.execute(task_msg) to get back an AXELMessage.
+
+Quick reference
+---------------
+Provider          Class               Install                     Env var
+──────────────    ────────────────    ────────────────────────    ────────────────────────
+OpenRouter        OpenRouterAdapter   pip install openai          OPENROUTER_API_KEY  ← start here
+Anthropic         AnthropicAdapter    (bundled)                   ANTHROPIC_API_KEY
+OpenAI            OpenAIAdapter       (bundled)                   OPENAI_API_KEY
+Ollama (local)    OllamaAdapter       (bundled)                   —
+Google Gemini     GeminiAdapter       google-generativeai         GOOGLE_API_KEY
+Mistral AI        MistralAdapter      mistralai                   MISTRAL_API_KEY
+Groq              GroqAdapter         groq                        GROQ_API_KEY
+Together AI       TogetherAdapter     together                    TOGETHER_API_KEY
+Cohere            CohereAdapter       cohere                      COHERE_API_KEY
+AWS Bedrock       BedrockAdapter      boto3                       AWS_* credentials
+Any (LiteLLM)     LiteLLMAdapter      litellm                     provider-specific
+Mock (testing)    MockAdapter         (bundled)                   —
+
+Usage
+-----
+    from axel.adapters import GeminiAdapter, GroqAdapter, LiteLLMAdapter
+
+    # Google Gemini researcher
+    researcher = GeminiAdapter("researcher",
+                               model="gemini-1.5-flash",
+                               capabilities=["research", "summarize"])
+
+    # Groq fast reviewer
+    reviewer = GroqAdapter("reviewer",
+                           model="llama-3.1-8b-instant",
+                           capabilities=["review", "score"])
+
+    # LiteLLM — any model, one adapter
+    writer = LiteLLMAdapter("writer",
+                            model="groq/llama-3.3-70b-versatile",
+                            capabilities=["write", "edit"])
+
+    # Register with the AXEL server bridge
+    bridge.add_adapter("researcher", researcher)
+    bridge.add_adapter("reviewer",   reviewer)
+    bridge.add_adapter("writer",     writer)
+"""
+
+# ── Bundled adapters (no extra install) ───────────────────────────
+from axel.universal import (
+    AnthropicAdapter,
+    OpenAIAdapter,
+    OllamaAdapter,
+    OpenRouterAdapter,
+    MockAdapter,
+    BaseAdapter,
+)
+
+# ── Optional provider adapters ────────────────────────────────────
+# All use lazy imports internally — importing these classes is free.
+# The provider SDK is only loaded when execute() is first called.
+
+from axel.adapters.gemini   import GeminiAdapter
+from axel.adapters.mistral  import MistralAdapter
+from axel.adapters.groq     import GroqAdapter
+from axel.adapters.together import TogetherAdapter
+from axel.adapters.cohere   import CohereAdapter
+from axel.adapters.litellm  import LiteLLMAdapter
+from axel.adapters.bedrock  import BedrockAdapter
+
+__all__ = [
+    # Bundled
+    "BaseAdapter",
+    "MockAdapter",
+    "AnthropicAdapter",
+    "OpenAIAdapter",
+    "OllamaAdapter",
+    "OpenRouterAdapter",
+    # Optional
+    "GeminiAdapter",
+    "MistralAdapter",
+    "GroqAdapter",
+    "TogetherAdapter",
+    "CohereAdapter",
+    "LiteLLMAdapter",
+    "BedrockAdapter",
+]
+
+# ── Provider registry — useful for dynamic instantiation ──────────
+PROVIDERS: dict[str, type] = {
+    "anthropic": AnthropicAdapter,
+    "openai":    OpenAIAdapter,
+    "ollama":    OllamaAdapter,
+    "google":    GeminiAdapter,
+    "gemini":    GeminiAdapter,
+    "mistral":   MistralAdapter,
+    "groq":      GroqAdapter,
+    "together":  TogetherAdapter,
+    "cohere":    CohereAdapter,
+    "litellm":   LiteLLMAdapter,
+    "bedrock":   BedrockAdapter,
+    "aws":       BedrockAdapter,
+    "openrouter": OpenRouterAdapter,
+    "mock":        MockAdapter,
+}
+
+
+def get_adapter(provider: str) -> type:
+    """
+    Lookup an adapter class by provider name (case-insensitive).
+
+    Example::
+
+        AdapterClass = get_adapter("groq")
+        adapter = AdapterClass("my_agent", model="llama-3.1-8b-instant")
+    """
+    key = provider.lower()
+    if key not in PROVIDERS:
+        available = ", ".join(sorted(PROVIDERS))
+        raise ValueError(
+            f"Unknown provider '{provider}'. Available: {available}"
+        )
+    return PROVIDERS[key]
+
+
+def make_adapter(
+    agent_id: str,
+    provider: str,
+    model: str,
+    capabilities: list[str] | None = None,
+    **kwargs,
+) -> BaseAdapter:
+    """
+    Factory: create any adapter by provider name.
+
+    Example::
+
+        adapter = make_adapter("researcher", "groq",
+                               "llama-3.3-70b-versatile",
+                               capabilities=["research"])
+        result  = adapter.execute(task_msg)
+    """
+    AdapterClass = get_adapter(provider)
+    # MockAdapter has a simplified signature
+    if AdapterClass is MockAdapter:
+        return AdapterClass(agent_id)
+    return AdapterClass(agent_id, model=model, capabilities=capabilities, **kwargs)

axel/adapters/bedrock.py

@@ -0,0 +1,153 @@
+"""
+axel/adapters/bedrock.py — AWS Bedrock adapter for AXEL
+
+Bedrock gives access to frontier models (Claude, Llama, Mistral, Titan)
+inside your AWS VPC — no data leaves your cloud environment.
+Ideal for enterprise deployments with strict data residency requirements.
+
+Supported model IDs (as of 2024):
+    anthropic.claude-3-5-haiku-20241022-v1:0    Claude 3.5 Haiku
+    anthropic.claude-3-5-sonnet-20241022-v2:0   Claude 3.5 Sonnet
+    anthropic.claude-3-opus-20240229-v1:0        Claude 3 Opus
+    meta.llama3-1-70b-instruct-v1:0              Llama 3.1 70B
+    meta.llama3-1-8b-instruct-v1:0               Llama 3.1 8B
+    mistral.mistral-large-2402-v1:0              Mistral Large
+    amazon.titan-text-premier-v1:0               Amazon Titan
+
+Install:
+    pip install boto3
+
+Auth:
+    AWS credentials via env vars, ~/.aws/credentials, or IAM role:
+    export AWS_ACCESS_KEY_ID=...
+    export AWS_SECRET_ACCESS_KEY=...
+    export AWS_DEFAULT_REGION=us-east-1
+
+Permissions needed:
+    bedrock:InvokeModel on arn:aws:bedrock:*::foundation-model/*
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from typing import List, Optional
+
+from axel.universal import BaseAdapter, make_system_prompt, AXELMessage
+
+
+class BedrockAdapter(BaseAdapter):
+    """
+    Execute AXEL TASK messages using AWS Bedrock.
+
+    Bedrock uses the Converse API (unified chat interface across all models),
+    so this adapter works consistently regardless of which model is selected.
+
+    Example::
+
+        adapter = BedrockAdapter(
+            "secure_researcher",
+            model_id="anthropic.claude-3-5-haiku-20241022-v1:0",
+            region="us-east-1",
+            capabilities=["research", "summarize"],
+        )
+        result = adapter.execute(task_msg)
+
+    Notes:
+        - Model access must be enabled in the Bedrock console for your region
+        - Cross-region inference profiles are supported (prefix with region code)
+    """
+
+    PROVIDER = "bedrock"
+    DEFAULT_MODEL = "anthropic.claude-3-5-haiku-20241022-v1:0"
+
+    def __init__(
+        self,
+        agent_id: str,
+        model_id: str = DEFAULT_MODEL,
+        capabilities: Optional[List[str]] = None,
+        region: Optional[str] = None,
+        aws_access_key_id: Optional[str] = None,
+        aws_secret_access_key: Optional[str] = None,
+        aws_session_token: Optional[str] = None,
+        max_tokens: int = 2048,
+        temperature: float = 0.7,
+    ):
+        system = make_system_prompt(agent_id, capabilities or [], f"bedrock/{model_id}")
+        super().__init__(agent_id, system)
+        self.model_id    = model_id
+        self.max_tokens  = max_tokens
+        self.temperature = temperature
+        self._region     = region or os.environ.get("AWS_DEFAULT_REGION", "us-east-1")
+        self._key_id     = aws_access_key_id
+        self._secret     = aws_secret_access_key
+        self._token      = aws_session_token
+        self._client     = None
+
+    def _get_client(self):
+        if self._client is None:
+            try:
+                import boto3
+            except ImportError:
+                raise RuntimeError(
+                    "boto3 not installed.\n"
+                    "Run: pip install boto3"
+                )
+            session_kwargs = {}
+            if self._key_id:
+                session_kwargs["aws_access_key_id"]     = self._key_id
+            if self._secret:
+                session_kwargs["aws_secret_access_key"] = self._secret
+            if self._token:
+                session_kwargs["aws_session_token"]     = self._token
+
+            session = boto3.Session(**session_kwargs) if session_kwargs else boto3.Session()
+            self._client = session.client("bedrock-runtime", region_name=self._region)
+        return self._client
+
+    def execute(self, task_msg: AXELMessage) -> AXELMessage:
+        action = task_msg.body.get("act", "unknown")
+        args   = task_msg.body.get("args", {})
+        ctx    = task_msg.body.get("ctx", {})
+
+        user_content = (
+            f"AXEL TASK:\n{task_msg.to_json(compact=False)}\n\n"
+            f"Execute '{action}' with args: {json.dumps(args)}\n"
+            f"Context: {json.dumps(ctx)}\n\n"
+            f"Respond with a single compact AXEL OK or ER JSON message."
+        )
+
+        try:
+            client = self._get_client()
+
+            # Bedrock Converse API — unified interface across all models
+            resp = client.converse(
+                modelId=self.model_id,
+                system=[{"text": self.system_prompt}],
+                messages=[{"role": "user", "content": [{"text": user_content}]}],
+                inferenceConfig={
+                    "maxTokens":   self.max_tokens,
+                    "temperature": self.temperature,
+                },
+            )
+            raw = resp["output"]["message"]["content"][0]["text"].strip()
+
+            try:
+                match = re.search(r"\{.*\}", raw, re.DOTALL)
+                if match:
+                    parsed = json.loads(match.group())
+                    return AXELMessage.from_dict({
+                        **parsed,
+                        "fr":  self.agent_id,
+                        "to":  task_msg.fr,
+                        "cid": task_msg.cid,
+                        "re":  task_msg.id,
+                    })
+            except Exception:
+                pass
+
+            return self._ok(task_msg, {"text": raw})
+
+        except Exception as exc:
+            return self._err(task_msg, "INTERNAL", str(exc), retry=True)

axel/adapters/cohere.py

@@ -0,0 +1,121 @@
+"""
+axel/adapters/cohere.py — Cohere adapter for AXEL
+
+Cohere specialises in enterprise NLP: RAG, classification, reranking, and embeddings.
+Their Command R+ model is particularly strong for tool-use and multi-step reasoning.
+
+Supported models (as of 2024):
+    command-r-plus     best quality, tool-use, 128k context
+    command-r          balanced speed/quality, 128k context
+    command-light      fast and cheap
+    command            production-ready general model
+
+Install:
+    pip install cohere
+
+Auth:
+    export COHERE_API_KEY=your_key
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from typing import List, Optional
+
+from axel.universal import BaseAdapter, make_system_prompt, AXELMessage
+
+
+class CohereAdapter(BaseAdapter):
+    """
+    Execute AXEL TASK messages using Cohere.
+
+    Cohere's Command R+ is excellent for RAG-augmented tasks and tool use,
+    making it well-suited for research and retrieval agent roles in a network.
+
+    Example::
+
+        adapter = CohereAdapter(
+            "rag_researcher",
+            model="command-r-plus",
+            capabilities=["research", "rag_query", "rerank"],
+        )
+        result = adapter.execute(task_msg)
+    """
+
+    PROVIDER = "cohere"
+    DEFAULT_MODEL = "command-r-plus"
+
+    def __init__(
+        self,
+        agent_id: str,
+        model: str = DEFAULT_MODEL,
+        capabilities: Optional[List[str]] = None,
+        api_key: Optional[str] = None,
+        temperature: float = 0.7,
+        max_tokens: int = 2048,
+    ):
+        system = make_system_prompt(agent_id, capabilities or [], f"cohere/{model}")
+        super().__init__(agent_id, system)
+        self.model       = model
+        self.temperature = temperature
+        self.max_tokens  = max_tokens
+        self._api_key    = api_key or os.environ.get("COHERE_API_KEY")
+        self._client     = None
+
+    def _get_client(self):
+        if self._client is None:
+            try:
+                import cohere
+            except ImportError:
+                raise RuntimeError(
+                    "Cohere SDK not installed.\n"
+                    "Run: pip install cohere"
+                )
+            self._client = cohere.ClientV2(api_key=self._api_key)
+        return self._client
+
+    def execute(self, task_msg: AXELMessage) -> AXELMessage:
+        action = task_msg.body.get("act", "unknown")
+        args   = task_msg.body.get("args", {})
+        ctx    = task_msg.body.get("ctx", {})
+
+        user_content = (
+            f"AXEL TASK:\n{task_msg.to_json(compact=False)}\n\n"
+            f"Execute '{action}' with args: {json.dumps(args)}\n"
+            f"Context: {json.dumps(ctx)}\n\n"
+            f"Respond with a single compact AXEL OK or ER JSON message."
+        )
+
+        try:
+            client = self._get_client()
+            resp   = client.chat(
+                model=self.model,
+                messages=[
+                    {"role": "system", "content": self.system_prompt},
+                    {"role": "user",   "content": user_content},
+                ],
+                temperature=self.temperature,
+                max_tokens=self.max_tokens,
+            )
+            raw = resp.message.content[0].text.strip()
+
+            try:
+                match = re.search(r"\{.*\}", raw, re.DOTALL)
+                if match:
+                    parsed = json.loads(match.group())
+                    return AXELMessage.from_dict({
+                        **parsed,
+                        "fr":  self.agent_id,
+                        "to":  task_msg.fr,
+                        "cid": task_msg.cid,
+                        "re":  task_msg.id,
+                    })
+            except Exception:
+                pass
+
+            return self._ok(task_msg, {"text": raw})
+
+        except Exception as exc:
+            return self._err(task_msg, "INTERNAL", str(exc), retry=True)

axel/adapters/gemini.py

@@ -0,0 +1,119 @@
+"""
+axel/adapters/gemini.py — Google Gemini adapter for AXEL
+
+Supported models (as of 2024):
+    gemini-1.5-flash        fast, cheap, 1M context
+    gemini-1.5-pro          flagship, multimodal, 2M context
+    gemini-2.0-flash        next-gen fast model
+
+Install:
+    pip install google-generativeai
+
+Auth:
+    export GOOGLE_API_KEY=your_key
+    # OR pass api_key= directly
+    # OR use Application Default Credentials (ADC) on GCP/Vertex
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from typing import List, Optional
+
+from axel.universal import BaseAdapter, make_system_prompt, AXELMessage
+
+
+class GeminiAdapter(BaseAdapter):
+    """
+    Execute AXEL TASK messages using Google Gemini.
+
+    Example::
+
+        adapter = GeminiAdapter(
+            "researcher",
+            model="gemini-1.5-flash",
+            capabilities=["research", "summarize"],
+        )
+        result = adapter.execute(task_msg)
+    """
+
+    PROVIDER = "google"
+    DEFAULT_MODEL = "gemini-1.5-flash"
+
+    def __init__(
+        self,
+        agent_id: str,
+        model: str = DEFAULT_MODEL,
+        capabilities: Optional[List[str]] = None,
+        api_key: Optional[str] = None,
+        temperature: float = 0.7,
+        max_tokens: int = 2048,
+    ):
+        system = make_system_prompt(agent_id, capabilities or [], f"gemini/{model}")
+        super().__init__(agent_id, system)
+        self.model       = model
+        self.temperature = temperature
+        self.max_tokens  = max_tokens
+        self._api_key    = api_key or os.environ.get("GOOGLE_API_KEY")
+        self._client     = None
+
+    def _get_client(self):
+        if self._client is None:
+            try:
+                import google.generativeai as genai
+            except ImportError:
+                raise RuntimeError(
+                    "Google Generative AI SDK not installed.\n"
+                    "Run: pip install google-generativeai"
+                )
+            if self._api_key:
+                genai.configure(api_key=self._api_key)
+            # else relies on GOOGLE_API_KEY env var or ADC
+            self._client = genai.GenerativeModel(
+                model_name=self.model,
+                system_instruction=self.system_prompt,
+                generation_config={
+                    "temperature":     self.temperature,
+                    "max_output_tokens": self.max_tokens,
+                },
+            )
+        return self._client
+
+    def execute(self, task_msg: AXELMessage) -> AXELMessage:
+        action = task_msg.body.get("act", "unknown")
+        args   = task_msg.body.get("args", {})
+        ctx    = task_msg.body.get("ctx", {})
+
+        prompt = (
+            f"AXEL TASK received:\n"
+            f"{task_msg.to_json(compact=False)}\n\n"
+            f"Execute action '{action}' with args: {json.dumps(args)}\n"
+            f"Context: {json.dumps(ctx)}\n\n"
+            f"Respond with a single compact AXEL OK or ER JSON message."
+        )
+
+        try:
+            model  = self._get_client()
+            resp   = model.generate_content(prompt)
+            raw    = resp.text.strip()
+
+            try:
+                match = re.search(r"\{.*\}", raw, re.DOTALL)
+                if match:
+                    parsed = json.loads(match.group())
+                    return AXELMessage.from_dict({
+                        **parsed,
+                        "fr":  self.agent_id,
+                        "to":  task_msg.fr,
+                        "cid": task_msg.cid,
+                        "re":  task_msg.id,
+                    })
+            except Exception:
+                pass
+
+            return self._ok(task_msg, {"text": raw})
+
+        except Exception as exc:
+            return self._err(task_msg, "INTERNAL", str(exc), retry=True)