voicerun_completions 0.1.2__py3-none-any.whl

voicerun_completions/providers/anthropic/utils.py

@@ -0,0 +1,193 @@
+import json
+from typing import Optional, List, Union
+from anthropic.types import (
+    MessageParam as AnthropicMessage,
+    ToolParam as AnthropicToolDefinition,
+    ToolChoiceParam as AnthropicToolChoice,
+    ContentBlock as AnthropicContentBlock,
+    TextBlockParam as AnthropicTextBlock,
+    ToolUseBlockParam as AnthropicToolCall,
+    ToolResultBlockParam as AnthropicToolResult,
+    ToolChoiceAutoParam as AnthropicToolChoiceAuto,
+    ToolChoiceAnyParam as AnthropicToolChoiceAny,
+    ToolChoiceNoneParam as AnthropicToolChoiceNone,
+    ToolChoiceToolParam as AnthropicToolChoiceToolName,
+    CacheControlEphemeralParam as AnthropicCacheControl,
+)
+from primfunctions.completions.messages import (
+  ConversationHistory,
+  UserMessage,
+  AssistantMessage,
+  SystemMessage,
+  ToolResultMessage,
+  ToolCall,
+)
+from primfunctions.completions.request import ToolChoice, ToolDefinition
+
+
+def denormalize_tool_calls(normalized_tool_calls: Optional[List[ToolCall]]) -> list[AnthropicToolCall]:
+    """TODO"""
+
+    tool_calls: Optional[list[AnthropicToolCall]] = None
+    if normalized_tool_calls:
+        tool_calls = []
+        for tc in normalized_tool_calls:
+            tool_call: AnthropicToolCall = {
+                "type": "tool_use",
+                "id": tc.id,
+                "name": tc.function.name,
+                "input": tc.function.arguments,
+            }
+            tool_calls.append(tool_call)
+
+    return tool_calls
+
+
+def denormalize_conversation_history(normalized_messages: ConversationHistory) -> tuple[list[AnthropicMessage], Optional[list[AnthropicTextBlock]]]:
+    """Convert normalized Message objects to Anthropic MessageParam format.
+
+    Returns:
+        Tuple of (messages, system_prompt) since Anthropic handles system prompts separately
+    """
+
+    messages: list[AnthropicMessage] = []
+    system_messages: list[AnthropicTextBlock] = []
+
+    i = 0
+    while i < len(normalized_messages):
+        msg = normalized_messages[i]
+
+        match msg:
+            case UserMessage():
+                # User messages: simple content handling
+                user_message: AnthropicMessage = {
+                    "role": "user",
+                    "content": [
+                        AnthropicTextBlock(
+                            type="text",
+                            text=msg.content or "",
+                            cache_control=AnthropicCacheControl(
+                                type="ephemeral",
+                                ttl=msg.cache_breakpoint.ttl,
+                            ) if msg.cache_breakpoint else None
+                        )
+                    ],
+                }
+                messages.append(user_message)
+                i += 1
+            case AssistantMessage():
+                # Build content blocks
+                content_blocks: list[AnthropicContentBlock] = []
+
+                # Add text content if present
+                if msg.content:
+                    content_blocks.append(AnthropicTextBlock(
+                        type="text",
+                        text=msg.content,
+                    ))
+
+                # Add tool calls
+                if msg.tool_calls:
+                    tool_calls = denormalize_tool_calls(msg.tool_calls)
+                    if tool_calls:
+                        content_blocks.extend(tool_calls)
+
+                # Capture cache control of assistant message
+                cache_control = AnthropicCacheControl(
+                    type="ephemeral",
+                    ttl=msg.cache_breakpoint.ttl,
+                ) if msg.cache_breakpoint else None
+
+                # Add cache control to final block if present and blocks exist
+                if cache_control and content_blocks:
+                    final_block: Union[AnthropicTextBlock, AnthropicToolCall] = content_blocks[-1]
+                    final_block["cache_control"] = cache_control
+
+                assistant_message: AnthropicMessage = {
+                    "role": "assistant",
+                    "content": content_blocks
+                }
+
+                messages.append(assistant_message)
+                i += 1
+            case SystemMessage():
+                # Collect all system and developer messages
+                system_messages.append(
+                    AnthropicTextBlock(
+                        type="text",
+                        text=msg.content or "",
+                        cache_control=AnthropicCacheControl(
+                            type="ephemeral",
+                            ttl=msg.cache_breakpoint.ttl,
+                        ) if msg.cache_breakpoint else None
+                    )
+                )
+                i += 1
+            case ToolResultMessage():
+                # Look ahead to group consecutive tool messages into a single user message
+                tool_results: list[AnthropicToolResult] = []
+                while i < len(normalized_messages) and normalized_messages[i].role == "tool":
+                    tool_msg: ToolResultMessage = normalized_messages[i]
+                    tool_results.append(AnthropicToolResult(
+                        type="tool_result",
+                        tool_use_id=tool_msg.tool_call_id,
+                        content=json.dumps(tool_msg.content),
+                        cache_control=AnthropicCacheControl(
+                            type="ephemeral",
+                            ttl=tool_msg.cache_breakpoint.ttl,
+                        ) if tool_msg.cache_breakpoint else None
+                    ))
+                    i += 1
+
+                # Create user message with all tool results
+                user_message: AnthropicMessage = {
+                    "role": "user",
+                    "content": tool_results
+                }
+                messages.append(user_message)
+            case _:
+                # Skip unsupported roles
+                i += 1
+
+    # Capture system prompt as list of TextBlocks
+    system_prompt: list[AnthropicTextBlock] = system_messages or None
+
+    return messages, system_prompt
+
+
+def denormalize_tools(normalized_tools: Optional[list[ToolDefinition]]) -> Optional[list[AnthropicToolDefinition]]:
+    """Convert normalized Tool objects to Anthropic ToolParam format."""
+
+    tools: Optional[list[AnthropicToolDefinition]] = None
+    if normalized_tools:
+        tools = []
+        for tool in normalized_tools:
+            tool_def: AnthropicToolDefinition = {
+                "name": tool.function.name,
+                "description": tool.function.description,
+                "input_schema": tool.function.parameters,
+            }
+            tools.append(tool_def)
+
+    return tools
+
+
+def denormalize_tool_choice(normalized_tool_choice: Optional[ToolChoice]) -> Optional[AnthropicToolChoice]:
+    """Convert normalized ToolChoice to Anthropic ToolChoiceParam format."""
+
+    if not normalized_tool_choice:
+        return None
+
+    # Map our normalized tool choice to Anthropic's format using proper SDK types
+    if normalized_tool_choice == "auto":
+        return AnthropicToolChoiceAuto(type="auto")
+    elif normalized_tool_choice == "none":
+        return AnthropicToolChoiceNone(type="none")
+    elif normalized_tool_choice == "required":
+        return AnthropicToolChoiceAny(type="any")  # Anthropic uses "any" for required
+    else:
+        # Specific tool name - use ToolChoiceToolParam
+        return AnthropicToolChoiceToolName(
+            type="tool",
+            name=normalized_tool_choice
+        )

voicerun_completions/providers/base.py

@@ -0,0 +1,145 @@
+import json
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, AsyncIterable, Optional
+from primfunctions.completions.streaming import ChatCompletionChunk
+from primfunctions.completions.response import ChatCompletionResponse
+from primfunctions.completions.request import ChatCompletionRequest, StreamOptions
+from primfunctions.completions.messages import ToolCall, FunctionCall
+
+
+@dataclass
+class PartialToolCall:
+    """Internal state for accumulating tool call data."""
+    id: str
+    type: str
+    function_name: str
+    arguments_buffer: str = ""
+    index: Optional[int] = None
+
+    def is_complete(self) -> bool:
+        """Check if the accumulated arguments form valid JSON."""
+        # TODO: better way of doing this?
+        try:
+            json.loads(self.arguments_buffer)
+            return True
+        except json.JSONDecodeError:
+            return False
+        
+    def to_tool_call(self) -> ToolCall:
+        """Convert this partial to ToolCall. Empty arguments if invalid json."""
+
+        arguments = {}
+        try:
+            arguments = json.loads(self.arguments_buffer)
+        except:
+            # Received invalid json arguments
+            pass
+
+        return ToolCall(
+            id=self.id,
+            type=self.type,
+            function=FunctionCall(
+                name=self.function_name,
+                arguments=arguments,
+            ),
+            index=self.index,
+        )
+
+
+class StreamProcessor(ABC):
+    """Processes LLM provider specific completion stream and returns ChatCompletionChunks to yield to client.
+    Accumulates streaming tool call deltas and emits complete tool calls.
+    """
+
+    @abstractmethod
+    async def process_stream(
+        self,
+        stream: AsyncIterable[Any]
+    ) -> AsyncIterable[ChatCompletionChunk]:
+        """Process a stream of provider completion chunks and yield normalized chunks."""
+        pass
+
+
+class CompletionClient(ABC):
+    """Abstract base class for LLM completion clients."""
+
+    @abstractmethod
+    def _denormalize_request(
+        self,
+        request: ChatCompletionRequest,
+    ) -> dict[str, Any]:
+        pass
+
+
+    @abstractmethod
+    def _normalize_response(
+        self,
+        response: Any,
+    ) -> ChatCompletionResponse:
+        pass
+
+
+    @abstractmethod
+    async def _get_completion(
+        self,
+        **kwargs
+    ) -> Any:
+        pass
+
+
+    @abstractmethod
+    async def _get_completion_stream(
+        self,
+        **kwargs
+    ) -> AsyncIterable[Any]:
+        """Get streaming completion from provider."""
+        pass
+
+
+    @abstractmethod
+    def _get_stream_processor(
+        self,
+        stream_options: Optional[StreamOptions] = None,
+    ) -> StreamProcessor:
+        """Get provider-specific StreamProcessor."""
+        pass
+
+
+    async def generate_chat_completion(
+        self,
+        request: ChatCompletionRequest,
+    ) -> ChatCompletionResponse:
+        """
+        Generate chat completion.
+
+        Args:
+            request: Normalized chat completion request
+
+        Returns:
+            ChatCompletionResponse with normalized data
+        """
+        denormalized_request = self._denormalize_request(request)
+        completion = await self._get_completion(**denormalized_request)
+        return self._normalize_response(completion)
+
+
+    async def generate_chat_completion_stream(
+        self,
+        request: ChatCompletionRequest,
+    ) -> AsyncIterable[ChatCompletionChunk]:
+        """
+        Generate streaming chat completion.
+
+        Args:
+            request: Normalized chat completion request with streaming=True
+
+        Returns:
+            AsyncIterable of ChatCompletionStreamChunk with normalized data
+        """
+        denormalized_request = self._denormalize_request(request)
+        processor = self._get_stream_processor(request.stream_options)
+        completion_stream = await self._get_completion_stream(**denormalized_request)
+
+        async for normalized_chunk in processor.process_stream(completion_stream):
+            yield normalized_chunk

voicerun_completions/providers/google/google_client.py

@@ -0,0 +1,165 @@
+from typing import Any, AsyncIterator, Optional
+from google.genai import Client
+from google.genai.types import (
+    Candidate as GoogleResponseCandidate,
+    Content as GoogleMessageContent,
+    Part as GoogleMessagePart,
+    GenerateContentResponse as GoogleContentResponse,
+    GenerateContentConfigDict as GoogleRequestConfigDict,
+    ThinkingConfigDict as GoogleThinkingConfigDict,
+)
+from primfunctions.completions.messages import AssistantMessage, FunctionCall, ToolCall
+from primfunctions.completions.response import ChatCompletionResponse
+from primfunctions.completions.request import ChatCompletionRequest, StreamOptions
+
+from ..base import CompletionClient
+from .utils import denormalize_conversation_history, denormalize_tools, denormalize_tool_choice
+from .streaming import GoogleStreamProcessor
+
+
+class GoogleCompletionClient(CompletionClient):
+
+    def _denormalize_request(
+        self,
+        request: ChatCompletionRequest,
+    ) -> dict[str, Any]:
+        """Convert ChatCompletionRequest to kwargs for _get_completion."""
+
+        contents, system_instruction = denormalize_conversation_history(request.messages)
+
+        kwargs = {
+            "api_key": request.api_key,
+            "model": request.model,
+            "contents": contents,
+        }
+
+        # Build config using GenerateContentConfigDict
+        config_dict = {}
+
+        if request.temperature is not None:
+            config_dict["temperature"] = request.temperature
+
+        if request.max_tokens is not None:
+            config_dict["max_output_tokens"] = request.max_tokens
+
+        if request.tools:
+            config_dict["tools"] = denormalize_tools(request.tools)
+
+        if request.tool_choice:
+            tool_config = denormalize_tool_choice(request.tool_choice)
+            if tool_config:
+                config_dict["tool_config"] = tool_config
+        
+        if request.timeout is not None:
+            # Google takes timeout in ms
+            timeout_ms: int = request.timeout * 1000
+            config_dict["http_options"] = {
+                "timeout": timeout_ms
+            }
+
+        # Add system instruction if present
+        if system_instruction:
+            config_dict["system_instruction"] = system_instruction
+
+        # Disable thinking to improve streaming latency
+        config_dict["thinking_config"] = GoogleThinkingConfigDict(
+            thinking_budget=0,  # 0 = DISABLED
+            include_thoughts=False
+        )
+
+        # Only add config if it has values
+        if config_dict:
+            kwargs["config"] = GoogleRequestConfigDict(**config_dict)
+
+        return kwargs
+
+    def _normalize_response(
+        self,
+        response: GoogleContentResponse,
+    ) -> ChatCompletionResponse:
+
+        # Take only first candidate
+        candidate: GoogleResponseCandidate = response.candidates[0]
+        google_message: GoogleMessageContent = candidate.content
+        google_message_parts: list[GoogleMessagePart] = google_message.parts
+
+        # Extract text and function calls from parts
+        text_parts: list[str] = []
+        tool_calls: list[ToolCall] = []
+        tool_call_index: int = 0
+
+        for part in google_message_parts:
+            if part.text:
+                text_parts.append(part.text)
+            elif part.function_call:
+                # Convert function call to ToolCall
+                tool_calls.append(ToolCall(
+                    id=part.function_call.id,
+                    type="function",
+                    function=FunctionCall(
+                        name=part.function_call.name,
+                        arguments=part.function_call.args
+                    ),
+                    index=tool_call_index,
+                ))
+                tool_call_index += 1
+
+        # Combine text content
+        content = "".join(text_parts) if text_parts else None
+
+        normalized_message = AssistantMessage(
+            content=content,
+            tool_calls=tool_calls if tool_calls else None
+        )
+
+        return ChatCompletionResponse(
+            message=normalized_message,
+            finish_reason=candidate.finish_reason,
+            usage=response.usage_metadata.model_dump() if response.usage_metadata else None
+        )
+
+    async def _get_completion(
+        self,
+        api_key: str,
+        model: str,
+        contents: list[GoogleMessageContent],
+        config: Optional[GoogleRequestConfigDict] = None,
+    ) -> GoogleContentResponse:
+        """Generate content using Google Gen AI client.
+
+        [Client](https://github.com/googleapis/python-genai)
+        """
+
+        async with Client(api_key=api_key).aio as async_client:
+            return await async_client.models.generate_content(
+                model=model,
+                contents=contents,
+                config=config,
+            )
+
+
+    def _get_stream_processor(
+        self,
+        stream_options: Optional[StreamOptions] = None,
+    ) -> GoogleStreamProcessor:
+        """Get anthropic-specific StreamProcessor."""
+        return GoogleStreamProcessor(stream_options=stream_options)
+
+
+    async def _get_completion_stream(
+        self,
+        api_key: str,
+        model: str,
+        contents: list[GoogleMessageContent],
+        config: Optional[GoogleRequestConfigDict] = None,
+    ) -> AsyncIterator[GoogleContentResponse]:
+        """Stream chat completion events from Google.
+
+        [Client](https://github.com/googleapis/python-genai)
+        """
+        client = Client(api_key=api_key)
+        return await client.aio.models.generate_content_stream(
+            model=model,
+            contents=contents,
+            config=config,
+        )

voicerun_completions/providers/google/streaming.py

@@ -0,0 +1,177 @@
+import httpx
+from typing import Any, AsyncIterable, Dict, List, Optional
+from google.genai.types import (
+    Candidate as GoogleResponseCandidate,
+    GenerateContentResponse as GoogleResponseChunk,
+    Content as GoogleMessageContent,
+    Part as GoogleMessagePart,
+)
+from primfunctions.completions.messages import ToolCall, FunctionCall, AssistantMessage
+from primfunctions.completions.response import ChatCompletionResponse
+from primfunctions.completions.streaming import (
+    ChatCompletionChunk,
+    AssistantMessageDeltaChunk,
+    AssistantMessageSentenceChunk,
+    FinishReasonChunk,
+    ToolCallChunk,
+    UsageChunk,
+    FinalResponseChunk,
+)
+from primfunctions.utils.streaming import update_sentence_buffer, clean_text_for_speech
+from primfunctions.completions.request import StreamOptions
+
+from ..base import StreamProcessor, PartialToolCall
+
+
+class GoogleStreamProcessor(StreamProcessor):
+    """Processes Google message stream events yielding normalized chunks."""
+
+    def __init__(
+        self,
+        stream_options: Optional[StreamOptions] = None,
+    ):
+        self.stream_sentences: bool = False
+        self.clean_sentences: bool = True
+        self.min_sentence_length: int = 6
+        self.punctuation_marks: Optional[list[str]] = None
+        self.punctuation_language: Optional[str] = None
+
+        # Override stream options defaults
+        if stream_options:
+            self.stream_sentences = stream_options.stream_sentences
+            self.clean_sentences = stream_options.clean_sentences
+            self.min_sentence_length = stream_options.min_sentence_length
+            self.punctuation_marks = stream_options.punctuation_marks
+            self.punctuation_language = stream_options.punctuation_language
+
+        self.active_calls: Dict[int, PartialToolCall] = {}
+        self.content: str = ""
+        self.tool_calls: List[ToolCall] = []
+        self.finish_reason: str = ""
+        self.usage: Dict[str, Any] = {}
+        self.sentence_buffer = ""
+        self.current_block_index = 0
+
+
+    def _process_chunk(
+        self,
+        chunk: GoogleResponseChunk,
+    ) -> List[ChatCompletionChunk]:
+        """Convert Google ContentResponse to individual typed chunks."""
+        chunks = []
+
+        # Handle usage information
+        if chunk.usage_metadata:
+            # TODO: ensure cumulative
+            self.usage = chunk.usage_metadata.model_dump()
+
+        # Handle candidates
+        if not chunk.candidates:
+            return chunks
+
+        # Take only first candidate (Google pattern)
+        candidate: GoogleResponseCandidate = chunk.candidates[0]
+        content: GoogleMessageContent = candidate.content
+        parts: list[GoogleMessagePart] = content.parts
+
+        # Handle finish reason
+        if candidate.finish_reason:
+            self.finish_reason = candidate.finish_reason.value.lower()
+
+        # Process each part in the content
+        for part in parts:
+            # Handle text content
+            if part.text:
+                chunks.extend(self._process_text_partial(part.text))
+
+            # Handle function calls (tool calls)
+            elif part.function_call:
+                # Google returns complete function calls, not deltas
+                tool_call = ToolCall(
+                    id=part.function_call.id or f"call_{self.current_block_index}",
+                    type="function",
+                    function=FunctionCall(
+                        name=part.function_call.name,
+                        arguments=part.function_call.args,
+                    ),
+                    index=self.current_block_index,
+                )
+
+                chunks.append(ToolCallChunk(tool_call=tool_call))
+                self.tool_calls.append(tool_call)
+                self.current_block_index += 1
+
+        return chunks
+
+    def _process_text_partial(self, text: str) -> List[ChatCompletionChunk]:
+        """Process text content and return appropriate chunks."""
+        chunks = []
+
+        if self.stream_sentences:
+            # Append delta to sentence buffer
+            sentence_buffer, complete_sentence = update_sentence_buffer(
+                content=text,
+                sentence_buffer=self.sentence_buffer,
+                punctuation_marks=self.punctuation_marks,
+                clean_text=self.clean_sentences,
+                min_sentence_length=self.min_sentence_length,
+            )
+            self.sentence_buffer = sentence_buffer
+
+            if complete_sentence:
+                chunks.append(AssistantMessageSentenceChunk(
+                    sentence=complete_sentence
+                ))
+        else:
+            # Otherwise stream content delta directly
+            chunks.append(AssistantMessageDeltaChunk(
+                content=text
+            ))
+
+        # Add content delta to accumulated response
+        self.content += text
+
+        return chunks
+
+    async def process_stream(
+        self,
+        stream: AsyncIterable[GoogleResponseChunk],
+    ) -> AsyncIterable[ChatCompletionChunk]:
+        """Process Google event stream and yield normalized chunks."""
+        try:
+            async for event in stream:
+                for chunk in self._process_chunk(event):
+                    yield chunk
+        except Exception as e:
+            # Handle Google API connection issues that occur after successful content delivery
+            if isinstance(e, httpx.ReadError) and str(e) == '':
+                # This is a known issue with Google's streaming API - ignore empty ReadErrors
+                # that occur after content has been successfully delivered
+                pass
+            else:
+                raise
+
+        # Handle remaining sentence buffer if streaming sentences
+        if self.stream_sentences and self.sentence_buffer:
+            complete_sentence = clean_text_for_speech(self.sentence_buffer) if self.clean_sentences else self.sentence_buffer
+            yield AssistantMessageSentenceChunk(
+                sentence=complete_sentence
+            )
+
+        # Yield the finish chunk (or default)
+        yield FinishReasonChunk(finish_reason=self.finish_reason or "stop")
+
+        # Yield the usage chunk
+        yield UsageChunk(usage=self.usage)
+
+        # Yield aggregated chat completion response as final chunk
+        yield FinalResponseChunk(
+            response=ChatCompletionResponse(
+                message=AssistantMessage(
+                    content=self.content or None,
+                    tool_calls=self.tool_calls or None,
+                ),
+                usage=self.usage,
+                finish_reason=self.finish_reason,
+            )
+        )