gllm-inference-binary 0.5.65__cp313-cp313-macosx_13_0_arm64.whl

gllm_inference/realtime_chat/google_realtime_chat.pyi

@@ -0,0 +1,205 @@
+import asyncio
+import logging
+from _typeshed import Incomplete
+from gllm_inference.constants import GOOGLE_SCOPES as GOOGLE_SCOPES
+from gllm_inference.realtime_chat.input_streamer import KeyboardInputStreamer as KeyboardInputStreamer
+from gllm_inference.realtime_chat.input_streamer.input_streamer import BaseInputStreamer as BaseInputStreamer
+from gllm_inference.realtime_chat.output_streamer import ConsoleOutputStreamer as ConsoleOutputStreamer
+from gllm_inference.realtime_chat.output_streamer.output_streamer import BaseOutputStreamer as BaseOutputStreamer
+from gllm_inference.realtime_chat.realtime_chat import BaseRealtimeChat as BaseRealtimeChat
+from pydantic import BaseModel
+from typing import Literal
+
+DEFAULT_POST_OUTPUT_AUDIO_DELAY: float
+LIVE_CONNECT_CONFIG: Incomplete
+
+class GoogleIOStreamerState(BaseModel):
+    '''[BETA] Defines the state of the GoogleIOStreamer with thread-safe properties.
+
+    Attributes:
+        is_streaming_output (bool): Whether the output is streaming.
+        console_mode (Literal["input", "user", "assistant"]): The current console mode.
+        terminated (bool): Whether the conversation is terminated.
+    '''
+    is_streaming_output: bool
+    console_mode: Literal['input', 'user', 'assistant']
+    terminated: bool
+    async def set_streaming_output(self, value: bool) -> None:
+        """Thread-safe setter for is_streaming_output.
+
+        Args:
+            value (bool): The value to set for is_streaming_output.
+        """
+    async def get_streaming_output(self) -> bool:
+        """Thread-safe getter for is_streaming_output.
+
+        Returns:
+            bool: The value of is_streaming_output.
+        """
+    async def set_console_mode(self, value: Literal['input', 'user', 'assistant']) -> None:
+        '''Thread-safe setter for console_mode.
+
+        Args:
+            value (Literal["input", "user", "assistant"]): The value to set for console_mode.
+        '''
+    async def get_console_mode(self) -> Literal['input', 'user', 'assistant']:
+        '''Thread-safe getter for console_mode.
+
+        Returns:
+            Literal["input", "user", "assistant"]: The value of console_mode.
+        '''
+    async def set_terminated(self, value: bool) -> None:
+        """Thread-safe setter for terminated.
+
+        Args:
+            value (bool): The value to set for terminated.
+        """
+    async def get_terminated(self) -> bool:
+        """Thread-safe getter for terminated.
+
+        Returns:
+            bool: The value of terminated.
+        """
+
+class GoogleIOStreamer:
+    """[BETA] Defines the GoogleIOStreamer.
+
+    This class manages the realtime conversation lifecycle.
+    It handles the IO operations between the model and the input/output streamers.
+
+    Attributes:
+        session (AsyncSession): The session of the GoogleIOStreamer.
+        task_group (asyncio.TaskGroup): The task group of the GoogleIOStreamer.
+        input_queue (asyncio.Queue): The input queue of the GoogleIOStreamer.
+        output_queue (asyncio.Queue): The output queue of the GoogleIOStreamer.
+        input_streamers (list[BaseInputStreamer]): The input streamers of the GoogleIOStreamer.
+        output_streamers (list[BaseOutputStreamer]): The output streamers of the GoogleIOStreamer.
+        post_output_audio_delay (float): The delay in seconds to post the output audio.
+    """
+    session: AsyncSession
+    task_group: Incomplete
+    input_queue: Incomplete
+    output_queue: Incomplete
+    state: Incomplete
+    input_streamers: Incomplete
+    output_streamers: Incomplete
+    post_output_audio_delay: Incomplete
+    def __init__(self, session: AsyncSession, task_group: asyncio.TaskGroup, input_queue: asyncio.Queue, output_queue: asyncio.Queue, input_streamers: list[BaseInputStreamer], output_streamers: list[BaseOutputStreamer], post_output_audio_delay: float, logger: logging.Logger) -> None:
+        """Initializes a new instance of the GoogleIOStreamer class.
+
+        Args:
+            session (AsyncSession): The session of the GoogleIOStreamer.
+            task_group (asyncio.TaskGroup): The task group of the GoogleIOStreamer.
+            input_queue (asyncio.Queue): The input queue of the GoogleIOStreamer.
+            output_queue (asyncio.Queue): The output queue of the GoogleIOStreamer.
+            input_streamers (list[BaseInputStreamer]): The input streamers of the GoogleIOStreamer.
+            output_streamers (list[BaseOutputStreamer]): The output streamers of the GoogleIOStreamer.
+            post_output_audio_delay (float): The delay in seconds to post the output audio.
+            logger (logging.Logger): The logger of the GoogleIOStreamer.
+        """
+    async def start(self) -> None:
+        """Processes the realtime conversation.
+
+        This method is used to start the realtime conversation.
+        It initializes the input and output streamers, creates the necessary tasks, and starts the conversation.
+        When the conversation is terminated, it cleans up the input and output streamers.
+        """
+
+class GoogleRealtimeChat(BaseRealtimeChat):
+    '''[BETA] A realtime chat module to interact with Gemini Live models.
+
+    Warning:
+        The \'GoogleRealtimeChat\' class is currently in beta and may be subject to changes in the future.
+        It is intended only for quick prototyping in local environments.
+        Please avoid using it in production environments.
+
+    Attributes:
+        model_name (str): The name of the language model.
+        client_params (dict[str, Any]): The Google client instance init parameters.
+
+    Basic usage:
+        The `GoogleRealtimeChat` can be used as started as follows:
+        ```python
+        realtime_chat = GoogleRealtimeChat(model_name="gemini-live-2.5-flash-preview")
+        await realtime_chat.invoke()
+        ```
+
+    Custom IO streamers:
+        The `GoogleRealtimeChat` can be used with custom IO streamers.
+        ```python
+        input_streamers = [KeyboardInputStreamer(), LinuxMicInputStreamer()]
+        output_streamers = [ConsoleOutputStreamer(), LinuxSpeakerOutputStreamer()]
+        realtime_chat = GoogleRealtimeChat(model_name="gemini-live-2.5-flash-preview")
+        await realtime_chat.start(input_streamers=input_streamers, output_streamers=output_streamers)
+        ```
+
+        In the above example, we added a capability to use a Linux system microphone and speaker,
+        allowing realtime audio input and output to the model.
+
+    Authentication:
+        The `GoogleRealtimeChat` can use either Google Gen AI or Google Vertex AI.
+
+        Google Gen AI is recommended for quick prototyping and development.
+        It requires a Gemini API key for authentication.
+
+        Usage example:
+        ```python
+        realtime_chat = GoogleRealtimeChat(
+            model_name="gemini-live-2.5-flash-preview",
+            api_key="your_api_key"
+        )
+        ```
+
+        Google Vertex AI is recommended to build production-ready applications.
+        It requires a service account JSON file for authentication.
+
+        Usage example:
+        ```python
+        realtime_chat = GoogleRealtimeChat(
+            model_name="gemini-live-2.5-flash-preview",
+            credentials_path="path/to/service_account.json"
+        )
+        ```
+
+        If neither `api_key` nor `credentials_path` is provided, Google Gen AI will be used by default.
+        The `GOOGLE_API_KEY` environment variable will be used for authentication.
+    '''
+    model_name: Incomplete
+    client_params: Incomplete
+    def __init__(self, model_name: str, api_key: str | None = None, credentials_path: str | None = None, project_id: str | None = None, location: str = 'us-central1') -> None:
+        '''Initializes a new instance of the GoogleRealtimeChat class.
+
+        Args:
+            model_name (str): The name of the model to use.
+            api_key (str | None, optional): Required for Google Gen AI authentication. Cannot be used together
+                with `credentials_path`. Defaults to None.
+            credentials_path (str | None, optional): Required for Google Vertex AI authentication. Path to the service
+                account credentials JSON file. Cannot be used together with `api_key`. Defaults to None.
+            project_id (str | None, optional): The Google Cloud project ID for Vertex AI. Only used when authenticating
+                with `credentials_path`. Defaults to None, in which case it will be loaded from the credentials file.
+            location (str, optional): The location of the Google Cloud project for Vertex AI. Only used when
+                authenticating with `credentials_path`. Defaults to "us-central1".
+
+        Note:
+            If neither `api_key` nor `credentials_path` is provided, Google Gen AI will be used by default.
+            The `GOOGLE_API_KEY` environment variable will be used for authentication.
+        '''
+    async def start(self, input_streamers: list[BaseInputStreamer] | None = None, output_streamers: list[BaseOutputStreamer] | None = None, post_output_audio_delay: float = ...) -> None:
+        """Starts the realtime conversation using the provided input and output streamers.
+
+        This method is used to start the realtime conversation using a `GoogleIOStreamer`.
+        The streamers are responsible for handling the input and output of the conversation.
+
+        Args:
+            input_streamers (list[BaseInputStreamer] | None, optional): The input streamers to use.
+                Defaults to None, in which case a `KeyboardInputStreamer` will be used.
+            output_streamers (list[BaseOutputStreamer] | None, optional): The output streamers to use.
+                Defaults to None, in which case a `ConsoleOutputStreamer` will be used.
+            post_output_audio_delay (float, optional): The delay in seconds to post the output audio.
+                Defaults to 0.5 seconds.
+
+        Raises:
+            ValueError: If the `input_streamers` or `output_streamers` is an empty list.
+            ValueError: If the `post_output_audio_delay` is not greater than 0.
+            Exception: If the conversation fails to process.
+        """

gllm_inference/realtime_chat/input_streamer/__init__.pyi

@@ -0,0 +1,4 @@
+from gllm_inference.realtime_chat.input_streamer.keyboard_input_streamer import KeyboardInputStreamer as KeyboardInputStreamer
+from gllm_inference.realtime_chat.input_streamer.linux_mic_input_streamer import LinuxMicInputStreamer as LinuxMicInputStreamer
+
+__all__ = ['KeyboardInputStreamer', 'LinuxMicInputStreamer']

gllm_inference/realtime_chat/input_streamer/input_streamer.pyi

@@ -0,0 +1,36 @@
+import abc
+import asyncio
+from abc import ABC, abstractmethod
+from pydantic import BaseModel as BaseModel
+
+class BaseInputStreamer(ABC, metaclass=abc.ABCMeta):
+    """[BETA] A base class for input streamers.
+
+    Attributes:
+        state (BaseModel | None): The state of the input streamer.
+        input_queue (asyncio.Queue | None): The queue to put the input events.
+    """
+    state: BaseModel | None
+    input_queue: asyncio.Queue | None
+    async def initialize(self, state: BaseModel, input_queue: asyncio.Queue) -> None:
+        """Initializes the input streamer.
+
+        Args:
+            input_queue (asyncio.Queue): The queue to put the input events.
+            state (BaseModel): The state of the input streamer.
+        """
+    @abstractmethod
+    async def stream_input(self) -> None:
+        """Streams the input from a certain source.
+
+        This method must be implemented by subclasses to define the logic for streaming the input.
+
+        Raises:
+            NotImplementedError: If the method is not implemented in a subclass.
+        """
+    async def close(self) -> None:
+        """Closes the input streamer.
+
+        This method is used to close the input streamer.
+        It is used to clean up the input streamer.
+        """

gllm_inference/realtime_chat/input_streamer/keyboard_input_streamer.pyi

@@ -0,0 +1,27 @@
+import asyncio
+from _typeshed import Incomplete
+from gllm_inference.realtime_chat.input_streamer.input_streamer import BaseInputStreamer as BaseInputStreamer
+
+DEFAULT_QUIT_CMD: str
+
+class KeyboardInputStreamer(BaseInputStreamer):
+    """[BETA] A keyboard input streamer that reads the input text from the keyboard.
+
+    Attributes:
+        state (BaseModel): The state of the input streamer.
+        input_queue (asyncio.Queue): The queue to put the input events.
+        quit_cmd (str): The command to quit the conversation.
+    """
+    record_process: asyncio.subprocess.Process | None
+    quit_cmd: Incomplete
+    def __init__(self, quit_cmd: str = ...) -> None:
+        """Initializes the KeyboardInputStreamer.
+
+        Args:
+            quit_cmd (str, optional): The command to quit the conversation. Defaults to DEFAULT_QUIT_CMD.
+        """
+    async def stream_input(self) -> None:
+        """Streams the input from the keyboard.
+
+        This method is used to stream the input text from the keyboard to the input queue.
+        """

gllm_inference/realtime_chat/input_streamer/linux_mic_input_streamer.pyi

@@ -0,0 +1,36 @@
+import asyncio
+from _typeshed import Incomplete
+from gllm_inference.realtime_chat.input_streamer.input_streamer import BaseInputStreamer as BaseInputStreamer
+
+SEND_SAMPLE_RATE: int
+CHANNELS: int
+RECORD_CMD: Incomplete
+CHUNK_DURATION: float
+CHUNK_SIZE: Incomplete
+
+class LinuxMicInputStreamer(BaseInputStreamer):
+    """[BETA] A Linux microphone input streamer that reads the input audio from the microphone.
+
+    Attributes:
+        state (BaseModel): The state of the input streamer.
+        input_queue (asyncio.Queue): The queue to put the input events.
+        record_process (asyncio.subprocess.Process | None): The process to record the input audio.
+    """
+    record_process: asyncio.subprocess.Process | None
+    def __init__(self) -> None:
+        """Initializes the LinuxMicInputStreamer.
+
+        Raises:
+            OSError: If the current system is not Linux.
+        """
+    async def stream_input(self) -> None:
+        """Streams the input audio from the Linux system microphone.
+
+        This method is used to stream the recorded input audio from the Linux system microphone to the input queue.
+        """
+    async def close(self) -> None:
+        """Closes the LinuxMicInputStreamer.
+
+        This method is used to close the LinuxMicInputStreamer.
+        It is used to clean up the recording process.
+        """

gllm_inference/realtime_chat/output_streamer/__init__.pyi

@@ -0,0 +1,4 @@
+from gllm_inference.realtime_chat.output_streamer.console_output_streamer import ConsoleOutputStreamer as ConsoleOutputStreamer
+from gllm_inference.realtime_chat.output_streamer.linux_speaker_output_streamer import LinuxSpeakerOutputStreamer as LinuxSpeakerOutputStreamer
+
+__all__ = ['ConsoleOutputStreamer', 'LinuxSpeakerOutputStreamer']

gllm_inference/realtime_chat/output_streamer/console_output_streamer.pyi

@@ -0,0 +1,21 @@
+from gllm_inference.realtime_chat.output_streamer.output_streamer import BaseOutputStreamer as BaseOutputStreamer
+from typing import Any
+
+USER_HEADER: str
+ASSISTANT_HEADER: str
+FOOTER: str
+
+class ConsoleOutputStreamer(BaseOutputStreamer):
+    """[BETA] A console output streamer that prints the output to the console.
+
+    Attributes:
+        state (BaseModel): The state of the output streamer.
+    """
+    async def handle(self, data: dict[str, Any]) -> None:
+        """Handles the output events.
+
+        This method is used to handle the text output events and print them to the console.
+
+        Args:
+            data (dict[str, Any]): The output events.
+        """

gllm_inference/realtime_chat/output_streamer/linux_speaker_output_streamer.pyi

@@ -0,0 +1,42 @@
+import asyncio
+from _typeshed import Incomplete
+from gllm_inference.realtime_chat.output_streamer.output_streamer import BaseOutputStreamer as BaseOutputStreamer
+from pydantic import BaseModel as BaseModel
+from typing import Any
+
+PLAY_AUDIO_SAMPLE_RATE: int
+CHANNELS: int
+PLAY_CMD: Incomplete
+OUTPUT_AUDIO_DELAY: float
+
+class LinuxSpeakerOutputStreamer(BaseOutputStreamer):
+    """[BETA] A Linux speaker output streamer that plays the output audio through the speakers.
+
+    Attributes:
+        state (BaseModel): The state of the output streamer.
+        play_process (asyncio.subprocess.Process | None): The process to play the output audio.
+    """
+    play_process: asyncio.subprocess.Process | None
+    async def initialize(self, state: BaseModel) -> None:
+        """Initializes the LinuxSpeakerOutputStreamer.
+
+        Args:
+            state (BaseModel): The state of the output streamer.
+
+        Raises:
+            OSError: If the current system is not Linux.
+        """
+    async def handle(self, data: dict[str, Any]) -> None:
+        """Handles the output events.
+
+        This method is used to handle the audio output events and play them through the Linux system speakers.
+
+        Args:
+            data (dict[str, Any]): The output events.
+        """
+    async def close(self) -> None:
+        """Closes the LinuxSpeakerOutputStreamer.
+
+        This method is used to close the LinuxSpeakerOutputStreamer.
+        It is used to clean up playing process.
+        """

gllm_inference/realtime_chat/output_streamer/output_streamer.pyi

@@ -0,0 +1,33 @@
+import abc
+from abc import ABC, abstractmethod
+from pydantic import BaseModel as BaseModel
+from typing import Any
+
+class BaseOutputStreamer(ABC, metaclass=abc.ABCMeta):
+    """[BETA] A base class for output streamers.
+
+    Attributes:
+        state (BaseModel | None): The state of the output streamer.
+    """
+    state: BaseModel | None
+    async def initialize(self, state: BaseModel) -> None:
+        """Initializes the output streamer.
+
+        Args:
+            state (BaseModel): The state of the output streamer.
+        """
+    @abstractmethod
+    async def handle(self, data: dict[str, Any]) -> None:
+        """Handles output events streamed from the model.
+
+        This method must be implemented by subclasses to define the logic for handling the output events.
+
+        Raises:
+            NotImplementedError: If the method is not implemented in a subclass.
+        """
+    async def close(self) -> None:
+        """Closes the output streamer.
+
+        This method is used to close the output streamer.
+        It is used to clean up the output streamer.
+        """

gllm_inference/realtime_chat/realtime_chat.pyi

@@ -0,0 +1,28 @@
+import abc
+from abc import ABC, abstractmethod
+from gllm_inference.realtime_chat.input_streamer.input_streamer import BaseInputStreamer as BaseInputStreamer
+from gllm_inference.realtime_chat.output_streamer.output_streamer import BaseOutputStreamer as BaseOutputStreamer
+
+class BaseRealtimeChat(ABC, metaclass=abc.ABCMeta):
+    """[BETA] A base class for realtime chat modules.
+
+    The `BaseRealtimeChat` class provides a framework for processing real-time conversations.
+    """
+    def __init__(self) -> None:
+        """Initializes a new instance of the BaseRealtimeChat class."""
+    @abstractmethod
+    async def start(self, input_streamers: list[BaseInputStreamer] | None = None, output_streamers: list[BaseOutputStreamer] | None = None) -> None:
+        """Starts the real-time conversation using the provided input and output streamers.
+
+        This abstract method must be implemented by subclasses to define the logic
+        for starting the real-time conversation.
+
+        Args:
+            input_streamers (list[BaseInputStreamer] | None, optional): The input streamers to use.
+                Defaults to None.
+            output_streamers (list[BaseOutputStreamer] | None, optional): The output streamers to use.
+                Defaults to None.
+
+        Raises:
+            NotImplementedError: If the method is not implemented in a subclass.
+        """

gllm_inference/request_processor/__init__.pyi

@@ -0,0 +1,4 @@
+from gllm_inference.request_processor.lm_request_processor import LMRequestProcessor as LMRequestProcessor
+from gllm_inference.request_processor.uses_lm_mixin import UsesLM as UsesLM
+
+__all__ = ['LMRequestProcessor', 'UsesLM']

gllm_inference/request_processor/lm_request_processor.pyi

@@ -0,0 +1,101 @@
+from _typeshed import Incomplete
+from gllm_core.event import EventEmitter as EventEmitter
+from gllm_inference.lm_invoker.lm_invoker import BaseLMInvoker as BaseLMInvoker
+from gllm_inference.output_parser.output_parser import BaseOutputParser as BaseOutputParser
+from gllm_inference.prompt_builder.prompt_builder import PromptBuilder as PromptBuilder
+from gllm_inference.schema import LMOutput as LMOutput, Message as Message, MessageContent as MessageContent, ResponseSchema as ResponseSchema, ToolCall as ToolCall, ToolResult as ToolResult
+from langchain_core.tools import Tool as Tool
+from typing import Any
+
+class LMRequestProcessor:
+    """A request processor to perform language models inference.
+
+    The `LMRequestProcessor` class handles the process of building a prompt, invoking a language model, and optionally
+    parsing the output. It combines a prompt builder, language model invoker, and an optional output parser to manage
+    the inference process in Gen AI applications.
+
+    Attributes:
+        prompt_builder (PromptBuilder): The prompt builder used to format the prompt.
+        lm_invoker (BaseLMInvoker): The language model invoker that handles the model inference.
+        output_parser (BaseOutputParser | None): The optional parser to process the model's output, if any.
+        tool_dict (dict[str, Tool]): A dictionary of tools provided to the language model to enable tool calling,
+            if any. The dictionary maps the tool name to the tools themselves.
+    """
+    prompt_builder: Incomplete
+    lm_invoker: Incomplete
+    output_parser: Incomplete
+    tool_dict: Incomplete
+    def __init__(self, prompt_builder: PromptBuilder, lm_invoker: BaseLMInvoker, output_parser: BaseOutputParser | None = None) -> None:
+        """Initializes a new instance of the LMRequestProcessor class.
+
+        Args:
+            prompt_builder (PromptBuilder): The prompt builder used to format the prompt.
+            lm_invoker (BaseLMInvoker): The language model invoker that handles the model inference.
+            output_parser (BaseOutputParser, optional): An optional parser to process the model's output.
+                Defaults to None.
+        """
+    def set_tools(self, tools: list[Tool]) -> None:
+        """Sets the tools for the LM invoker.
+
+        This method sets the tools for the LM invoker. Any existing tools will be replaced.
+
+        Args:
+            tools (list[Tool]): The list of tools to be used.
+        """
+    def clear_tools(self) -> None:
+        """Clears the tools for the LM invoker.
+
+        This method clears the tools for the LM invoker.
+        """
+    def set_response_schema(self, response_schema: ResponseSchema | None) -> None:
+        """Sets the response schema for the LM invoker.
+
+        This method sets the response schema for the LM invoker. Any existing response schema will be replaced.
+
+        Args:
+            response_schema (ResponseSchema | None): The response schema to be used.
+        """
+    def clear_response_schema(self) -> None:
+        """Clears the response schema for the LM invoker.
+
+        This method clears the response schema for the LM invoker.
+        """
+    async def process(self, prompt_kwargs: dict[str, Any] | None = None, history: list[Message] | None = None, extra_contents: list[MessageContent] | None = None, hyperparameters: dict[str, Any] | None = None, event_emitter: EventEmitter | None = None, auto_execute_tools: bool = True, max_lm_calls: int = 5, **kwargs: Any) -> Any:
+        """Processes a language model inference request.
+
+        This method processes the language model inference request as follows:
+        1. Assembling the prompt using the provided keyword arguments.
+        2. Invoking the language model with the assembled prompt and optional hyperparameters.
+        3. If `auto_execute_tools` is True, the method will automatically execute tools if the LM output includes
+           tool calls.
+        4. Optionally parsing the model's output using the output parser if provided. If the model output is an
+           LMOutput object, the output parser will process the `response` attribute of the LMOutput object.
+
+        Args:
+            prompt_kwargs (dict[str, Any], optional): Deprecated parameter for passing prompt kwargs.
+                Replaced by **kwargs. Defaults to None
+            history (list[Message] | None, optional): A list of conversation history to be included in the prompt.
+                Defaults to None.
+            extra_contents (list[MessageContent] | None, optional): A list of extra contents to be included in the
+                user message. Defaults to None.
+            hyperparameters (dict[str, Any] | None, optional): A dictionary of hyperparameters for the model invocation.
+                Defaults to None.
+            event_emitter (EventEmitter | None, optional): An event emitter for streaming model outputs.
+                Defaults to None.
+            auto_execute_tools (bool, optional): Whether to automatically execute tools if the LM invokes output
+                tool calls. Defaults to True.
+            max_lm_calls (int, optional): The maximum number of times the language model can be invoked
+                when `auto_execute_tools` is True. Defaults to 5.
+            **kwargs (Any): Keyword arguments that will be passed to format the prompt builder.
+                Values must be either a string or an object that can be serialized to a string.
+                Reserved keyword arguments that cannot be passed to the prompt builder include:
+                1. `history`
+                2. `extra_contents`
+                3. `hyperparameters`
+                4. `event_emitter`
+                5. `auto_execute_tools`
+                6. `max_lm_calls`
+
+        Returns:
+            Any: The result of the language model invocation, optionally parsed by the output parser.
+        """