agent-runtime-core 0.1.0__py3-none-any.whl

agent_runtime/llm/anthropic.py

@@ -0,0 +1,237 @@
+"""
+Anthropic API client implementation.
+"""
+
+import os
+from typing import AsyncIterator, Optional
+
+from agent_runtime.interfaces import (
+    LLMClient,
+    LLMResponse,
+    LLMStreamChunk,
+    Message,
+)
+
+try:
+    from anthropic import AsyncAnthropic, APIError
+except ImportError:
+    AsyncAnthropic = None
+    APIError = Exception
+
+
+class AnthropicConfigurationError(Exception):
+    """Raised when Anthropic API key is not configured."""
+    pass
+
+
+class AnthropicClient(LLMClient):
+    """
+    Anthropic API client.
+
+    Supports Claude models.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        default_model: Optional[str] = None,
+        **kwargs,
+    ):
+        if AsyncAnthropic is None:
+            raise ImportError(
+                "anthropic package is required for AnthropicClient. "
+                "Install it with: pip install agent_runtime[anthropic]"
+            )
+
+        from agent_runtime.config import get_config
+        config = get_config()
+        
+        self.default_model = default_model or config.default_model or "claude-sonnet-4-20250514"
+        
+        # Resolve API key with clear priority
+        resolved_api_key = self._resolve_api_key(api_key)
+        
+        if not resolved_api_key:
+            raise AnthropicConfigurationError(
+                "Anthropic API key is not configured.\n\n"
+                "Configure it using one of these methods:\n"
+                "  1. Use configure():\n"
+                "     from agent_runtime.config import configure\n"
+                "     configure(anthropic_api_key='sk-ant-...')\n\n"
+                "  2. Set the ANTHROPIC_API_KEY environment variable:\n"
+                "     export ANTHROPIC_API_KEY='sk-ant-...'\n\n"
+                "  3. Pass api_key directly to get_llm_client():\n"
+                "     llm = get_llm_client(api_key='sk-ant-...')"
+            )
+        
+        self._client = AsyncAnthropic(
+            api_key=resolved_api_key,
+            **kwargs,
+        )
+
+    def _resolve_api_key(self, explicit_key: Optional[str]) -> Optional[str]:
+        """
+        Resolve API key with clear priority order.
+        
+        Priority:
+        1. Explicit api_key parameter passed to __init__
+        2. anthropic_api_key in config
+        3. ANTHROPIC_API_KEY environment variable
+        """
+        if explicit_key:
+            return explicit_key
+        
+        from agent_runtime.config import get_config
+        config = get_config()
+        settings_key = config.get_anthropic_api_key()
+        if settings_key:
+            return settings_key
+        
+        return os.environ.get("ANTHROPIC_API_KEY")
+
+    async def generate(
+        self,
+        messages: list[Message],
+        *,
+        model: Optional[str] = None,
+        stream: bool = False,
+        tools: Optional[list[dict]] = None,
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        **kwargs,
+    ) -> LLMResponse:
+        """Generate a completion from Anthropic."""
+        model = model or self.default_model
+
+        # Extract system message
+        system_message = None
+        chat_messages = []
+        for msg in messages:
+            if msg.get("role") == "system":
+                system_message = msg.get("content", "")
+            else:
+                chat_messages.append(self._convert_message(msg))
+
+        request_kwargs = {
+            "model": model,
+            "messages": chat_messages,
+            "max_tokens": max_tokens or 4096,
+        }
+
+        if system_message:
+            request_kwargs["system"] = system_message
+        if tools:
+            request_kwargs["tools"] = self._convert_tools(tools)
+        if temperature is not None:
+            request_kwargs["temperature"] = temperature
+
+        request_kwargs.update(kwargs)
+
+        response = await self._client.messages.create(**request_kwargs)
+
+        return LLMResponse(
+            message=self._convert_response(response),
+            usage={
+                "prompt_tokens": response.usage.input_tokens,
+                "completion_tokens": response.usage.output_tokens,
+                "total_tokens": response.usage.input_tokens + response.usage.output_tokens,
+            },
+            model=response.model,
+            finish_reason=response.stop_reason or "",
+            raw_response=response,
+        )
+
+    async def stream(
+        self,
+        messages: list[Message],
+        *,
+        model: Optional[str] = None,
+        tools: Optional[list[dict]] = None,
+        **kwargs,
+    ) -> AsyncIterator[LLMStreamChunk]:
+        """Stream a completion from Anthropic."""
+        model = model or self.default_model
+
+        # Extract system message
+        system_message = None
+        chat_messages = []
+        for msg in messages:
+            if msg.get("role") == "system":
+                system_message = msg.get("content", "")
+            else:
+                chat_messages.append(self._convert_message(msg))
+
+        request_kwargs = {
+            "model": model,
+            "messages": chat_messages,
+            "max_tokens": kwargs.pop("max_tokens", 4096),
+        }
+
+        if system_message:
+            request_kwargs["system"] = system_message
+        if tools:
+            request_kwargs["tools"] = self._convert_tools(tools)
+
+        request_kwargs.update(kwargs)
+
+        async with self._client.messages.stream(**request_kwargs) as stream:
+            async for event in stream:
+                if event.type == "content_block_delta":
+                    if hasattr(event.delta, "text"):
+                        yield LLMStreamChunk(delta=event.delta.text)
+                elif event.type == "message_stop":
+                    yield LLMStreamChunk(finish_reason="stop")
+
+    def _convert_message(self, msg: Message) -> dict:
+        """Convert our message format to Anthropic format."""
+        role = msg.get("role", "user")
+        if role == "assistant":
+            role = "assistant"
+        elif role == "tool":
+            role = "user"  # Tool results go as user messages in Anthropic
+
+        return {
+            "role": role,
+            "content": msg.get("content", ""),
+        }
+
+    def _convert_tools(self, tools: list[dict]) -> list[dict]:
+        """Convert OpenAI tool format to Anthropic format."""
+        result = []
+        for tool in tools:
+            if tool.get("type") == "function":
+                func = tool["function"]
+                result.append({
+                    "name": func["name"],
+                    "description": func.get("description", ""),
+                    "input_schema": func.get("parameters", {}),
+                })
+        return result
+
+    def _convert_response(self, response) -> Message:
+        """Convert Anthropic response to our format."""
+        content = ""
+        tool_calls = []
+
+        for block in response.content:
+            if block.type == "text":
+                content += block.text
+            elif block.type == "tool_use":
+                tool_calls.append({
+                    "id": block.id,
+                    "type": "function",
+                    "function": {
+                        "name": block.name,
+                        "arguments": str(block.input),
+                    },
+                })
+
+        result: Message = {
+            "role": "assistant",
+            "content": content,
+        }
+
+        if tool_calls:
+            result["tool_calls"] = tool_calls
+
+        return result

agent_runtime/llm/litellm_client.py

@@ -0,0 +1,175 @@
+"""
+LiteLLM adapter for unified LLM access.
+
+LiteLLM provides a unified interface to 100+ LLM providers.
+This is an OPTIONAL adapter - the core runtime doesn't depend on it.
+"""
+
+from typing import AsyncIterator, Optional
+
+from agent_runtime.interfaces import (
+    LLMClient,
+    LLMResponse,
+    LLMStreamChunk,
+    Message,
+)
+
+try:
+    import litellm
+    from litellm import acompletion
+except ImportError:
+    litellm = None
+    acompletion = None
+
+
+class LiteLLMClient(LLMClient):
+    """
+    LiteLLM adapter for unified LLM access.
+
+    Supports 100+ providers through LiteLLM's unified interface.
+    See: https://docs.litellm.ai/docs/providers
+    """
+
+    def __init__(
+        self,
+        default_model: Optional[str] = None,
+        **kwargs,
+    ):
+        if litellm is None:
+            raise ImportError(
+                "litellm package is required for LiteLLMClient. "
+                "Install it with: pip install agent_runtime[litellm]"
+            )
+
+        from agent_runtime.config import get_config
+        config = get_config()
+        
+        self.default_model = default_model or config.default_model or "gpt-4o"
+        self._kwargs = kwargs
+
+    async def generate(
+        self,
+        messages: list[Message],
+        *,
+        model: Optional[str] = None,
+        stream: bool = False,
+        tools: Optional[list[dict]] = None,
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        **kwargs,
+    ) -> LLMResponse:
+        """Generate a completion using LiteLLM."""
+        model = model or self.default_model
+
+        request_kwargs = {
+            "model": model,
+            "messages": self._convert_messages(messages),
+        }
+
+        if tools:
+            request_kwargs["tools"] = tools
+        if temperature is not None:
+            request_kwargs["temperature"] = temperature
+        if max_tokens is not None:
+            request_kwargs["max_tokens"] = max_tokens
+
+        request_kwargs.update(self._kwargs)
+        request_kwargs.update(kwargs)
+
+        response = await acompletion(**request_kwargs)
+
+        choice = response.choices[0]
+        message = choice.message
+
+        return LLMResponse(
+            message=self._convert_response_message(message),
+            usage={
+                "prompt_tokens": response.usage.prompt_tokens if response.usage else 0,
+                "completion_tokens": response.usage.completion_tokens if response.usage else 0,
+                "total_tokens": response.usage.total_tokens if response.usage else 0,
+            },
+            model=response.model or model,
+            finish_reason=choice.finish_reason or "",
+            raw_response=response,
+        )
+
+    async def stream(
+        self,
+        messages: list[Message],
+        *,
+        model: Optional[str] = None,
+        tools: Optional[list[dict]] = None,
+        **kwargs,
+    ) -> AsyncIterator[LLMStreamChunk]:
+        """Stream a completion using LiteLLM."""
+        model = model or self.default_model
+
+        request_kwargs = {
+            "model": model,
+            "messages": self._convert_messages(messages),
+            "stream": True,
+        }
+
+        if tools:
+            request_kwargs["tools"] = tools
+
+        request_kwargs.update(self._kwargs)
+        request_kwargs.update(kwargs)
+
+        response = await acompletion(**request_kwargs)
+
+        async for chunk in response:
+            if not chunk.choices:
+                continue
+
+            choice = chunk.choices[0]
+            delta = choice.delta
+
+            yield LLMStreamChunk(
+                delta=getattr(delta, "content", "") or "",
+                tool_calls=getattr(delta, "tool_calls", None),
+                finish_reason=choice.finish_reason,
+                usage=None,
+            )
+
+    def _convert_messages(self, messages: list[Message]) -> list[dict]:
+        """Convert our message format to LiteLLM format (OpenAI-compatible)."""
+        result = []
+        for msg in messages:
+            converted = {
+                "role": msg.get("role", "user"),
+                "content": msg.get("content", ""),
+            }
+
+            if msg.get("name"):
+                converted["name"] = msg["name"]
+            if msg.get("tool_call_id"):
+                converted["tool_call_id"] = msg["tool_call_id"]
+            if msg.get("tool_calls"):
+                converted["tool_calls"] = msg["tool_calls"]
+
+            result.append(converted)
+
+        return result
+
+    def _convert_response_message(self, message) -> Message:
+        """Convert LiteLLM response message to our format."""
+        result: Message = {
+            "role": message.role,
+            "content": message.content or "",
+        }
+
+        if hasattr(message, "tool_calls") and message.tool_calls:
+            result["tool_calls"] = [
+                {
+                    "id": tc.id,
+                    "type": tc.type,
+                    "function": {
+                        "name": tc.function.name,
+                        "arguments": tc.function.arguments,
+                    },
+                }
+                for tc in message.tool_calls
+            ]
+
+        return result

agent_runtime/llm/openai.py

@@ -0,0 +1,220 @@
+"""
+OpenAI API client implementation.
+"""
+
+import os
+from typing import AsyncIterator, Optional
+
+from agent_runtime.interfaces import (
+    LLMClient,
+    LLMResponse,
+    LLMStreamChunk,
+    Message,
+)
+
+try:
+    from openai import AsyncOpenAI, OpenAIError
+except ImportError:
+    AsyncOpenAI = None
+    OpenAIError = Exception
+
+
+class OpenAIConfigurationError(Exception):
+    """Raised when OpenAI API key is not configured."""
+    pass
+
+
+class OpenAIClient(LLMClient):
+    """
+    OpenAI API client.
+
+    Supports GPT-4, GPT-3.5, and other OpenAI models.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        default_model: Optional[str] = None,
+        organization: Optional[str] = None,
+        base_url: Optional[str] = None,
+        **kwargs,
+    ):
+        if AsyncOpenAI is None:
+            raise ImportError(
+                "openai package is required for OpenAIClient. "
+                "Install it with: pip install agent_runtime[openai]"
+            )
+
+        from agent_runtime.config import get_config
+        config = get_config()
+        
+        self.default_model = default_model or config.default_model
+        
+        # Resolve API key with clear priority
+        resolved_api_key = self._resolve_api_key(api_key)
+        
+        try:
+            self._client = AsyncOpenAI(
+                api_key=resolved_api_key,
+                organization=organization,
+                base_url=base_url,
+                **kwargs,
+            )
+        except OpenAIError as e:
+            if "api_key" in str(e).lower():
+                raise OpenAIConfigurationError(
+                    "OpenAI API key is not configured.\n\n"
+                    "Configure it using one of these methods:\n"
+                    "  1. Use configure():\n"
+                    "     from agent_runtime.config import configure\n"
+                    "     configure(openai_api_key='sk-...')\n\n"
+                    "  2. Set the OPENAI_API_KEY environment variable:\n"
+                    "     export OPENAI_API_KEY='sk-...'\n\n"
+                    "  3. Pass api_key directly to get_llm_client():\n"
+                    "     llm = get_llm_client(api_key='sk-...')"
+                ) from e
+            raise
+
+    def _resolve_api_key(self, explicit_key: Optional[str]) -> Optional[str]:
+        """
+        Resolve API key with clear priority order.
+        
+        Priority:
+        1. Explicit api_key parameter passed to __init__
+        2. openai_api_key in config
+        3. OPENAI_API_KEY environment variable
+        """
+        if explicit_key:
+            return explicit_key
+        
+        from agent_runtime.config import get_config
+        config = get_config()
+        settings_key = config.get_openai_api_key()
+        if settings_key:
+            return settings_key
+        
+        return os.environ.get("OPENAI_API_KEY")
+
+    async def generate(
+        self,
+        messages: list[Message],
+        *,
+        model: Optional[str] = None,
+        stream: bool = False,
+        tools: Optional[list[dict]] = None,
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        **kwargs,
+    ) -> LLMResponse:
+        """Generate a completion from OpenAI."""
+        model = model or self.default_model
+
+        request_kwargs = {
+            "model": model,
+            "messages": self._convert_messages(messages),
+        }
+
+        if tools:
+            request_kwargs["tools"] = tools
+        if temperature is not None:
+            request_kwargs["temperature"] = temperature
+        if max_tokens is not None:
+            request_kwargs["max_tokens"] = max_tokens
+
+        request_kwargs.update(kwargs)
+
+        response = await self._client.chat.completions.create(**request_kwargs)
+
+        choice = response.choices[0]
+        message = choice.message
+
+        return LLMResponse(
+            message=self._convert_response_message(message),
+            usage={
+                "prompt_tokens": response.usage.prompt_tokens if response.usage else 0,
+                "completion_tokens": response.usage.completion_tokens if response.usage else 0,
+                "total_tokens": response.usage.total_tokens if response.usage else 0,
+            },
+            model=response.model,
+            finish_reason=choice.finish_reason or "",
+            raw_response=response,
+        )
+
+    async def stream(
+        self,
+        messages: list[Message],
+        *,
+        model: Optional[str] = None,
+        tools: Optional[list[dict]] = None,
+        **kwargs,
+    ) -> AsyncIterator[LLMStreamChunk]:
+        """Stream a completion from OpenAI."""
+        model = model or self.default_model
+
+        request_kwargs = {
+            "model": model,
+            "messages": self._convert_messages(messages),
+            "stream": True,
+        }
+
+        if tools:
+            request_kwargs["tools"] = tools
+
+        request_kwargs.update(kwargs)
+
+        async with await self._client.chat.completions.create(**request_kwargs) as stream:
+            async for chunk in stream:
+                if not chunk.choices:
+                    continue
+
+                choice = chunk.choices[0]
+                delta = choice.delta
+
+                yield LLMStreamChunk(
+                    delta=delta.content or "",
+                    tool_calls=delta.tool_calls if hasattr(delta, "tool_calls") else None,
+                    finish_reason=choice.finish_reason,
+                    usage=None,
+                )
+
+    def _convert_messages(self, messages: list[Message]) -> list[dict]:
+        """Convert our message format to OpenAI format."""
+        result = []
+        for msg in messages:
+            converted = {
+                "role": msg.get("role", "user"),
+                "content": msg.get("content", ""),
+            }
+
+            if msg.get("name"):
+                converted["name"] = msg["name"]
+            if msg.get("tool_call_id"):
+                converted["tool_call_id"] = msg["tool_call_id"]
+            if msg.get("tool_calls"):
+                converted["tool_calls"] = msg["tool_calls"]
+
+            result.append(converted)
+
+        return result
+
+    def _convert_response_message(self, message) -> Message:
+        """Convert OpenAI response message to our format."""
+        result: Message = {
+            "role": message.role,
+            "content": message.content or "",
+        }
+
+        if message.tool_calls:
+            result["tool_calls"] = [
+                {
+                    "id": tc.id,
+                    "type": tc.type,
+                    "function": {
+                        "name": tc.function.name,
+                        "arguments": tc.function.arguments,
+                    },
+                }
+                for tc in message.tool_calls
+            ]
+
+        return result

agent_runtime/queue/__init__.py

@@ -0,0 +1,55 @@
+"""
+Queue implementations for agent run scheduling.
+
+Provides:
+- RunQueue: Abstract interface
+- QueuedRun: Data structure for queued runs
+- InMemoryQueue: For testing and simple use cases
+- RedisQueue: For production with Redis
+- SQLiteQueue: For persistent local storage
+"""
+
+from agent_runtime.queue.base import RunQueue, QueuedRun
+from agent_runtime.queue.memory import InMemoryQueue
+
+__all__ = [
+    "RunQueue",
+    "QueuedRun",
+    "InMemoryQueue",
+    "get_queue",
+]
+
+
+def get_queue(backend: str = None, **kwargs) -> RunQueue:
+    """
+    Factory function to get a run queue.
+    
+    Args:
+        backend: "memory", "redis", or "sqlite"
+        **kwargs: Backend-specific configuration
+        
+    Returns:
+        RunQueue instance
+    """
+    from agent_runtime.config import get_config
+    
+    config = get_config()
+    backend = backend or config.queue_backend
+    
+    if backend == "memory":
+        return InMemoryQueue()
+    
+    elif backend == "redis":
+        from agent_runtime.queue.redis import RedisQueue
+        url = kwargs.get("url") or config.redis_url
+        if not url:
+            raise ValueError("redis_url is required for redis queue backend")
+        return RedisQueue(url=url)
+    
+    elif backend == "sqlite":
+        from agent_runtime.queue.sqlite import SQLiteQueue
+        path = kwargs.get("path") or config.sqlite_path or "agent_runtime.db"
+        return SQLiteQueue(path=path)
+    
+    else:
+        raise ValueError(f"Unknown queue backend: {backend}")