arbiterx-gate 0.1.0__py3-none-any.whl

arbiterx/__init__.py

@@ -0,0 +1,3 @@
+"""Cartograph — intelligent codebase mapping for AI-assisted development."""
+
+__version__ = "0.1.0"

arbiterx/adapters/__init__.py

@@ -0,0 +1,47 @@
+"""Model adapters for LLM providers."""
+
+from arbiterx.adapters.anthropic import AnthropicAdapter
+from arbiterx.adapters.base import ModelAdapter
+from arbiterx.adapters.google import GoogleAdapter
+from arbiterx.adapters.ollama import OllamaAdapter
+from arbiterx.adapters.openai import OpenAIAdapter
+from arbiterx.adapters.openrouter import OpenRouterAdapter
+
+__all__ = [
+    "ModelAdapter",
+    "AnthropicAdapter",
+    "OpenAIAdapter",
+    "GoogleAdapter",
+    "OllamaAdapter",
+    "OpenRouterAdapter",
+]
+
+# Registry for adapter lookup by provider name
+ADAPTER_REGISTRY: dict[str, type[ModelAdapter]] = {
+    "anthropic": AnthropicAdapter,
+    "openai": OpenAIAdapter,
+    "google": GoogleAdapter,
+    "ollama": OllamaAdapter,
+    "openrouter": OpenRouterAdapter,
+}
+
+
+def get_adapter(provider: str, model_name: str, **kwargs) -> ModelAdapter:
+    """Factory function to get an adapter by provider name.
+
+    Args:
+        provider: Provider identifier (anthropic, openai, google, ollama, openrouter).
+        model_name: Model name to use.
+        **kwargs: Additional configuration for the adapter.
+
+    Returns:
+        An initialized ModelAdapter instance.
+
+    Raises:
+        ValueError: If the provider is not registered.
+    """
+    adapter_cls = ADAPTER_REGISTRY.get(provider)
+    if adapter_cls is None:
+        available = ", ".join(sorted(ADAPTER_REGISTRY.keys()))
+        raise ValueError(f"Unknown provider '{provider}'. Available: {available}")
+    return adapter_cls(model_name, **kwargs)

arbiterx/adapters/anthropic.py

@@ -0,0 +1,145 @@
+"""Anthropic (Claude) adapter implementation."""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import AsyncIterator
+from typing import Any
+
+import httpx
+
+from arbiterx.adapters.base import ModelAdapter
+from arbiterx.router.handoff import ConversationState
+
+
+class AnthropicAdapter(ModelAdapter):
+    """Adapter for Anthropic's Claude API.
+
+    Handles the Anthropic-specific message format where system prompts
+    are passed as a separate top-level parameter rather than as a message.
+
+    Example:
+        >>> adapter = AnthropicAdapter("claude-sonnet-4-20250514", api_key="sk-...")
+        >>> response = await adapter.complete([{"role": "user", "content": "Hello"}])
+    """
+
+    DEFAULT_BASE_URL = "https://api.anthropic.com/v1"
+
+    def __init__(self, model_name: str = "claude-sonnet-4-20250514", **kwargs: Any) -> None:
+        api_key = kwargs.pop("api_key", "") or os.environ.get("ANTHROPIC_API_KEY", "")
+        super().__init__(model_name, api_key=api_key, **kwargs)
+        if not self.base_url:
+            self.base_url = self.DEFAULT_BASE_URL
+        self.api_version: str = kwargs.get("api_version", "2023-06-01")
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "x-api-key": self.api_key,
+            "anthropic-version": self.api_version,
+            "content-type": "application/json",
+        }
+
+    def _build_request(self, messages: list[dict[str, str]], **kwargs: Any) -> dict[str, Any]:
+        """Build the Anthropic API request body."""
+        # Separate system messages from conversation
+        system_parts: list[str] = []
+        api_messages: list[dict[str, str]] = []
+
+        for msg in messages:
+            if msg["role"] == "system":
+                system_parts.append(msg["content"])
+            else:
+                api_messages.append(msg)
+
+        body: dict[str, Any] = {
+            "model": self.model_name,
+            "messages": api_messages,
+            "max_tokens": kwargs.get("max_tokens", self.max_tokens),
+        }
+
+        if system_parts:
+            body["system"] = "\n\n".join(system_parts)
+
+        temperature = kwargs.get("temperature", self.temperature)
+        if temperature is not None:
+            body["temperature"] = temperature
+
+        return body
+
+    async def complete(self, messages: list[dict[str, str]], **kwargs: Any) -> str:
+        """Send messages to Claude and return the complete response."""
+        body = self._build_request(messages, **kwargs)
+
+        async with httpx.AsyncClient(timeout=120.0) as client:
+            response = await client.post(
+                f"{self.base_url}/messages",
+                headers=self._headers(),
+                json=body,
+            )
+            response.raise_for_status()
+            data = response.json()
+
+        # Extract text from content blocks
+        content_blocks = data.get("content", [])
+        text_parts = [block["text"] for block in content_blocks if block.get("type") == "text"]
+        return "\n".join(text_parts)
+
+    async def stream(self, messages: list[dict[str, str]], **kwargs: Any) -> AsyncIterator[str]:
+        """Stream response tokens from Claude using SSE."""
+        body = self._build_request(messages, **kwargs)
+        body["stream"] = True
+
+        async with (
+            httpx.AsyncClient(timeout=120.0) as client,
+            client.stream(
+                "POST",
+                f"{self.base_url}/messages",
+                headers=self._headers(),
+                json=body,
+            ) as response,
+        ):
+            response.raise_for_status()
+            async for line in response.aiter_lines():
+                if not line.startswith("data: "):
+                    continue
+                payload = line[6:]
+                if payload == "[DONE]":
+                    break
+                try:
+                    event = json.loads(payload)
+                    if event.get("type") == "content_block_delta":
+                        delta = event.get("delta", {})
+                        if delta.get("type") == "text_delta":
+                            yield delta.get("text", "")
+                except json.JSONDecodeError:
+                    continue
+
+    def format_messages(self, state: ConversationState) -> list[dict[str, str]]:
+        """Format state for Anthropic's API.
+
+        Anthropic expects system prompt as a separate parameter, so it's
+        stored in a system message that _build_request will extract.
+        """
+        messages: list[dict[str, str]] = []
+
+        # System prompt
+        system_parts: list[str] = []
+        if state.system_prompt:
+            system_parts.append(state.system_prompt)
+        if state.context_snippets:
+            system_parts.append(
+                "<context>\n" + "\n---\n".join(state.context_snippets) + "\n</context>"
+            )
+        if system_parts:
+            messages.append({"role": "system", "content": "\n\n".join(system_parts)})
+
+        # Conversation messages
+        for msg in state.messages:
+            messages.append({"role": msg.role, "content": msg.content})
+
+        return messages
+
+    def count_tokens(self, text: str) -> int:
+        """Estimate tokens using Claude's ~3.5 chars per token average."""
+        return max(1, len(text) // 4 + len(text) % 4)

arbiterx/adapters/base.py

@@ -0,0 +1,124 @@
+"""Abstract base class for all model adapters."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+from typing import Any
+
+from arbiterx.router.handoff import ConversationState
+
+
+class ModelAdapter(ABC):
+    """Abstract interface for LLM provider adapters.
+
+    All adapters must implement complete(), stream(), format_messages(),
+    and count_tokens(). Subclasses handle provider-specific API formats,
+    authentication, and error handling.
+
+    Attributes:
+        model_name: The identifier of the model being used.
+        max_tokens: Maximum output tokens supported.
+    """
+
+    def __init__(self, model_name: str, api_key: str = "", **kwargs: Any) -> None:
+        """Initialize the adapter.
+
+        Args:
+            model_name: Model identifier (e.g., "claude-sonnet-4-20250514").
+            api_key: API key for authentication.
+            **kwargs: Additional provider-specific configuration.
+        """
+        self.model_name = model_name
+        self.api_key = api_key
+        self.max_tokens: int = kwargs.get("max_tokens", 4096)
+        self.temperature: float = kwargs.get("temperature", 0.7)
+        self.base_url: str = kwargs.get("base_url", "")
+
+    @abstractmethod
+    async def complete(self, messages: list[dict[str, str]], **kwargs: Any) -> str:
+        """Send messages and return a complete response.
+
+        Args:
+            messages: List of message dicts with 'role' and 'content' keys.
+            **kwargs: Additional parameters (temperature, max_tokens, etc.).
+
+        Returns:
+            The complete response text from the model.
+
+        Raises:
+            NotImplementedError: Subclass must implement.
+        """
+        ...
+
+    @abstractmethod
+    async def stream(self, messages: list[dict[str, str]], **kwargs: Any) -> AsyncIterator[str]:
+        """Stream response tokens as they are generated.
+
+        Args:
+            messages: List of message dicts with 'role' and 'content' keys.
+            **kwargs: Additional parameters.
+
+        Yields:
+            Response text chunks as they arrive.
+
+        Raises:
+            NotImplementedError: Subclass must implement.
+        """
+        ...
+
+    @abstractmethod
+    def format_messages(self, state: ConversationState) -> list[dict[str, str]]:
+        """Convert a ConversationState into the provider's message format.
+
+        Different providers have different conventions for system messages,
+        multi-turn formatting, and metadata. This method handles those
+        translations.
+
+        Args:
+            state: The conversation state to format.
+
+        Returns:
+            List of message dicts formatted for this provider's API.
+        """
+        ...
+
+    @abstractmethod
+    def count_tokens(self, text: str) -> int:
+        """Estimate the number of tokens in a text string.
+
+        Each provider may use different tokenizers. This provides a
+        provider-appropriate estimate.
+
+        Args:
+            text: The text to tokenize.
+
+        Returns:
+            Estimated token count.
+        """
+        ...
+
+    def _build_messages(self, state: ConversationState) -> list[dict[str, str]]:
+        """Default message builder — can be overridden by subclasses.
+
+        Combines system prompt, context snippets, and conversation messages
+        into a flat list.
+        """
+        messages: list[dict[str, str]] = []
+
+        # System prompt with context
+        system_parts = [state.system_prompt] if state.system_prompt else []
+        if state.context_snippets:
+            system_parts.append("\n--- Context ---\n" + "\n---\n".join(state.context_snippets))
+
+        if system_parts:
+            messages.append({"role": "system", "content": "\n\n".join(system_parts)})
+
+        # Conversation messages
+        for msg in state.messages:
+            messages.append({"role": msg.role, "content": msg.content})
+
+        return messages
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(model={self.model_name!r})"

arbiterx/adapters/google.py

@@ -0,0 +1,133 @@
+"""Google Gemini adapter implementation."""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import AsyncIterator
+from typing import Any
+
+import httpx
+
+from arbiterx.adapters.base import ModelAdapter
+from arbiterx.router.handoff import ConversationState
+
+
+class GoogleAdapter(ModelAdapter):
+    """Adapter for Google's Gemini API.
+
+    Supports Gemini 1.5 Pro, 2.0 Pro, and Flash models.
+
+    Example:
+        >>> adapter = GoogleAdapter("gemini-2.0-pro", api_key="...")
+        >>> response = await adapter.complete([{"role": "user", "content": "Hello"}])
+    """
+
+    DEFAULT_BASE_URL = "https://generativelanguage.googleapis.com/v1beta"
+
+    def __init__(self, model_name: str = "gemini-2.0-flash", **kwargs: Any) -> None:
+        api_key = kwargs.pop("api_key", "") or os.environ.get("GOOGLE_AI_API_KEY", "")
+        super().__init__(model_name, api_key=api_key, **kwargs)
+        if not self.base_url:
+            self.base_url = self.DEFAULT_BASE_URL
+
+    def _build_request(self, messages: list[dict[str, str]], **kwargs: Any) -> dict[str, Any]:
+        """Build the Gemini API request body.
+
+        Gemini uses 'user' and 'model' roles with 'parts' content structure.
+        """
+        contents: list[dict[str, Any]] = []
+        system_instruction: str = ""
+
+        for msg in messages:
+            if msg["role"] == "system":
+                system_instruction = msg["content"]
+            else:
+                role = "model" if msg["role"] == "assistant" else "user"
+                contents.append(
+                    {
+                        "role": role,
+                        "parts": [{"text": msg["content"]}],
+                    }
+                )
+
+        body: dict[str, Any] = {
+            "contents": contents,
+            "generationConfig": {
+                "maxOutputTokens": kwargs.get("max_tokens", self.max_tokens),
+                "temperature": kwargs.get("temperature", self.temperature),
+            },
+        }
+
+        if system_instruction:
+            body["systemInstruction"] = {"parts": [{"text": system_instruction}]}
+
+        return body
+
+    async def complete(self, messages: list[dict[str, str]], **kwargs: Any) -> str:
+        """Send messages to Gemini and return the complete response."""
+        body = self._build_request(messages, **kwargs)
+        url = f"{self.base_url}/models/{self.model_name}:generateContent?key={self.api_key}"
+
+        async with httpx.AsyncClient(timeout=120.0) as client:
+            response = await client.post(url, json=body)
+            response.raise_for_status()
+            data = response.json()
+
+        candidates = data.get("candidates", [])
+        if candidates:
+            parts = candidates[0].get("content", {}).get("parts", [])
+            return "".join(p.get("text", "") for p in parts)
+        return ""
+
+    async def stream(self, messages: list[dict[str, str]], **kwargs: Any) -> AsyncIterator[str]:
+        """Stream response tokens from Gemini."""
+        body = self._build_request(messages, **kwargs)
+        url = (
+            f"{self.base_url}/models/{self.model_name}:streamGenerateContent"
+            f"?key={self.api_key}&alt=sse"
+        )
+
+        async with httpx.AsyncClient(timeout=120.0) as client:
+            async with client.stream("POST", url, json=body) as response:
+                response.raise_for_status()
+                async for line in response.aiter_lines():
+                    if not line.startswith("data: "):
+                        continue
+                    payload = line[6:]
+                    try:
+                        event = json.loads(payload)
+                        candidates = event.get("candidates", [])
+                        if candidates:
+                            parts = candidates[0].get("content", {}).get("parts", [])
+                            for part in parts:
+                                text = part.get("text", "")
+                                if text:
+                                    yield text
+                    except json.JSONDecodeError:
+                        continue
+
+    def format_messages(self, state: ConversationState) -> list[dict[str, str]]:
+        """Format state for Gemini's API.
+
+        Gemini uses 'user'/'model' roles. System prompt goes into
+        systemInstruction (handled by _build_request).
+        """
+        messages: list[dict[str, str]] = []
+
+        system_parts: list[str] = []
+        if state.system_prompt:
+            system_parts.append(state.system_prompt)
+        if state.context_snippets:
+            system_parts.append("## Context\n" + "\n---\n".join(state.context_snippets))
+        if system_parts:
+            messages.append({"role": "system", "content": "\n\n".join(system_parts)})
+
+        for msg in state.messages:
+            messages.append({"role": msg.role, "content": msg.content})
+
+        return messages
+
+    def count_tokens(self, text: str) -> int:
+        """Estimate tokens — Gemini uses ~4 chars per token on average."""
+        return max(1, len(text) // 4)

arbiterx/adapters/ollama.py

@@ -0,0 +1,129 @@
+"""Ollama adapter for local model inference."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator
+from typing import Any
+
+import httpx
+
+from arbiterx.adapters.base import ModelAdapter
+from arbiterx.router.handoff import ConversationState
+
+
+class OllamaAdapter(ModelAdapter):
+    """Adapter for Ollama local inference server.
+
+    Supports any model available via Ollama's OpenAI-compatible API.
+    No API key needed — runs entirely local.
+
+    Example:
+        >>> adapter = OllamaAdapter("qwen2.5-coder:7b")
+        >>> response = await adapter.complete([{"role": "user", "content": "Hello"}])
+    """
+
+    DEFAULT_BASE_URL = "http://localhost:11434"
+
+    def __init__(self, model_name: str = "qwen2.5-coder:7b", **kwargs: Any) -> None:
+        super().__init__(model_name, api_key="", **kwargs)
+        if not self.base_url:
+            self.base_url = self.DEFAULT_BASE_URL
+
+    def _build_request(self, messages: list[dict[str, str]], **kwargs: Any) -> dict[str, Any]:
+        """Build the Ollama API request body (OpenAI-compatible format)."""
+        body: dict[str, Any] = {
+            "model": self.model_name,
+            "messages": messages,
+            "options": {
+                "temperature": kwargs.get("temperature", self.temperature),
+                "num_predict": kwargs.get("max_tokens", self.max_tokens),
+            },
+        }
+        return body
+
+    async def complete(self, messages: list[dict[str, str]], **kwargs: Any) -> str:
+        """Send messages to Ollama and return the complete response."""
+        body = self._build_request(messages, **kwargs)
+        body["stream"] = False
+
+        async with httpx.AsyncClient(timeout=300.0) as client:
+            response = await client.post(
+                f"{self.base_url}/api/chat",
+                json=body,
+            )
+            response.raise_for_status()
+            data = response.json()
+
+        return data.get("message", {}).get("content", "")
+
+    async def stream(self, messages: list[dict[str, str]], **kwargs: Any) -> AsyncIterator[str]:
+        """Stream response tokens from Ollama."""
+        body = self._build_request(messages, **kwargs)
+        body["stream"] = True
+
+        async with (
+            httpx.AsyncClient(timeout=300.0) as client,
+            client.stream(
+                "POST",
+                f"{self.base_url}/api/chat",
+                json=body,
+            ) as response,
+        ):
+            response.raise_for_status()
+            async for line in response.aiter_lines():
+                if not line.strip():
+                    continue
+                try:
+                    event = json.loads(line)
+                    content = event.get("message", {}).get("content", "")
+                    if content:
+                        yield content
+                    if event.get("done", False):
+                        break
+                except json.JSONDecodeError:
+                    continue
+
+    def format_messages(self, state: ConversationState) -> list[dict[str, str]]:
+        """Format state for Ollama's API.
+
+        Ollama supports standard system/user/assistant roles.
+        """
+        messages: list[dict[str, str]] = []
+
+        system_parts: list[str] = []
+        if state.system_prompt:
+            system_parts.append(state.system_prompt)
+        if state.context_snippets:
+            system_parts.append("Context:\n" + "\n---\n".join(state.context_snippets))
+        if system_parts:
+            messages.append({"role": "system", "content": "\n\n".join(system_parts)})
+
+        for msg in state.messages:
+            messages.append({"role": msg.role, "content": msg.content})
+
+        return messages
+
+    def count_tokens(self, text: str) -> int:
+        """Estimate tokens — most local models use ~4 chars per token."""
+        return max(1, len(text) // 4)
+
+    async def is_available(self) -> bool:
+        """Check if Ollama server is running and accessible."""
+        try:
+            async with httpx.AsyncClient(timeout=5.0) as client:
+                response = await client.get(f"{self.base_url}/api/tags")
+                return response.status_code == 200
+        except (httpx.ConnectError, httpx.TimeoutException):
+            return False
+
+    async def list_models(self) -> list[str]:
+        """List available models on the Ollama server."""
+        try:
+            async with httpx.AsyncClient(timeout=10.0) as client:
+                response = await client.get(f"{self.base_url}/api/tags")
+                response.raise_for_status()
+                data = response.json()
+                return [m["name"] for m in data.get("models", [])]
+        except (httpx.ConnectError, httpx.TimeoutException, httpx.HTTPStatusError):
+            return []