voxagent 0.1.0__py3-none-any.whl

voxagent/providers/openai.py

@@ -0,0 +1,435 @@
+"""OpenAI provider implementation.
+
+This module implements the OpenAI provider for chat completions,
+supporting both streaming and non-streaming responses with tool calling.
+"""
+
+import json
+from collections.abc import AsyncIterator
+from typing import Any
+
+import httpx
+
+from voxagent.providers.base import (
+    AbortSignal,
+    BaseProvider,
+    ErrorChunk,
+    MessageEndChunk,
+    StreamChunk,
+    TextDeltaChunk,
+    ToolUseChunk,
+)
+from voxagent.types import Message, ToolCall
+
+
+class OpenAIProvider(BaseProvider):
+    """OpenAI chat completions provider.
+
+    Supports GPT-4o, GPT-4-turbo, GPT-3.5-turbo, and O1 models
+    with streaming, tool calling, and token counting.
+    """
+
+    ENV_KEY = "OPENAI_API_KEY"
+    DEFAULT_BASE_URL = "https://api.openai.com/v1"
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        model: str = "gpt-4o",
+        **kwargs: Any,
+    ) -> None:
+        """Initialize the OpenAI provider.
+
+        Args:
+            api_key: OpenAI API key. Falls back to OPENAI_API_KEY env var.
+            base_url: Custom base URL for API requests (e.g., for Azure or proxies).
+            model: Model name to use. Defaults to "gpt-4o".
+            **kwargs: Additional provider-specific arguments.
+        """
+        super().__init__(api_key=api_key, base_url=base_url, **kwargs)
+        self._model = model
+
+    @property
+    def name(self) -> str:
+        """Get the provider name."""
+        return "openai"
+
+    @property
+    def model(self) -> str:
+        """Get the current model name."""
+        return self._model
+
+    @property
+    def models(self) -> list[str]:
+        """Get the list of supported model names."""
+        return ["gpt-4o", "gpt-4o-mini", "gpt-4-turbo", "gpt-3.5-turbo", "o1", "o1-mini", "o1-preview"]
+
+    @property
+    def supports_tools(self) -> bool:
+        """Check if the provider supports tool/function calling."""
+        return True
+
+    @property
+    def supports_streaming(self) -> bool:
+        """Check if the provider supports streaming responses."""
+        return True
+
+    @property
+    def context_limit(self) -> int:
+        """Get the maximum context length in tokens."""
+        return 128000
+
+    def _get_api_url(self) -> str:
+        """Get the API URL for chat completions."""
+        base = self._base_url or self.DEFAULT_BASE_URL
+        return f"{base}/chat/completions"
+
+    def _get_headers(self) -> dict[str, str]:
+        """Get HTTP headers for API requests."""
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+    def _convert_messages_to_openai(
+        self, messages: list[Message], system: str | None = None
+    ) -> list[dict[str, Any]]:
+        """Convert voxagent Messages to OpenAI message format.
+
+        Args:
+            messages: List of voxagent Message objects.
+            system: Optional system prompt to prepend.
+
+        Returns:
+            List of OpenAI-format message dictionaries.
+        """
+        result: list[dict[str, Any]] = []
+
+        if system:
+            result.append({"role": "system", "content": system})
+
+        for msg in messages:
+            openai_msg: dict[str, Any] = {"role": msg.role}
+
+            # Handle content
+            if isinstance(msg.content, str):
+                openai_msg["content"] = msg.content
+            else:
+                # Handle content blocks - convert to string for simplicity
+                text_parts = [b.text for b in msg.content if hasattr(b, "text")]
+                openai_msg["content"] = " ".join(text_parts) if text_parts else ""
+
+            # Handle tool calls
+            if msg.tool_calls:
+                openai_msg["tool_calls"] = [
+                    {
+                        "id": tc.id,
+                        "type": "function",
+                        "function": {
+                            "name": tc.name,
+                            "arguments": json.dumps(tc.params),
+                        },
+                    }
+                    for tc in msg.tool_calls
+                ]
+
+            result.append(openai_msg)
+
+        return result
+
+    def _convert_openai_response_to_message(self, response: dict[str, Any]) -> Message:
+        """Convert OpenAI response message to voxagent Message.
+
+        Args:
+            response: OpenAI message dictionary from API response.
+
+        Returns:
+            A voxagent Message object.
+        """
+        role = response.get("role", "assistant")
+        content = response.get("content") or ""
+
+        tool_calls: list[ToolCall] | None = None
+        if "tool_calls" in response and response["tool_calls"]:
+            tool_calls = []
+            for tc in response["tool_calls"]:
+                params = {}
+                if tc.get("function", {}).get("arguments"):
+                    try:
+                        params = json.loads(tc["function"]["arguments"])
+                    except json.JSONDecodeError:
+                        params = {}
+                tool_calls.append(
+                    ToolCall(
+                        id=tc["id"],
+                        name=tc["function"]["name"],
+                        params=params,
+                    )
+                )
+
+        return Message(role=role, content=content, tool_calls=tool_calls)
+
+    def _build_request_body(
+        self,
+        messages: list[Message],
+        system: str | None = None,
+        tools: list[Any] | None = None,
+        stream: bool = False,
+    ) -> dict[str, Any]:
+        """Build the request body for OpenAI API.
+
+        Args:
+            messages: List of voxagent Message objects.
+            system: Optional system prompt.
+            tools: Optional list of tool definitions.
+            stream: Whether to enable streaming.
+
+        Returns:
+            Request body dictionary.
+        """
+        body: dict[str, Any] = {
+            "model": self._model,
+            "messages": self._convert_messages_to_openai(messages, system=system),
+            "stream": stream,
+        }
+
+        if tools:
+            body["tools"] = tools
+
+        return body
+
+    async def _make_request(
+        self,
+        messages: list[Message],
+        system: str | None = None,
+        tools: list[Any] | None = None,
+    ) -> dict[str, Any]:
+        """Make a non-streaming request to the OpenAI API.
+
+        Args:
+            messages: List of voxagent Message objects.
+            system: Optional system prompt.
+            tools: Optional list of tool definitions.
+
+        Returns:
+            The JSON response from the API.
+
+        Raises:
+            Exception: If the API request fails.
+        """
+        body = self._build_request_body(messages, system=system, tools=tools, stream=False)
+
+        async with httpx.AsyncClient() as client:
+            response = await client.post(
+                self._get_api_url(),
+                headers=self._get_headers(),
+                json=body,
+                timeout=60.0,
+            )
+            response.raise_for_status()
+            return response.json()
+
+    async def _make_streaming_request(
+        self,
+        messages: list[Message],
+        system: str | None = None,
+        tools: list[Any] | None = None,
+    ) -> AsyncIterator[dict[str, Any]]:
+        """Make a streaming request to the OpenAI API.
+
+        Args:
+            messages: List of voxagent Message objects.
+            system: Optional system prompt.
+            tools: Optional list of tool definitions.
+
+        Yields:
+            Parsed JSON chunks from the SSE stream.
+        """
+        body = self._build_request_body(messages, system=system, tools=tools, stream=True)
+
+        async with httpx.AsyncClient() as client:
+            async with client.stream(
+                "POST",
+                self._get_api_url(),
+                headers=self._get_headers(),
+                json=body,
+                timeout=60.0,
+            ) as response:
+                response.raise_for_status()
+                async for line in response.aiter_lines():
+                    if not line:
+                        continue
+                    if line.startswith("data: "):
+                        data = line[6:]
+                        if data == "[DONE]":
+                            return
+                        try:
+                            yield json.loads(data)
+                        except json.JSONDecodeError:
+                            continue
+
+    async def stream(
+        self,
+        messages: list[Message],
+        system: str | None = None,
+        tools: list[Any] | None = None,
+        abort_signal: AbortSignal | None = None,
+    ) -> AsyncIterator[StreamChunk]:
+        """Stream a response from the OpenAI API.
+
+        Args:
+            messages: The conversation messages.
+            system: Optional system prompt.
+            tools: Optional list of tool definitions.
+            abort_signal: Optional signal to abort the stream.
+
+        Yields:
+            StreamChunk objects containing response data.
+        """
+        # Track tool calls being built across chunks
+        pending_tool_calls: dict[int, dict[str, Any]] = {}
+
+        try:
+            async for chunk in self._make_streaming_request(messages, system=system, tools=tools):
+                # Check abort signal
+                if abort_signal and abort_signal.aborted:
+                    return
+
+                choices = chunk.get("choices", [])
+                if not choices:
+                    continue
+
+                choice = choices[0]
+                delta = choice.get("delta", {})
+                finish_reason = choice.get("finish_reason")
+
+                # Handle content delta
+                if "content" in delta and delta["content"]:
+                    yield TextDeltaChunk(delta=delta["content"])
+
+                # Handle tool calls
+                if "tool_calls" in delta:
+                    for tc_delta in delta["tool_calls"]:
+                        idx = tc_delta.get("index", 0)
+                        if idx not in pending_tool_calls:
+                            pending_tool_calls[idx] = {
+                                "id": tc_delta.get("id", ""),
+                                "name": tc_delta.get("function", {}).get("name", ""),
+                                "arguments": "",
+                            }
+                        else:
+                            if tc_delta.get("id"):
+                                pending_tool_calls[idx]["id"] = tc_delta["id"]
+                            if tc_delta.get("function", {}).get("name"):
+                                pending_tool_calls[idx]["name"] = tc_delta["function"]["name"]
+
+                        # Accumulate arguments
+                        if tc_delta.get("function", {}).get("arguments"):
+                            pending_tool_calls[idx]["arguments"] += tc_delta["function"]["arguments"]
+
+                # Handle finish
+                if finish_reason:
+                    # Emit any pending tool calls
+                    for tc_data in pending_tool_calls.values():
+                        params = {}
+                        if tc_data["arguments"]:
+                            try:
+                                params = json.loads(tc_data["arguments"])
+                            except json.JSONDecodeError:
+                                params = {}
+                        yield ToolUseChunk(
+                            tool_call=ToolCall(
+                                id=tc_data["id"],
+                                name=tc_data["name"],
+                                params=params,
+                            )
+                        )
+                    yield MessageEndChunk()
+                    return
+
+        except Exception as e:
+            yield ErrorChunk(error=str(e))
+
+    async def complete(
+        self,
+        messages: list[Message],
+        system: str | None = None,
+        tools: list[Any] | None = None,
+    ) -> Message:
+        """Get a complete response from the OpenAI API.
+
+        Args:
+            messages: The conversation messages.
+            system: Optional system prompt.
+            tools: Optional list of tool definitions.
+
+        Returns:
+            The assistant's response message.
+
+        Raises:
+            Exception: If the API request fails.
+        """
+        response = await self._make_request(messages, system=system, tools=tools)
+        choices = response.get("choices", [])
+        if not choices:
+            return Message(role="assistant", content="")
+
+        return self._convert_openai_response_to_message(choices[0]["message"])
+
+    def count_tokens(
+        self,
+        messages: list[Message],
+        system: str | None = None,
+    ) -> int:
+        """Count tokens in the messages.
+
+        Uses tiktoken if available, otherwise falls back to character-based estimation.
+
+        Args:
+            messages: The conversation messages.
+            system: Optional system prompt.
+
+        Returns:
+            The estimated token count.
+        """
+        try:
+            import tiktoken
+
+            encoding = tiktoken.encoding_for_model(self._model)
+        except (ImportError, KeyError):
+            # Fall back to character-based estimation (roughly 4 chars per token)
+            total_chars = 0
+            if system:
+                total_chars += len(system)
+            for msg in messages:
+                if isinstance(msg.content, str):
+                    total_chars += len(msg.content)
+                else:
+                    for block in msg.content:
+                        if hasattr(block, "text"):
+                            total_chars += len(block.text)
+            return max(1, total_chars // 4)
+
+        # Use tiktoken for accurate counting
+        total_tokens = 0
+
+        if system:
+            total_tokens += len(encoding.encode(system))
+            total_tokens += 4  # Overhead for system message
+
+        for msg in messages:
+            total_tokens += 4  # Message overhead
+            if isinstance(msg.content, str):
+                total_tokens += len(encoding.encode(msg.content))
+            else:
+                for block in msg.content:
+                    if hasattr(block, "text"):
+                        total_tokens += len(encoding.encode(block.text))
+
+        total_tokens += 2  # Response priming
+        return total_tokens
+
+
+__all__ = ["OpenAIProvider"]
+

voxagent/providers/registry.py

@@ -0,0 +1,175 @@
+"""Provider registry for managing and instantiating LLM providers.
+
+This module provides:
+- ProviderRegistry for registering and looking up provider classes
+- get_default_registry() for accessing a global singleton registry
+- Exceptions for registry-related errors
+"""
+
+from typing import Any
+
+from voxagent.providers.base import BaseProvider
+
+
+# =============================================================================
+# Exceptions
+# =============================================================================
+
+
+class ProviderNotFoundError(Exception):
+    """Raised when a provider is not found in the registry."""
+
+    pass
+
+
+class InvalidModelStringError(Exception):
+    """Raised when a model string is malformed."""
+
+    pass
+
+
+# =============================================================================
+# Provider Registry
+# =============================================================================
+
+
+class ProviderRegistry:
+    """Registry for managing LLM provider classes.
+
+    Provides functionality to register, unregister, and look up provider classes
+    by name. Also supports instantiating providers from model strings in the
+    format "provider:model".
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty provider registry."""
+        self._providers: dict[str, type[BaseProvider]] = {}
+
+    def register(self, name: str, provider_class: type[BaseProvider]) -> None:
+        """Register a provider class by name.
+
+        Args:
+            name: The provider name (must be non-empty, non-whitespace).
+            provider_class: The provider class (must be a BaseProvider subclass).
+
+        Raises:
+            ValueError: If name is empty or whitespace-only.
+            TypeError: If provider_class is not a BaseProvider subclass.
+        """
+        if not name or not name.strip():
+            raise ValueError("Provider name cannot be empty or whitespace-only")
+
+        if not isinstance(provider_class, type) or not issubclass(
+            provider_class, BaseProvider
+        ):
+            raise TypeError("provider_class must be a subclass of BaseProvider")
+
+        self._providers[name] = provider_class
+
+    def unregister(self, name: str) -> None:
+        """Remove a provider from the registry.
+
+        Args:
+            name: The provider name to unregister.
+
+        Raises:
+            ProviderNotFoundError: If the provider is not registered.
+        """
+        if name not in self._providers:
+            raise ProviderNotFoundError(name)
+        del self._providers[name]
+
+    def is_registered(self, name: str) -> bool:
+        """Check if a provider is registered.
+
+        Args:
+            name: The provider name to check.
+
+        Returns:
+            True if the provider is registered, False otherwise.
+        """
+        return name in self._providers
+
+    def get_provider_class(self, name: str) -> type[BaseProvider]:
+        """Get a provider class by name.
+
+        Args:
+            name: The provider name.
+
+        Returns:
+            The registered provider class.
+
+        Raises:
+            ProviderNotFoundError: If the provider is not found.
+        """
+        if name not in self._providers:
+            raise ProviderNotFoundError(name)
+        return self._providers[name]
+
+    def list_providers(self) -> list[str]:
+        """List all registered provider names.
+
+        Returns:
+            A copy of the list of registered provider names.
+        """
+        return list(self._providers.keys())
+
+    def get_provider(self, model_string: str, **kwargs: Any) -> BaseProvider:
+        """Parse model string and instantiate provider.
+
+        Args:
+            model_string: Format "provider:model" (e.g., "openai:gpt-4o").
+                Handles multiple colons: first part is provider, rest is model.
+                e.g., "ollama:model:latest" → provider="ollama", model="model:latest"
+            **kwargs: Additional arguments to pass to provider constructor.
+
+        Returns:
+            Instantiated provider.
+
+        Raises:
+            InvalidModelStringError: If model_string is malformed.
+            ProviderNotFoundError: If provider is not registered.
+        """
+        if not model_string or ":" not in model_string:
+            raise InvalidModelStringError(model_string)
+
+        # Split on first colon only
+        parts = model_string.split(":", 1)
+        provider_name = parts[0]
+        model_name = parts[1] if len(parts) > 1 else ""
+
+        if not provider_name:
+            raise InvalidModelStringError(model_string)
+        if not model_name:
+            raise InvalidModelStringError(model_string)
+
+        provider_class = self.get_provider_class(provider_name)
+        return provider_class(model=model_name, **kwargs)
+
+
+# =============================================================================
+# Default Registry Singleton
+# =============================================================================
+
+_default_registry: ProviderRegistry | None = None
+
+
+def get_default_registry() -> ProviderRegistry:
+    """Get the default global provider registry.
+
+    Returns:
+        The singleton ProviderRegistry instance.
+    """
+    global _default_registry
+    if _default_registry is None:
+        _default_registry = ProviderRegistry()
+    return _default_registry
+
+
+__all__ = [
+    "InvalidModelStringError",
+    "ProviderNotFoundError",
+    "ProviderRegistry",
+    "get_default_registry",
+]
+

voxagent/py.typed

@@ -0,0 +1 @@
+

voxagent/security/__init__.py

@@ -0,0 +1,14 @@
+"""Security module for voxagent."""
+
+from voxagent.security.events import SecurityEvent, SecurityEventEmitter
+from voxagent.security.filter import RedactionFilter, StreamFilter
+from voxagent.security.registry import SecretRegistry
+
+__all__ = [
+    "RedactionFilter",
+    "SecretRegistry",
+    "SecurityEvent",
+    "SecurityEventEmitter",
+    "StreamFilter",
+]
+

voxagent/security/events.py

@@ -0,0 +1,75 @@
+"""Security events for voxagent."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Callable
+
+
+class SecurityEvent(Enum):
+    """Security-related events."""
+
+    SECRET_REDACTED = "secret_redacted"
+    CREDENTIAL_ACCESSED = "credential_accessed"
+    PATTERN_MATCHED = "pattern_matched"
+
+
+class SecurityEventEmitter:
+    """Emits security events to listeners."""
+
+    def __init__(self) -> None:
+        """Initialize an empty event emitter."""
+        self._listeners: dict[
+            SecurityEvent, list[Callable[[dict[str, Any]], None]]
+        ] = {}
+
+    def on(
+        self,
+        event: SecurityEvent,
+        callback: Callable[[dict[str, Any]], None],
+    ) -> Callable[[], None]:
+        """Register a listener for an event.
+
+        Args:
+            event: The security event type to listen for.
+            callback: Function to call when the event is emitted.
+
+        Returns:
+            An unsubscribe function that removes the listener.
+        """
+        if event not in self._listeners:
+            self._listeners[event] = []
+
+        self._listeners[event].append(callback)
+
+        def unsubscribe() -> None:
+            if event in self._listeners and callback in self._listeners[event]:
+                self._listeners[event].remove(callback)
+
+        return unsubscribe
+
+    def emit(self, event: SecurityEvent, data: dict[str, Any]) -> None:
+        """Emit an event to all registered listeners.
+
+        Args:
+            event: The security event type to emit.
+            data: Event data to pass to listeners.
+        """
+        if event in self._listeners:
+            for callback in self._listeners[event]:
+                callback(data)
+
+    def off(
+        self,
+        event: SecurityEvent,
+        callback: Callable[[dict[str, Any]], None],
+    ) -> None:
+        """Remove a specific listener.
+
+        Args:
+            event: The security event type.
+            callback: The callback to remove.
+        """
+        if event in self._listeners and callback in self._listeners[event]:
+            self._listeners[event].remove(callback)
+