voicerun_completions 0.1.2__py3-none-any.whl

voicerun_completions/client.py

@@ -0,0 +1,165 @@
+from typing import Any, Optional, Union, AsyncIterable
+from primfunctions.completions.request import (
+    CompletionsProvider,
+    ChatCompletionRequest,
+    StreamOptions,
+    ToolChoice,
+    ToolDefinition,
+    normalize_tools,
+)
+from primfunctions.completions.messages import ConversationHistory, normalize_messages
+from primfunctions.completions.streaming import ChatCompletionChunk
+from primfunctions.completions.response import ChatCompletionResponse
+
+from .providers.base import CompletionClient
+from .providers.openai.openai_client import OpenAiCompletionClient
+from .providers.anthropic.anthropic_client import AnthropicCompletionClient
+from .providers.google.google_client import GoogleCompletionClient
+
+
+async def generate_chat_completion(
+    provider: Union[str, CompletionsProvider],
+    api_key: str,
+    model: str,
+    messages: Union[ConversationHistory, list[dict]],
+    *,
+    tools: Optional[list[Union[ToolDefinition, dict[str, Any]]]] = None,
+    tool_choice: Optional[ToolChoice] = None,
+    temperature: Optional[float] = None,
+    timeout: Optional[float] = None,
+    max_tokens: Optional[int] = None,
+) -> ChatCompletionResponse:
+    """
+    Generate chat completion.
+
+    Args:
+        provider: LLM provider ("openai", "anthropic", or "google")
+        api_key: API key for the provider
+        model: Model identifier (provider-specific)
+        messages: Conversation history or list of message dicts
+        tools: Optional list of tool/function definitions
+        tool_choice: Tool choice strategy ("none", "auto", "required", or tool name)
+        temperature: Sampling temperature (0.0-2.0)
+        timeout: Request timeout in seconds
+        max_tokens: Maximum tokens to generate
+
+    Returns:
+        ChatCompletionResponse with the complete response
+    """
+
+    # Normalize string input to enum
+    if isinstance(provider, str):
+        try:
+            provider = CompletionsProvider(provider.lower())
+        except ValueError:
+            raise ValueError(f"Invalid provider: {provider}.")
+
+    # Normalize messages to proper message objects
+    normalized_messages = normalize_messages(messages)
+
+    # Normalize tools to proper tool objects
+    normalized_tools = normalize_tools(tools) if tools else None
+
+    client: CompletionClient
+    if provider == CompletionsProvider.OPENAI:
+        client = OpenAiCompletionClient()
+    elif provider == CompletionsProvider.ANTHROPIC:
+        client = AnthropicCompletionClient()
+    elif provider == CompletionsProvider.GOOGLE:
+        client = GoogleCompletionClient()
+    else:
+        raise ValueError(f"Invalid provider: {provider}")
+
+    request = ChatCompletionRequest(
+        provider=provider,
+        api_key=api_key,
+        model=model,
+        messages=normalized_messages,
+        tools=normalized_tools,
+        tool_choice=tool_choice,
+        temperature=temperature,
+        timeout=timeout,
+        max_tokens=max_tokens,
+        streaming=False,
+    )
+
+    return await client.generate_chat_completion(request=request)
+
+
+async def generate_chat_completion_stream(
+    provider: Union[str, CompletionsProvider],
+    api_key: str,
+    model: str,
+    messages: Union[ConversationHistory, list[dict]],
+    *,
+    tools: Optional[list[Union[ToolDefinition, dict[str, Any]]]] = None,
+    tool_choice: Optional[ToolChoice] = None,
+    temperature: Optional[float] = None,
+    timeout: Optional[float] = None,
+    max_tokens: Optional[int] = None,
+    stream_options: Optional[Union[StreamOptions, dict[str, Any]]] = None,
+) -> AsyncIterable[ChatCompletionChunk]:
+    """
+    Generate streaming chat completion.
+
+    Args:
+        provider: LLM provider ("openai", "anthropic", or "google")
+        api_key: API key for the provider
+        model: Model identifier (provider-specific)
+        messages: Conversation history or list of message dicts
+        tools: Optional list of tool/function definitions
+        tool_choice: Tool choice strategy ("none", "auto", "required", or tool name)
+        temperature: Sampling temperature (0.0-2.0)
+        timeout: Request timeout in seconds
+        max_tokens: Maximum tokens to generate
+        stream_options: TODO
+
+    Returns:
+        AsyncIterable of ChatCompletionChunk objects (typed chunks)
+    """
+
+    # Normalize string input to enum
+    if isinstance(provider, str):
+        try:
+            provider = CompletionsProvider(provider.lower())
+        except ValueError:
+            raise ValueError(f"Invalid provider: {provider}.")
+
+    # Normalize messages to proper message objects
+    normalized_messages = normalize_messages(messages)
+
+    # Normalize tools to proper tool objects
+    normalized_tools = normalize_tools(tools) if tools else None
+
+    # Normalize stream options if provided as dict
+    if stream_options and isinstance(stream_options, dict):
+        stream_options = StreamOptions.deserialize(stream_options)
+
+    client: CompletionClient
+    if provider == CompletionsProvider.OPENAI:
+        client = OpenAiCompletionClient()
+    elif provider == CompletionsProvider.ANTHROPIC:
+        client = AnthropicCompletionClient()
+    elif provider == CompletionsProvider.GOOGLE:
+        # TODO: enable once google fixes their SDK
+        raise ValueError(f"Google streaming currently unsupported")
+        # client = GoogleCompletionClient()
+    else:
+        raise ValueError(f"Invalid provider: {provider}")
+
+    request = ChatCompletionRequest(
+        provider=provider,
+        api_key=api_key,
+        model=model,
+        messages=normalized_messages,
+        tools=normalized_tools,
+        tool_choice=tool_choice,
+        temperature=temperature,
+        timeout=timeout,
+        max_tokens=max_tokens,
+        streaming=True,
+        stream_options=stream_options,
+    )
+
+    return client.generate_chat_completion_stream(request=request)
+

voicerun_completions/providers/anthropic/anthropic_client.py

@@ -0,0 +1,192 @@
+from typing import Any, List, Optional
+from anthropic import AsyncAnthropic, AsyncStream
+from anthropic.types import (
+    Message as AnthropicMessage,
+    MessageParam as AnthropicMessageParam,
+    TextBlockParam as AnthropicTextBlockParam,
+    ToolParam as AnthropicToolDefinition,
+    ToolChoiceParam as AnthropicToolChoice,
+    TextBlock as AnthropicTextBlock,
+    ToolUseBlock as AnthropicToolCall,
+    RawMessageStreamEvent as AnthropicStreamEvent,
+)
+from primfunctions.completions.messages import AssistantMessage, ToolCall, FunctionCall
+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 AnthropicStreamProcessor
+
+
+class AnthropicCompletionClient(CompletionClient):
+
+    def _denormalize_request(
+        self,
+        request: ChatCompletionRequest,
+    ) -> dict[str, Any]:
+        """Convert ChatCompletionRequest to kwargs for _get_completion."""
+
+        messages, system_prompt = denormalize_conversation_history(request.messages)
+
+        kwargs = {
+            "api_key": request.api_key,
+            "model": request.model,
+            "messages": messages,
+            "tools": denormalize_tools(request.tools),
+            "tool_choice": denormalize_tool_choice(request.tool_choice),
+            "temperature": request.temperature if request.temperature else None,
+        }
+
+        # Add system prompt if present
+        if system_prompt:
+            kwargs["system"] = system_prompt
+
+        # Include or default required max_tokens
+        kwargs["max_tokens"] = request.max_tokens if request.max_tokens else 4000
+
+        # Include timeout if provided
+        if request.timeout is not None:
+            kwargs["timeout"] = request.timeout
+
+        return kwargs
+
+
+    def _normalize_response(
+        self,
+        response: AnthropicMessage,
+    ) -> ChatCompletionResponse:
+        """Convert Anthropic Message to normalized ChatCompletionResponse."""
+
+        # Extract text content and tool calls from content blocks
+        text_parts: list[str] = []
+        tool_calls: list[ToolCall] = []
+        tool_call_index: int = 0
+
+        for block in response.content:
+            match block:
+                case AnthropicTextBlock():
+                    text_parts.append(block.text)
+                case AnthropicToolCall():
+                    tool_calls.append(ToolCall(
+                        id=block.id,
+                        type="function",
+                        function=FunctionCall(
+                            name=block.name,
+                            arguments=block.input
+                        ),
+                        index=tool_call_index,
+                    ))
+                    tool_call_index += 1
+
+        # Combine text content
+        content = "".join(text_parts) if text_parts else None
+
+        # Create normalized message
+        normalized_message = AssistantMessage(
+            content=content,
+            tool_calls=tool_calls if tool_calls else None,
+        )
+
+        return ChatCompletionResponse(
+            message=normalized_message,
+            finish_reason=response.stop_reason,
+            usage=response.usage.model_dump() if response.usage else None
+        )
+
+
+    async def _get_completion(
+        self,
+        api_key: str,
+        model: str,
+        messages: list[AnthropicMessageParam],
+        max_tokens: int,
+        tools: Optional[list[AnthropicToolDefinition]] = None,
+        tool_choice: Optional[AnthropicToolChoice] = None,
+        temperature: Optional[float] = None,
+        system: Optional[List[AnthropicTextBlockParam]] = None,
+        timeout: Optional[float] = None,
+    ) -> AnthropicMessage:
+        """TODO.
+
+        [Client](https://github.com/anthropics/anthropic-sdk-python)
+        """
+        async with AsyncAnthropic(api_key=api_key) as client:
+            # Build kwargs dict with required values
+            kwargs = {
+                "model": model,
+                "messages": messages,
+                "max_tokens": max_tokens,
+                "stream": False,
+                # Disable thinking
+                "thinking": {
+                    "type": "disabled"
+                },
+            }
+
+            # Only add optional parameters if they're provided
+            if tools is not None:
+                kwargs["tools"] = tools
+            if tool_choice is not None:
+                kwargs["tool_choice"] = tool_choice
+            if temperature is not None:
+                kwargs["temperature"] = temperature
+            if system is not None:
+                kwargs["system"] = system
+            if timeout is not None:
+                kwargs["timeout"] = timeout
+
+            return await client.messages.create(**kwargs)
+
+
+    def _get_stream_processor(
+        self,
+        stream_options: Optional[StreamOptions] = None,
+    ) -> AnthropicStreamProcessor:
+        """Get anthropic-specific StreamProcessor."""
+        return AnthropicStreamProcessor(stream_options=stream_options)
+
+
+    async def _get_completion_stream(
+        self,
+        api_key: str,
+        model: str,
+        messages: list[AnthropicMessageParam],
+        max_tokens: int,
+        tools: Optional[list[AnthropicToolDefinition]] = None,
+        tool_choice: Optional[AnthropicToolChoice] = None,
+        temperature: Optional[float] = None,
+        system: Optional[List[AnthropicTextBlockParam]] = None,
+        timeout: Optional[float] = None,
+    ) -> AsyncStream[AnthropicStreamEvent]:
+        """Stream chat response events from Anthropic.
+
+        [Client](https://github.com/anthropics/anthropic-sdk-python)
+        """
+        client = AsyncAnthropic(api_key=api_key)
+
+        # Build kwargs dict with required values
+        kwargs = {
+            "model": model,
+            "messages": messages,
+            "max_tokens": max_tokens,
+            "stream": True,
+            # Disable thinking
+            "thinking": {
+                "type": "disabled"
+            },
+        }
+
+        # Only add optional parameters if they're provided
+        if tools is not None:
+            kwargs["tools"] = tools
+        if tool_choice is not None:
+            kwargs["tool_choice"] = tool_choice
+        if temperature is not None:
+            kwargs["temperature"] = temperature
+        if system is not None:
+            kwargs["system"] = system
+        if timeout is not None:
+            kwargs["timeout"] = timeout
+
+        return await client.messages.create(**kwargs)

voicerun_completions/providers/anthropic/streaming.py

@@ -0,0 +1,197 @@
+from typing import Any, AsyncIterable, Dict, List, Optional
+from anthropic.types import (
+    RawMessageStreamEvent as AnthropicStreamEvent,
+    RawMessageStartEvent as AnthropicMessageStartEvent,
+    RawContentBlockStartEvent as AnthropicStartEvent,
+    RawContentBlockDeltaEvent as AnthropicContentDeltaEvent,
+    RawMessageDeltaEvent as AnthropicMessageDeltaEvent,
+    TextDelta as AnthropicTextDelta,
+    InputJSONDelta as AnthropicJsonDelta,
+    ToolUseBlock as AnthropicToolCall,
+    TextBlock as AnthropicTextBlock,
+)
+from primfunctions.completions.messages import ToolCall, 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 AnthropicStreamProcessor(StreamProcessor):
+    """Processes Anthropic 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_call: PartialToolCall = None
+        self.active_call_index = 0
+        self.content: str = ""
+        self.tool_calls: List[ToolCall] = []
+        self.finish_reason: str = ""
+        self.usage: Dict[str, Any] = {}
+        self.sentence_buffer = ""
+
+    
+    def _process_text_partial(self, text: str) -> List[ChatCompletionChunk]:
+        """Process text partial."""
+        chunks: List[ChatCompletionChunk] = []
+
+        if not text:
+            return 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
+
+
+    def _process_event(
+        self,
+        event: AnthropicStreamEvent,
+    ) -> List[ChatCompletionChunk]:
+        """Convert Anthropic streaming event to individual typed chunks."""
+        chunks = []
+
+        match event.type:
+            case "message_start":
+                msg_start_event: AnthropicMessageStartEvent = event
+
+                # Capture usage from message start
+                self.usage.update(msg_start_event.message.usage.model_dump())
+
+            case "content_block_start":
+                start_event: AnthropicStartEvent = event
+                
+                # For tool_use blocks, initialize the partial tool call
+                if start_event.content_block.type == "tool_use":
+                    tool_block: AnthropicToolCall = start_event.content_block
+                    self.active_call = PartialToolCall(
+                        id=tool_block.id,
+                        type="function",
+                        function_name=tool_block.name,
+                        arguments_buffer="",
+                        index=self.active_call_index,
+                    )
+                elif start_event.content_block.type == "text":
+                    text_block: AnthropicTextBlock = start_event.content_block
+                    chunks.extend(self._process_text_partial(text_block.text))
+
+            case "content_block_delta":
+                delta_event: AnthropicContentDeltaEvent = event
+
+                if hasattr(delta_event.delta, 'type'):
+                    # Handle text content delta
+                    if delta_event.delta.type == "text_delta":
+                        text_delta: AnthropicTextDelta = delta_event.delta
+                        chunks.extend(self._process_text_partial(text_delta.text))
+
+                    # Handle JSON content delta
+                    if delta_event.delta.type == "input_json_delta" and self.active_call:
+                        json_delta: AnthropicJsonDelta = delta_event.delta
+                        self.active_call.arguments_buffer += json_delta.partial_json
+
+            case "content_block_stop":
+                # Only special handling for tool call
+                if self.active_call:
+                    tool_call = self.active_call.to_tool_call()
+                    chunks.append(ToolCallChunk(tool_call=tool_call))
+                    self.tool_calls.append(tool_call)
+                    self.active_call = None
+                    self.active_call_index += 1
+
+            case "message_delta":
+                msg_delta_event: AnthropicMessageDeltaEvent = event
+
+                # Handle usage information if present
+                if msg_delta_event.usage:
+                    self.usage.update(msg_delta_event.usage.model_dump())
+
+                # Handle finish reason from delta
+                if msg_delta_event.delta.stop_reason:
+                    self.finish_reason = msg_delta_event.delta.stop_reason
+
+            case "message_stop":
+                # End of message - no special handling
+                pass
+
+        return chunks
+
+    async def process_stream(
+        self,
+        stream: AsyncIterable[AnthropicStreamEvent],
+    ) -> AsyncIterable[ChatCompletionChunk]:
+        """Process Anthropic event stream and yield normalized chunks."""
+        async for event in stream:
+            for chunk in self._process_event(event):
+                yield chunk
+
+        # 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,
+            )
+        )