gllm-inference-binary 0.5.51b3__cp313-cp313-macosx_11_0_arm64.whl

gllm_inference/lm_invoker/xai_lm_invoker.pyi

@@ -0,0 +1,289 @@
+from _typeshed import Incomplete
+from gllm_core.event import EventEmitter as EventEmitter
+from gllm_core.schema.tool import Tool as Tool
+from gllm_core.utils.retry import RetryConfig as RetryConfig
+from gllm_inference.constants import GRPC_ENABLE_RETRIES_KEY as GRPC_ENABLE_RETRIES_KEY, INVOKER_PROPAGATED_MAX_RETRIES as INVOKER_PROPAGATED_MAX_RETRIES
+from gllm_inference.exceptions import BaseInvokerError as BaseInvokerError, InvokerRuntimeError as InvokerRuntimeError, build_debug_info as build_debug_info
+from gllm_inference.exceptions.provider_error_map import GRPC_STATUS_CODE_MAPPING as GRPC_STATUS_CODE_MAPPING
+from gllm_inference.lm_invoker.lm_invoker import BaseLMInvoker as BaseLMInvoker
+from gllm_inference.lm_invoker.schema.xai import Key as Key, ReasoningEffort as ReasoningEffort
+from gllm_inference.schema import Attachment as Attachment, AttachmentType as AttachmentType, LMOutput as LMOutput, Message as Message, MessageRole as MessageRole, ModelId as ModelId, ModelProvider as ModelProvider, Reasoning as Reasoning, ResponseSchema as ResponseSchema, ThinkingEvent as ThinkingEvent, TokenUsage as TokenUsage, ToolCall as ToolCall, ToolResult as ToolResult
+from gllm_inference.utils.validation import validate_string_enum as validate_string_enum
+from langchain_core.tools import Tool as LangChainTool
+from typing import Any
+
+SUPPORTED_ATTACHMENTS: Incomplete
+
+class XAILMInvoker(BaseLMInvoker):
+    '''A language model invoker to interact with xAI language models.
+
+    Attributes:
+        model_id (str): The model ID of the language model.
+        model_provider (str): The provider of the language model.
+        model_name (str): The name of the language model.
+        client_params (dict[str, Any]): The xAI client initialization parameters.
+        default_hyperparameters (dict[str, Any]): Default hyperparameters for invoking the model.
+        tools (list[Tool]): The list of tools provided to the model to enable tool calling.
+        response_schema (ResponseSchema | None): The schema of the response. If provided, the model will output a
+            structured response as defined by the schema. Supports both Pydantic BaseModel and JSON schema dictionary.
+        output_analytics (bool): Whether to output the invocation analytics.
+        retry_config (RetryConfig | None): The retry configuration for the language model.
+        reasoning_effort (ReasoningEffort | None): The reasoning effort level for reasoning models ("low" or "high").
+        web_search (bool): Whether to enable the web search.
+
+
+    Basic usage:
+        The `XAILMInvoker` can be used as follows:
+        ```python
+        lm_invoker = XAILMInvoker(model_name="grok-3")
+        result = await lm_invoker.invoke("Hi there!")
+        ```
+
+    Input types:
+        The `XAILMInvoker` supports the following input types: text and image.
+        Non-text inputs can be passed as an `Attachment` object with the `user` role.
+
+        Usage example:
+        ```python
+        text = "What animal is in this image?"
+        image = Attachment.from_path("path/to/local/image.png")
+        result = await lm_invoker.invoke([text, image])
+        ```
+
+    Tool calling:
+        Tool calling is a feature that allows the language model to call tools to perform tasks.
+        Tools can be passed to the via the `tools` parameter as a list of `Tool` objects.
+        When tools are provided and the model decides to call a tool, the tool calls are stored in the
+        `tool_calls` attribute in the output.
+
+        Usage example:
+        ```python
+        lm_invoker = XAILMInvoker(..., tools=[tool_1, tool_2])
+        ```
+
+        Output example:
+        ```python
+        LMOutput(
+            response="Let me call the tools...",
+            tool_calls=[
+                ToolCall(id="123", name="tool_1", args={"key": "value"}),
+                ToolCall(id="456", name="tool_2", args={"key": "value"}),
+            ]
+        )
+        ```
+
+    Structured output:
+        Structured output is a feature that allows the language model to output a structured response.
+        This feature can be enabled by providing a schema to the `response_schema` parameter.
+
+        The schema must be either a JSON schema dictionary or a Pydantic BaseModel class.
+        If JSON schema is used, it must be compatible with Pydantic\'s JSON schema, especially for complex schemas.
+        For this reason, it is recommended to create the JSON schema using Pydantic\'s `model_json_schema` method.
+
+        The language model also doesn\'t need to stream anything when structured output is enabled. Thus, standard
+        invocation will be performed regardless of whether the `event_emitter` parameter is provided or not.
+
+        When enabled, the structured output is stored in the `structured_output` attribute in the output.
+        1. If the schema is a JSON schema dictionary, the structured output is a dictionary.
+        2. If the schema is a Pydantic BaseModel class, the structured output is a Pydantic model.
+
+        # Example 1: Using a JSON schema dictionary
+        Usage example:
+        ```python
+        schema = {
+            "title": "Animal",
+            "description": "A description of an animal.",
+            "properties": {
+                "color": {"title": "Color", "type": "string"},
+                "name": {"title": "Name", "type": "string"},
+            },
+            "required": ["name", "color"],
+            "type": "object",
+        }
+        lm_invoker = XAILMInvoker(..., response_schema=schema)
+        ```
+        Output example:
+        ```python
+        LMOutput(structured_output={"name": "Golden retriever", "color": "Golden"})
+        ```
+
+        # Example 2: Using a Pydantic BaseModel class
+        Usage example:
+        ```python
+        class Animal(BaseModel):
+            name: str
+            color: str
+
+        lm_invoker = XAILMInvoker(..., response_schema=Animal)
+        ```
+        Output example:
+        ```python
+        LMOutput(structured_output=Animal(name="Golden retriever", color="Golden"))
+        ```
+
+    Reasoning:
+        Reasoning effort is a feature specific to xAI\'s reasoning models that allows you to control the level
+        of reasoning performed by the model. This feature can be enabled by setting the `reasoning_effort` parameter.
+        Valid values are "low" and "high".
+
+        Please note that Grok 4 does not have a `reasoning_effort` parameter. If a `reasoning_effort` is provided,
+        the request will return error.
+
+        Usage example:
+        ```python
+        lm_invoker = XAILMInvoker(
+            model_name="grok-3",
+            reasoning_effort="high"  # Enable high reasoning effort
+        )
+        ```
+
+        When reasoning effort is enabled, the model\'s internal reasoning process is captured and stored in the
+        `reasoning` attribute in the output.
+
+        Output example:
+        ```python
+        LMOutput(
+            response="The answer is 42",
+            reasoning=[
+                Reasoning(
+                    id="reasoning_1",
+                    reasoning="First, I need to understand the question. The user is asking about..."
+                )
+            ]
+        )
+        ```
+
+        Streaming output example:
+        ```python
+        {"type": "thinking_start", "value": ""}\', ...}
+        {"type": "thinking", "value": "Let me think "}\', ...}
+        {"type": "thinking", "value": "about it..."}\', ...}
+        {"type": "thinking_end", "value": ""}\', ...}
+        {"type": "response", "value": "Golden retriever ", ...}
+        {"type": "response", "value": "is a good dog breed.", ...}
+        ```
+        Note: By default, the thinking token will be streamed with the legacy `EventType.DATA` event type.
+        To use the new simplified streamed event format, set the `simplify_events` parameter to `True` during
+        LM invoker initialization. The legacy event format support will be removed in v0.6.
+
+        Setting reasoning-related parameters for non-reasoning models will raise an error.
+
+    Analytics tracking:
+        Analytics tracking is a feature that allows the module to output additional information about the invocation.
+        This feature can be enabled by setting the `output_analytics` parameter to `True`.
+        When enabled, the following attributes will be stored in the output:
+        1. `token_usage`: The token usage.
+        2. `finish_details`: The details about how the generation finished.
+
+        Output example:
+        ```python
+        LMOutput(
+            response="Golden retriever is a good dog breed.",
+            token_usage=TokenUsage(input_tokens=100, output_tokens=50),
+            finish_details={"finish_reason": "stop"},
+        )
+        ```
+
+        When streaming is enabled, token usage is not supported. Therefore, the `token_usage` attribute will be `None`
+        regardless of the value of the `output_analytics` parameter.
+
+    Retry and timeout:
+        The `XAILMInvoker` supports retry and timeout configuration.
+        By default, the max retries is set to 0 and the timeout is set to 30.0 seconds.
+        They can be customized by providing a custom `RetryConfig` object to the `retry_config` parameter.
+
+        Retry config examples:
+        ```python
+        retry_config = RetryConfig(max_retries=0, timeout=None)  # No retry, no timeout
+        retry_config = RetryConfig(max_retries=0, timeout=10.0)  # No retry, 10.0 seconds timeout
+        retry_config = RetryConfig(max_retries=5, timeout=None)  # 5 max retries, no timeout
+        retry_config = RetryConfig(max_retries=5, timeout=10.0)  # 5 max retries, 10.0 seconds timeout
+        ```
+
+        Usage example:
+        ```python
+        lm_invoker = XAILMInvoker(..., retry_config=retry_config)
+        ```
+
+    Web Search:
+        The web search is a feature that allows the language model to search the web for relevant information.
+        This feature can be enabled by setting the `web_search` parameter to `True`.
+
+        Usage example:
+        ```python
+        lm_invoker = XAILMInvoker(
+            model_name="grok-3",
+            web_search=True
+        )
+        ```
+
+        When web search is enabled, the language model will search for relevant information and may cite the
+        relevant sources (including from X platform). The citations will be stored as `Chunk` objects in the
+        `citations` attribute in the output.
+
+        Output example:
+        ```python
+        LMOutput(
+            response="According to recent reports, the latest AI developments... ([Source](https://example.com)).",
+            citations=[
+                Chunk(
+                    id="search_result_1",
+                    content="Latest AI developments report",
+                    metadata={
+                        "start_index": 164,
+                        "end_index": 275,
+                        "title": "Example title",
+                        "url": "https://www.example.com",
+                        "type": "url_citation",
+                    },
+                ),
+            ],
+        )
+        ```
+
+    Output types:
+        The output of the `XAILMInvoker` can either be:
+        1. `str`: A text response.
+        2. `LMOutput`: A Pydantic model that may contain the following attributes:
+            2.1. response (str)
+            2.2. tool_calls (list[ToolCall])
+            2.3. structured_output (dict[str, Any] | BaseModel | None)
+            2.4. token_usage (TokenUsage | None)
+            2.5. duration (float | None)
+            2.6. finish_details (dict[str, Any])
+            2.7. reasoning (list[Reasoning])
+            2.8. citations (list[Chunk])
+    '''
+    reasoning_effort: Incomplete
+    web_search: Incomplete
+    client_params: Incomplete
+    def __init__(self, model_name: str, api_key: str | None = None, model_kwargs: dict[str, Any] | None = None, default_hyperparameters: dict[str, Any] | None = None, tools: list[Tool | LangChainTool] | None = None, response_schema: ResponseSchema | None = None, output_analytics: bool = False, retry_config: RetryConfig | None = None, reasoning_effort: ReasoningEffort | None = None, web_search: bool = False, simplify_events: bool = False) -> None:
+        """Initializes a new instance of the XAILMInvoker class.
+
+        Args:
+            model_name (str): The name of the xAI model.
+            api_key (str | None, optional): The API key for authenticating with xAI. Defaults to None, in which
+                case the `XAI_API_KEY` environment variable will be used.
+            model_kwargs (dict[str, Any] | None, optional): Additional model parameters. Defaults to None.
+            default_hyperparameters (dict[str, Any] | None, optional): Default hyperparameters for invoking the model.
+                Defaults to None.
+            tools (list[Tool | LangChainTool] | None, optional): Tools provided to the language model to enable tool
+            calling.
+                Defaults to None.
+            response_schema (ResponseSchema | None, optional): The schema of the response. If provided, the model will
+                output a structured response as defined by the schema. Supports both Pydantic BaseModel and JSON schema
+                dictionary. Defaults to None.
+            output_analytics (bool, optional): Whether to output the invocation analytics. Defaults to False.
+            retry_config (RetryConfig | None, optional): The retry configuration for the language model.
+                Defaults to None, in which case a default config with no retry and 30.0 seconds timeout is used.
+            reasoning_effort (ReasoningEffort | None, optional): The reasoning effort for reasoning models. Not allowed
+                for non-reasoning models. If None, the model will perform medium reasoning effort. Defaults to None.
+            web_search (bool, optional): Whether to enable the web search. Defaults to False.
+            simplify_events (bool, optional): Temporary parameter to control the streamed events format.
+                When True, uses the simplified events format. When False, uses the legacy events format for
+                backward compatibility. Will be removed in v0.6. Defaults to False.
+
+        Raises:
+            ValueError:
+            1. `reasoning_effort` is provided, but is not a valid ReasoningEffort.
+        """

gllm_inference/model/__init__.pyi

@@ -0,0 +1,12 @@
+from gllm_inference.model.em.cohere_em import CohereEM as CohereEM
+from gllm_inference.model.em.google_em import GoogleEM as GoogleEM
+from gllm_inference.model.em.jina_em import JinaEM as JinaEM
+from gllm_inference.model.em.openai_em import OpenAIEM as OpenAIEM
+from gllm_inference.model.em.twelvelabs_em import TwelveLabsEM as TwelveLabsEM
+from gllm_inference.model.em.voyage_em import VoyageEM as VoyageEM
+from gllm_inference.model.lm.anthropic_lm import AnthropicLM as AnthropicLM
+from gllm_inference.model.lm.google_lm import GoogleLM as GoogleLM
+from gllm_inference.model.lm.openai_lm import OpenAILM as OpenAILM
+from gllm_inference.model.lm.xai_lm import XAILM as XAILM
+
+__all__ = ['AnthropicLM', 'CohereEM', 'GoogleEM', 'GoogleLM', 'JinaEM', 'OpenAIEM', 'OpenAILM', 'TwelveLabsEM', 'VoyageEM', 'XAILM']

gllm_inference/model/em/cohere_em.pyi

@@ -0,0 +1,17 @@
+class CohereEM:
+    '''Defines Cohere embedding model names constants.
+
+    Usage example:
+    ```python
+    from gllm_inference.model import CohereEM
+    from gllm_inference.em_invoker import CohereEMInvoker
+
+    em_invoker = CohereEMInvoker(CohereEM.EMBED_V4_0)
+    result = await em_invoker.invoke("Hello, world!")
+    ```
+    '''
+    EMBED_V4_0: str
+    EMBED_ENGLISH_V3_0: str
+    EMBED_ENGLISH_LIGHT_V3_0: str
+    EMBED_MULTILINGUAL_V3_0: str
+    EMBED_MULTILINGUAL_LIGHT_V3_0: str

gllm_inference/model/em/google_em.pyi

@@ -0,0 +1,16 @@
+class GoogleEM:
+    '''Defines Google embedding model names constants.
+
+    Usage example:
+    ```python
+    from gllm_inference.model import GoogleEM
+    from gllm_inference.em_invoker import GoogleEMInvoker
+
+    em_invoker = GoogleEMInvoker(GoogleEM.GEMINI_EMBEDDING_001)
+    result = await em_invoker.invoke("Hello, world!")
+    ```
+    '''
+    GEMINI_EMBEDDING_001: str
+    TEXT_EMBEDDING_004: str
+    TEXT_EMBEDDING_005: str
+    TEXT_MULTILINGUAL_EMBEDDING_002: str

gllm_inference/model/em/jina_em.pyi

@@ -0,0 +1,22 @@
+class JinaEM:
+    '''Defines Jina embedding model names constants.
+
+    Usage example:
+    ```python
+    from gllm_inference.model import JinaEM
+    from gllm_inference.em_invoker import JinaEMInvoker
+
+    em_invoker = JinaEMInvoker(JinaEM.JINA_EMBEDDINGS_V4)
+    result = await em_invoker.invoke("Hello, world!")
+    ```
+    '''
+    JINA_EMBEDDINGS_V4: str
+    JINA_EMBEDDINGS_V3: str
+    JINA_EMBEDDINGS_V2_BASE_EN: str
+    JINA_EMBEDDINGS_V2_BASE_CODE: str
+    JINA_CLIP_V2: str
+    JINA_CLIP_V1: str
+    JINA_CODE_EMBEDDINGS_1_5B: str
+    JINA_CODE_EMBEDDINGS_0_5B: str
+    JINA_COLBERT_V2: str
+    JINA_COLBERT_V1_EN: str

gllm_inference/model/em/openai_em.pyi

@@ -0,0 +1,15 @@
+class OpenAIEM:
+    '''Defines OpenAI embedding model names constants.
+
+    Usage example:
+    ```python
+    from gllm_inference.model import OpenAIEM
+    from gllm_inference.em_invoker import OpenAIEMInvoker
+
+    em_invoker = OpenAIEMInvoker(OpenAIEM.TEXT_EMBEDDING_3_SMALL)
+    result = await em_invoker.invoke("Hello, world!")
+    ```
+    '''
+    TEXT_EMBEDDING_3_SMALL: str
+    TEXT_EMBEDDING_3_LARGE: str
+    TEXT_EMBEDDING_ADA_002: str

gllm_inference/model/em/twelvelabs_em.pyi

@@ -0,0 +1,13 @@
+class TwelveLabsEM:
+    '''Defines TwelveLabs embedding model names constants.
+
+    Usage example:
+    ```python
+    from gllm_inference.model import TwelveLabsEM
+    from gllm_inference.em_invoker import TwelveLabsEMInvoker
+
+    em_invoker = TwelveLabsEMInvoker(TwelveLabsEM.MARENGO_RETRIEVAL_2_7)
+    result = await em_invoker.invoke("Hello, world!")
+    ```
+    '''
+    MARENGO_RETRIEVAL_2_7: str

gllm_inference/model/em/voyage_em.pyi

@@ -0,0 +1,20 @@
+class VoyageEM:
+    '''Defines Voyage embedding model names constants.
+
+    Usage example:
+    ```python
+    from gllm_inference.model import VoyageEM
+    from gllm_inference.em_invoker import VoyageEMInvoker
+
+    em_invoker = VoyageEMInvoker(VoyageEM.VOYAGE_3_5_LITE)
+    result = await em_invoker.invoke("Hello, world!")
+    ```
+    '''
+    VOYAGE_3_5: str
+    VOYAGE_3_5_LITE: str
+    VOYAGE_3_LARGE: str
+    VOYAGE_CODE_3: str
+    VOYAGE_FINANCE_2: str
+    VOYAGE_LAW_2: str
+    VOYAGE_CODE_2: str
+    VOYAGE_MULTIMODAL_3: str

gllm_inference/model/lm/anthropic_lm.pyi

@@ -0,0 +1,22 @@
+class AnthropicLM:
+    '''Defines Anthropic language model names constants.
+
+    Usage example:
+    ```python
+    from gllm_inference.model import AnthropicLM
+    from gllm_inference.lm_invoker import AnthropicLMInvoker
+
+    lm_invoker = AnthropicLMInvoker(AnthropicLM.CLAUDE_SONNET_4)
+    response = await lm_invoker.invoke("Hello, world!")
+    ```
+    '''
+    CLAUDE_OPUS_4_1: str
+    CLAUDE_OPUS_4: str
+    CLAUDE_SONNET_4_5: str
+    CLAUDE_SONNET_4: str
+    CLAUDE_SONNET_3_7: str
+    CLAUDE_SONNET_3_5: str
+    CLAUDE_HAIKU_4_5: str
+    CLAUDE_HAIKU_3_5: str
+    CLAUDE_OPUS_3: str
+    CLAUDE_HAIKU_3: str

gllm_inference/model/lm/google_lm.pyi

@@ -0,0 +1,18 @@
+class GoogleLM:
+    '''Defines Google language model names constants.
+
+    Usage example:
+    ```python
+    from gllm_inference.model import GoogleLM
+    from gllm_inference.lm_invoker import GoogleLMInvoker
+
+    lm_invoker = GoogleLMInvoker(GoogleLM.GEMINI_2_5_FLASH)
+    response = await lm_invoker.invoke("Hello, world!")
+    ```
+    '''
+    GEMINI_2_5_PRO: str
+    GEMINI_2_5_FLASH: str
+    GEMINI_2_5_FLASH_IMAGE: str
+    GEMINI_2_5_FLASH_LITE: str
+    GEMINI_2_0_FLASH: str
+    GEMINI_2_0_FLASH_LITE: str

gllm_inference/model/lm/openai_lm.pyi

@@ -0,0 +1,27 @@
+class OpenAILM:
+    '''Defines OpenAI language model names constants.
+
+    Usage example:
+    ```python
+    from gllm_inference.model import OpenAILM
+    from gllm_inference.lm_invoker import OpenAILMInvoker
+
+    lm_invoker = OpenAILMInvoker(OpenAILM.GPT_5_NANO)
+    response = await lm_invoker.invoke("Hello, world!")
+    ```
+    '''
+    GPT_5: str
+    GPT_5_MINI: str
+    GPT_5_NANO: str
+    GPT_4_1: str
+    GPT_4_1_MINI: str
+    GPT_4_1_NANO: str
+    GPT_4O: str
+    GPT_4O_MINI: str
+    O4_MINI: str
+    O4_MINI_DEEP_RESEARCH: str
+    O3: str
+    O3_PRO: str
+    O3_DEEP_RESEARCH: str
+    O1: str
+    O1_PRO: str

gllm_inference/model/lm/xai_lm.pyi

@@ -0,0 +1,19 @@
+class XAILM:
+    '''Defines XAI language model names constants.
+
+    Usage example:
+    ```python
+    from gllm_inference.model import XAILM
+    from gllm_inference.lm_invoker import XAILMInvoker
+
+    lm_invoker = XAILMInvoker(XAILM.GROK_4_FAST_REASONING)
+    response = await lm_invoker.invoke("Hello, world!")
+    ```
+    '''
+    GROK_CODE_FAST_1: str
+    GROK_4_FAST_REASONING: str
+    GROK_4_FAST_NON_REASONING: str
+    GROK_4_0709: str
+    GROK_3_MINI: str
+    GROK_3: str
+    GROK_2_VISION_1212: str

gllm_inference/output_parser/__init__.pyi

@@ -0,0 +1,3 @@
+from gllm_inference.output_parser.json_output_parser import JSONOutputParser as JSONOutputParser
+
+__all__ = ['JSONOutputParser']

gllm_inference/output_parser/json_output_parser.pyi

@@ -0,0 +1,60 @@
+from gllm_inference.output_parser.output_parser import BaseOutputParser as BaseOutputParser
+from typing import Any
+
+class JSONOutputParser(BaseOutputParser[dict[str, Any]]):
+    '''An output parser that parses a json object from the language model output.
+
+    The `JSONOutputParser` class searches for the first opening curly brace `{` and the last closing curly brace `}`
+    in the language model\'s output to identify and extract a JSON object. It then parses the extracted substring into
+    a Python dictionary. This method relies on finding a well-formed JSON structure enclosed by the first and last
+    curly braces in the string. If the result contains additional curly braces outside the JSON object, or if there
+    are multiple JSON objects, this parser will not function correctly and will raise a `ValueError`.
+
+    Example:
+    If the result is:
+    ```
+    "Here is the data: {\\"key\\": \\"value\\"} and some other text."
+    ```
+    The parser will extract the `{"key": "value"}` JSON object.
+
+    However, if the result contains multiple JSON objects or nested data, such as:
+    ```
+    "Here are two JSONs: {\\"key1\\": \\"value1\\"} and {\\"key2\\": \\"value2\\"}"
+    ```
+    The parser will not handle this correctly, as it only extracts the content between the first `{` and the last `}`.
+    '''
+    def parse(self, result: str) -> dict[str, Any]:
+        '''Parses the raw output string to extract and decode a JSON object.
+
+        This method searches the provided string for the first opening curly brace `{` and the last closing curly
+        brace `}` to identify a JSON object. It extracts the substring between these braces and attempts to parse it
+        as a JSON object. The method raises a `ValueError` if no valid JSON structure is found or if the JSON is
+        malformed.
+
+        Note:
+            This approach relies on the first `{` and the last `}` in the string. It will fail if:
+            - The result contains curly braces outside the intended JSON object.
+            - There are multiple JSON objects within the string, as it only processes the first and last braces.
+
+        Example:
+            If the result is:
+            ```
+            "Here is the data: {\\"key\\": \\"value\\"} and some other text."
+            ```
+            The parser will extract and return the `{"key": "value"}` object.
+
+            However, if the result is:
+            ```
+            "Here are two JSONs: {\\"key1\\": \\"value1\\"} and {\\"key2\\": \\"value2\\"}"
+            ```
+            The parser will incorrectly attempt to parse everything between the first `{` and the last `}`.
+
+        Args:
+            result (str): The raw output string from the language model.
+
+        Returns:
+            dict[str, Any]: The parsed JSON object as a Python dictionary.
+
+        Raises:
+            ValueError: If no valid JSON object is found or if the JSON string is invalid.
+        '''

gllm_inference/output_parser/output_parser.pyi

@@ -0,0 +1,27 @@
+import abc
+from abc import ABC, abstractmethod
+from typing import Generic, TypeVar
+
+T = TypeVar('T')
+
+class BaseOutputParser(ABC, Generic[T], metaclass=abc.ABCMeta):
+    """A base class for output parsers used in Gen AI applications.
+
+    The `BaseOutputParser` class defines the interface for parsing the output of language models.
+    Subclasses must implement the `parse` method to process and extract meaningful data from the raw output.
+    """
+    @abstractmethod
+    def parse(self, result: str) -> T:
+        """Parses the raw output string from the language model.
+
+        This abstract method must be implemented by subclasses to define how the result is parsed and processed.
+
+        Args:
+            result (str): The raw output string from the language model.
+
+        Returns:
+            T: The parsed result of type T.
+
+        Raises:
+            NotImplementedError: If the method is not implemented in a subclass.
+        """

gllm_inference/prompt_builder/__init__.pyi

@@ -0,0 +1,3 @@
+from gllm_inference.prompt_builder.prompt_builder import PromptBuilder as PromptBuilder
+
+__all__ = ['PromptBuilder']

gllm_inference/prompt_builder/format_strategy/__init__.pyi

@@ -0,0 +1,4 @@
+from gllm_inference.prompt_builder.format_strategy.jinja_format_strategy import JinjaFormatStrategy as JinjaFormatStrategy
+from gllm_inference.prompt_builder.format_strategy.string_format_strategy import StringFormatStrategy as StringFormatStrategy
+
+__all__ = ['StringFormatStrategy', 'JinjaFormatStrategy']

gllm_inference/prompt_builder/format_strategy/format_strategy.pyi

@@ -0,0 +1,55 @@
+import abc
+from _typeshed import Incomplete
+from abc import ABC, abstractmethod
+from gllm_inference.schema.message import MessageContent as MessageContent
+
+class BasePromptFormattingStrategy(ABC, metaclass=abc.ABCMeta):
+    """Base class for prompt formatting strategies.
+
+    This class defines the interface for different prompt templating engines. Subclasses
+    implement specific formatting strategies to render templates with variable
+    substitution.
+
+    The strategy pattern allows the PromptBuilder to work with different templating engines
+    without changing its core logic.
+
+    Attributes:
+        key_defaults (dict[str, str]): The default values for the keys.
+    """
+    key_defaults: Incomplete
+    def __init__(self, key_defaults: dict[str, str] | None = None) -> None:
+        """Initialize the BasePromptFormattingStrategy.
+
+        Args:
+            key_defaults (dict[str, str] | None, optional): The default values for the keys. Defaults to None,
+                in which case no default values are used.
+        """
+    def format(self, template: str, variables_map: dict[str, str] | None = None, extra_contents: list[MessageContent] | None = None) -> list[str]:
+        """Format template with variables using the template method pattern.
+
+        This is a template method that defines the algorithm for formatting:
+        1. Merge key_defaults and variables_map
+        2. Render the template (delegated to subclass via _render_template)
+        3. Append extra_contents to the result
+
+        Args:
+            template (str): Template string to format.
+            variables_map (dict[str, str] | None, optional): Variables for substitution. Defaults to None.
+            extra_contents (list[MessageContent] | None, optional): Extra contents to format. Defaults to None.
+
+        Returns:
+            str: Formatted template string.
+        """
+    @abstractmethod
+    def extract_keys(self, template: str | None) -> set[str]:
+        """Extract variable keys from template.
+
+        Args:
+            template (str | None): Template string to extract keys from.
+
+        Returns:
+            set[str]: Set of variable keys found in template.
+
+        Raises:
+            NotImplementedError: If the method is not implemented.
+        """