chat-cmpl-stream-handler 0.1.0__tar.gz

chat_cmpl_stream_handler-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 AllenChou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chat_cmpl_stream_handler-0.1.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: chat-cmpl-stream-handler
+Version: 0.1.0
+Summary: Chat Completion Stream Handler
+License: MIT
+License-File: LICENSE
+Author: Allen Chou
+Author-email: f1470891079@gmail.com
+Requires-Python: >=3.11,<4
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: openai (>=1)
+Project-URL: Homepage, https://github.com/allen2c/chat-cmpl-stream-handler
+Project-URL: PyPI, https://pypi.org/project/chat-cmpl-stream-handler/
+Project-URL: Repository, https://github.com/allen2c/chat-cmpl-stream-handler
+Description-Content-Type: text/markdown
+
+# chat-cmpl-stream-handler
+
+[![PyPI version](https://img.shields.io/pypi/v/chat-cmpl-stream-handler.svg)](https://pypi.org/project/chat-cmpl-stream-handler/)
+[![Python Version](https://img.shields.io/pypi/pyversions/chat-cmpl-stream-handler.svg)](https://pypi.org/project/chat-cmpl-stream-handler/)
+[![License](https://img.shields.io/pypi/l/chat-cmpl-stream-handler.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://github.com/allen2c/chat-cmpl-stream-handler/actions/workflows/test.yml/badge.svg)](https://github.com/allen2c/chat-cmpl-stream-handler/actions/workflows/test.yml)
+[![Docs](https://img.shields.io/badge/docs-github%20pages-blue)](https://allen2c.github.io/chat-cmpl-stream-handler/)
+
+You've reimplemented the tool call loop for the fifth time. So have I. Never again.
+
+## Why
+
+OpenAI Responses API? Deprecated vibes. Agents SDK? Lovely — until the third breaking change in a month. Chat Completions API? Still here. Still boring. Still working.
+
+This library does exactly two things that everyone keeps copy-pasting across projects:
+
+1. Stream a chat completion and handle events
+2. Keep looping tool calls until the model is done
+
+That's it. No magic. No framework. Just the loop.
+
+## Installation
+
+```bash
+pip install chat-cmpl-stream-handler
+```
+
+## Quick Start
+
+```python
+import asyncio
+import json
+from openai import AsyncOpenAI
+from chat_cmpl_stream_handler import ChatCompletionStreamHandler, stream_until_user_input
+
+client = AsyncOpenAI(api_key="...")
+
+GET_WEATHER_TOOL = {
+    "type": "function",
+    "function": {
+        "name": "get_weather",
+        "description": "Get the current weather for a given city.",
+        "parameters": {
+            "type": "object",
+            "properties": {"city": {"type": "string"}},
+            "required": ["city"],
+            "additionalProperties": False,
+        },
+        "strict": True,
+    },
+}
+
+
+async def get_weather(arguments: str, context) -> str:
+    args = json.loads(arguments)
+    return f"The weather in {args['city']} is sunny and 25°C."
+
+
+async def main():
+    result = await stream_until_user_input(
+        messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
+        model="gpt-4.1-nano",
+        openai_client=client,
+        stream_handler=ChatCompletionStreamHandler(),
+        tool_invokers={"get_weather": get_weather},
+        stream_kwargs={
+            "tools": [GET_WEATHER_TOOL],
+            "stream_options": {"include_usage": True},
+        },
+    )
+
+    # user → assistant (tool_calls) → tool → assistant (final answer)
+    for msg in result.to_input_list():
+        print(msg["role"], "->", msg.get("content", ""))
+
+    for usage in result.usages:
+        print(f"total tokens: {usage.total_tokens}")
+
+
+asyncio.run(main())
+```
+
+### Listening to stream events
+
+Subclass `ChatCompletionStreamHandler` and override whatever you care about:
+
+```python
+from chat_cmpl_stream_handler import ChatCompletionStreamHandler
+from openai.lib.streaming.chat._events import ContentDeltaEvent, FunctionToolCallArgumentsDoneEvent
+
+
+class PrintingHandler(ChatCompletionStreamHandler):
+    async def on_content_delta(self, event: ContentDeltaEvent) -> None:
+        print(event.delta, end="", flush=True)
+
+    async def on_tool_calls_function_arguments_done(
+        self, event: FunctionToolCallArgumentsDoneEvent
+    ) -> None:
+        print(f"\n[calling] {event.name}({event.arguments})")
+```
+
+## API Reference
+
+### `stream_until_user_input`
+
+```python
+async def stream_until_user_input(
+    messages: Iterable[ChatCompletionMessageParam],
+    model: str | ChatModel,
+    openai_client: AsyncOpenAI,
+    *,
+    stream_handler: ChatCompletionStreamHandler[ResponseFormatT],
+    tool_invokers: dict[str, ToolInvokerFn] | None = None,
+    stream_kwargs: dict[str, Any] | None = None,
+    context: Any | None = None,
+    max_iterations: int = 10,
+) -> StreamResult
+```
+
+Streams a completion, executes tool calls, feeds results back, repeats — until the model stops asking for tools. Raises `MaxIterationsReached` if you've somehow ended up in an infinite tool call loop (it happens).
+
+| Parameter        | Description                                                                             |
+|------------------|-----------------------------------------------------------------------------------------|
+| `messages`       | Initial message list                                                                    |
+| `model`          | Model name                                                                              |
+| `openai_client`  | `AsyncOpenAI` instance                                                                  |
+| `stream_handler` | Receives stream events                                                                  |
+| `tool_invokers`  | `{"tool_name": async_fn}` — each fn takes `(arguments: str, context)` and returns `str` |
+| `stream_kwargs`  | Passed directly to `beta.chat.completions.stream()` (e.g. `tools`, `stream_options`)    |
+| `context`        | Forwarded to every tool invoker as-is                                                   |
+| `max_iterations` | Safety cap. Default: 10                                                                 |
+
+### `StreamResult`
+
+| Attribute / Method | Description                                                                 |
+|--------------------|-----------------------------------------------------------------------------|
+| `.to_input_list()` | Full message history as a JSON-serializable list, ready for the next round  |
+| `.usages`          | `list[CompletionUsage]` — one per iteration, so you can watch the bill grow |
+
+### `ChatCompletionStreamHandler`
+
+All methods are no-ops by default. Override only what you need.
+
+| Method                                          | When it fires                           |
+|-------------------------------------------------|-----------------------------------------|
+| `on_event(event)`                               | Every event, before more specific hooks |
+| `on_chunk(event)`                               | Every raw SSE chunk                     |
+| `on_content_delta(event)`                       | Each content token                      |
+| `on_content_done(event)`                        | Full content string complete            |
+| `on_refusal_delta(event)`                       | Each refusal token                      |
+| `on_refusal_done(event)`                        | Full refusal string complete            |
+| `on_tool_calls_function_arguments_delta(event)` | Each incremental tool argument fragment |
+| `on_tool_calls_function_arguments_done(event)`  | Full tool argument JSON available       |
+| `on_logprobs_content_delta(event)`              | Each logprobs content token             |
+| `on_logprobs_content_done(event)`               | All logprobs content tokens done        |
+| `on_logprobs_refusal_delta(event)`              | Each logprobs refusal token             |
+| `on_logprobs_refusal_done(event)`               | All logprobs refusal tokens done        |
+
+## Provider Compatibility
+
+Works with any OpenAI-compatible endpoint. Some providers are more compatible than others.
+
+### Gemini
+
+Gemini's streaming API sends `tool_call_delta.index = None`, which the OpenAI SDK does not appreciate. Apply the included patch once at startup:
+
+```python
+from chat_cmpl_stream_handler._patch_stream_tool_call_index import apply
+apply()  # safe to call multiple times
+```
+
+Put it at the top of `main.py`, or in `conftest.py` if you're testing. This is opt-in — the library won't silently monkey-patch anything on import.
+
+## License
+
+MIT
+

chat_cmpl_stream_handler-0.1.0/README.md

@@ -0,0 +1,176 @@
+# chat-cmpl-stream-handler
+
+[![PyPI version](https://img.shields.io/pypi/v/chat-cmpl-stream-handler.svg)](https://pypi.org/project/chat-cmpl-stream-handler/)
+[![Python Version](https://img.shields.io/pypi/pyversions/chat-cmpl-stream-handler.svg)](https://pypi.org/project/chat-cmpl-stream-handler/)
+[![License](https://img.shields.io/pypi/l/chat-cmpl-stream-handler.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://github.com/allen2c/chat-cmpl-stream-handler/actions/workflows/test.yml/badge.svg)](https://github.com/allen2c/chat-cmpl-stream-handler/actions/workflows/test.yml)
+[![Docs](https://img.shields.io/badge/docs-github%20pages-blue)](https://allen2c.github.io/chat-cmpl-stream-handler/)
+
+You've reimplemented the tool call loop for the fifth time. So have I. Never again.
+
+## Why
+
+OpenAI Responses API? Deprecated vibes. Agents SDK? Lovely — until the third breaking change in a month. Chat Completions API? Still here. Still boring. Still working.
+
+This library does exactly two things that everyone keeps copy-pasting across projects:
+
+1. Stream a chat completion and handle events
+2. Keep looping tool calls until the model is done
+
+That's it. No magic. No framework. Just the loop.
+
+## Installation
+
+```bash
+pip install chat-cmpl-stream-handler
+```
+
+## Quick Start
+
+```python
+import asyncio
+import json
+from openai import AsyncOpenAI
+from chat_cmpl_stream_handler import ChatCompletionStreamHandler, stream_until_user_input
+
+client = AsyncOpenAI(api_key="...")
+
+GET_WEATHER_TOOL = {
+    "type": "function",
+    "function": {
+        "name": "get_weather",
+        "description": "Get the current weather for a given city.",
+        "parameters": {
+            "type": "object",
+            "properties": {"city": {"type": "string"}},
+            "required": ["city"],
+            "additionalProperties": False,
+        },
+        "strict": True,
+    },
+}
+
+
+async def get_weather(arguments: str, context) -> str:
+    args = json.loads(arguments)
+    return f"The weather in {args['city']} is sunny and 25°C."
+
+
+async def main():
+    result = await stream_until_user_input(
+        messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
+        model="gpt-4.1-nano",
+        openai_client=client,
+        stream_handler=ChatCompletionStreamHandler(),
+        tool_invokers={"get_weather": get_weather},
+        stream_kwargs={
+            "tools": [GET_WEATHER_TOOL],
+            "stream_options": {"include_usage": True},
+        },
+    )
+
+    # user → assistant (tool_calls) → tool → assistant (final answer)
+    for msg in result.to_input_list():
+        print(msg["role"], "->", msg.get("content", ""))
+
+    for usage in result.usages:
+        print(f"total tokens: {usage.total_tokens}")
+
+
+asyncio.run(main())
+```
+
+### Listening to stream events
+
+Subclass `ChatCompletionStreamHandler` and override whatever you care about:
+
+```python
+from chat_cmpl_stream_handler import ChatCompletionStreamHandler
+from openai.lib.streaming.chat._events import ContentDeltaEvent, FunctionToolCallArgumentsDoneEvent
+
+
+class PrintingHandler(ChatCompletionStreamHandler):
+    async def on_content_delta(self, event: ContentDeltaEvent) -> None:
+        print(event.delta, end="", flush=True)
+
+    async def on_tool_calls_function_arguments_done(
+        self, event: FunctionToolCallArgumentsDoneEvent
+    ) -> None:
+        print(f"\n[calling] {event.name}({event.arguments})")
+```
+
+## API Reference
+
+### `stream_until_user_input`
+
+```python
+async def stream_until_user_input(
+    messages: Iterable[ChatCompletionMessageParam],
+    model: str | ChatModel,
+    openai_client: AsyncOpenAI,
+    *,
+    stream_handler: ChatCompletionStreamHandler[ResponseFormatT],
+    tool_invokers: dict[str, ToolInvokerFn] | None = None,
+    stream_kwargs: dict[str, Any] | None = None,
+    context: Any | None = None,
+    max_iterations: int = 10,
+) -> StreamResult
+```
+
+Streams a completion, executes tool calls, feeds results back, repeats — until the model stops asking for tools. Raises `MaxIterationsReached` if you've somehow ended up in an infinite tool call loop (it happens).
+
+| Parameter        | Description                                                                             |
+|------------------|-----------------------------------------------------------------------------------------|
+| `messages`       | Initial message list                                                                    |
+| `model`          | Model name                                                                              |
+| `openai_client`  | `AsyncOpenAI` instance                                                                  |
+| `stream_handler` | Receives stream events                                                                  |
+| `tool_invokers`  | `{"tool_name": async_fn}` — each fn takes `(arguments: str, context)` and returns `str` |
+| `stream_kwargs`  | Passed directly to `beta.chat.completions.stream()` (e.g. `tools`, `stream_options`)    |
+| `context`        | Forwarded to every tool invoker as-is                                                   |
+| `max_iterations` | Safety cap. Default: 10                                                                 |
+
+### `StreamResult`
+
+| Attribute / Method | Description                                                                 |
+|--------------------|-----------------------------------------------------------------------------|
+| `.to_input_list()` | Full message history as a JSON-serializable list, ready for the next round  |
+| `.usages`          | `list[CompletionUsage]` — one per iteration, so you can watch the bill grow |
+
+### `ChatCompletionStreamHandler`
+
+All methods are no-ops by default. Override only what you need.
+
+| Method                                          | When it fires                           |
+|-------------------------------------------------|-----------------------------------------|
+| `on_event(event)`                               | Every event, before more specific hooks |
+| `on_chunk(event)`                               | Every raw SSE chunk                     |
+| `on_content_delta(event)`                       | Each content token                      |
+| `on_content_done(event)`                        | Full content string complete            |
+| `on_refusal_delta(event)`                       | Each refusal token                      |
+| `on_refusal_done(event)`                        | Full refusal string complete            |
+| `on_tool_calls_function_arguments_delta(event)` | Each incremental tool argument fragment |
+| `on_tool_calls_function_arguments_done(event)`  | Full tool argument JSON available       |
+| `on_logprobs_content_delta(event)`              | Each logprobs content token             |
+| `on_logprobs_content_done(event)`               | All logprobs content tokens done        |
+| `on_logprobs_refusal_delta(event)`              | Each logprobs refusal token             |
+| `on_logprobs_refusal_done(event)`               | All logprobs refusal tokens done        |
+
+## Provider Compatibility
+
+Works with any OpenAI-compatible endpoint. Some providers are more compatible than others.
+
+### Gemini
+
+Gemini's streaming API sends `tool_call_delta.index = None`, which the OpenAI SDK does not appreciate. Apply the included patch once at startup:
+
+```python
+from chat_cmpl_stream_handler._patch_stream_tool_call_index import apply
+apply()  # safe to call multiple times
+```
+
+Put it at the top of `main.py`, or in `conftest.py` if you're testing. This is opt-in — the library won't silently monkey-patch anything on import.
+
+## License
+
+MIT

chat_cmpl_stream_handler-0.1.0/chat_cmpl_stream_handler/__init__.py

@@ -0,0 +1,247 @@
+import json
+import logging
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Awaitable,
+    Callable,
+    Dict,
+    Final,
+    Generic,
+    Iterable,
+    List,
+    Text,
+    Union,
+)
+
+from openai import AsyncOpenAI
+from openai.lib._parsing._completions import ResponseFormatT
+from openai.lib.streaming.chat._events import (
+    ChunkEvent,
+    ContentDeltaEvent,
+    ContentDoneEvent,
+    FunctionToolCallArgumentsDeltaEvent,
+    FunctionToolCallArgumentsDoneEvent,
+    LogprobsContentDeltaEvent,
+    LogprobsContentDoneEvent,
+    LogprobsRefusalDeltaEvent,
+    LogprobsRefusalDoneEvent,
+    RefusalDeltaEvent,
+    RefusalDoneEvent,
+)
+from openai.types.chat import ChatCompletionMessageParam
+from openai.types.chat.chat_completion_assistant_message_param import (
+    ChatCompletionAssistantMessageParam,
+)
+from openai.types.chat.chat_completion_message_function_tool_call_param import (
+    ChatCompletionMessageFunctionToolCallParam,
+)
+from openai.types.chat.chat_completion_tool_message_param import (
+    ChatCompletionToolMessageParam,
+)
+from openai.types.completion_usage import CompletionUsage
+from openai.types.shared.chat_model import ChatModel
+
+if TYPE_CHECKING:
+    from openai.lib.streaming.chat._events import ChatCompletionStreamEvent
+
+__version__: Final[Text] = "0.1.0"
+
+
+logger = logging.getLogger(__name__)
+
+
+ToolInvokerFn = Callable[[str, Any], Awaitable[str]]
+
+
+async def stream_until_user_input(
+    messages: Iterable[ChatCompletionMessageParam],
+    model: Union[str, ChatModel],
+    openai_client: AsyncOpenAI,
+    *,
+    stream_handler: "ChatCompletionStreamHandler[ResponseFormatT]",
+    tool_invokers: Dict[str, ToolInvokerFn] | None = None,
+    stream_kwargs: Dict[Text, Any] | None = None,
+    context: Any | None = None,
+    max_iterations: int = 10,
+    **kwargs,
+) -> "StreamResult":
+    current_messages = list(messages)
+    usages: List["CompletionUsage"] = []
+
+    for _ in range(max_iterations):
+        # 1. stream the response
+        async with openai_client.beta.chat.completions.stream(
+            messages=current_messages,
+            model=model,
+            **{
+                k: v
+                for k, v in (stream_kwargs or {}).items()
+                if k not in ("messages", "model")
+            },
+        ) as stream:
+            async for event in stream:
+                await stream_handler.handle(event)
+
+            final = await stream.get_final_completion()
+            if final.usage:
+                usages.append(
+                    CompletionUsage.model_validate_json(final.usage.model_dump_json())
+                )
+
+        assistant_msg = final.choices[0].message
+        current_messages.append(
+            ChatCompletionAssistantMessageParam(
+                role="assistant",
+                content=assistant_msg.content,
+                **(
+                    {
+                        "tool_calls": [
+                            ChatCompletionMessageFunctionToolCallParam(
+                                id=tc.id,
+                                type="function",
+                                function={
+                                    "name": tc.function.name,
+                                    "arguments": tc.function.arguments or "{}",
+                                },
+                            )
+                            for tc in assistant_msg.tool_calls
+                        ]
+                    }
+                    if assistant_msg.tool_calls
+                    else {}
+                ),
+            )
+        )  # Add assistant message to history
+
+        # 2. Check if there are tool calls
+        if not assistant_msg.tool_calls:
+            return StreamResult(current_messages, model, usages=usages)  # End
+
+        # 3. Execute tool calls, and add the results back to messages
+        for tool_call in assistant_msg.tool_calls:
+            invoker = (tool_invokers or {}).get(tool_call.function.name)
+
+            if invoker is None:
+                raise ValueError(f"No invoker for tool: {tool_call.function.name}")
+
+            tool_call_output = await invoker(tool_call.function.arguments, context)
+
+            current_messages.append(
+                ChatCompletionToolMessageParam(
+                    role="tool",
+                    tool_call_id=tool_call.id,
+                    content=tool_call_output,
+                )
+            )
+
+    raise MaxIterationsReached(
+        f"Reached max_iterations={max_iterations} without waiting for user input."
+    )
+
+
+class StreamResult:
+    def __init__(
+        self,
+        messages: List[ChatCompletionMessageParam],
+        model: Union[str, ChatModel],
+        usages: List["CompletionUsage"],
+    ):
+        self._messages = messages
+        self._model = model
+
+        self.usages = usages
+
+    def to_input_list(self) -> List[ChatCompletionMessageParam]:
+        return json.loads(json.dumps(self._messages, default=str))
+
+
+class ChatCompletionStreamHandler(Generic[ResponseFormatT]):
+    async def handle(self, event: "ChatCompletionStreamEvent[ResponseFormatT]") -> None:
+        """Internal dispatcher — routes each stream event to the right hook."""
+        await self.on_event(event)
+
+        if event.type == "chunk":
+            await self.on_chunk(event)
+        elif event.type == "content.delta":
+            await self.on_content_delta(event)
+        elif event.type == "content.done":
+            await self.on_content_done(event)
+        elif event.type == "refusal.delta":
+            await self.on_refusal_delta(event)
+        elif event.type == "refusal.done":
+            await self.on_refusal_done(event)
+        elif event.type == "tool_calls.function.arguments.delta":
+            await self.on_tool_calls_function_arguments_delta(event)
+        elif event.type == "tool_calls.function.arguments.done":
+            await self.on_tool_calls_function_arguments_done(event)
+        elif event.type == "logprobs.content.delta":
+            await self.on_logprobs_content_delta(event)
+        elif event.type == "logprobs.content.done":
+            await self.on_logprobs_content_done(event)
+        elif event.type == "logprobs.refusal.delta":
+            await self.on_logprobs_refusal_delta(event)
+        elif event.type == "logprobs.refusal.done":
+            await self.on_logprobs_refusal_done(event)
+        else:
+            logger.warning(f"Unknown event type: {event.type}")
+
+    async def on_event(
+        self, event: "ChatCompletionStreamEvent[ResponseFormatT]"
+    ) -> None:
+        """Called for every stream event before more specific hooks."""
+        pass
+
+    async def on_chunk(self, event: ChunkEvent) -> None:
+        """Called for every raw SSE chunk received from the API."""
+        pass
+
+    async def on_content_delta(self, event: ContentDeltaEvent) -> None:
+        """Called each time a new content token arrives."""
+        pass
+
+    async def on_content_done(self, event: ContentDoneEvent[ResponseFormatT]) -> None:
+        """Called once when the full content string is complete."""
+        pass
+
+    async def on_refusal_delta(self, event: RefusalDeltaEvent) -> None:
+        """Called each time a new refusal token arrives."""
+        pass
+
+    async def on_refusal_done(self, event: RefusalDoneEvent) -> None:
+        """Called once when the full refusal string is complete."""
+        pass
+
+    async def on_tool_calls_function_arguments_delta(
+        self, event: FunctionToolCallArgumentsDeltaEvent
+    ) -> None:
+        """Called for each incremental JSON fragment of a tool-call's arguments."""
+        pass
+
+    async def on_tool_calls_function_arguments_done(
+        self, event: FunctionToolCallArgumentsDoneEvent
+    ) -> None:
+        """Called once when a tool call's full argument JSON is available."""
+        pass
+
+    async def on_logprobs_content_delta(self, event: LogprobsContentDeltaEvent) -> None:
+        """Called for each incremental list of content log-probability tokens."""
+        pass
+
+    async def on_logprobs_content_done(self, event: LogprobsContentDoneEvent) -> None:
+        """Called once with the complete list of content log-probability tokens."""
+        pass
+
+    async def on_logprobs_refusal_delta(self, event: LogprobsRefusalDeltaEvent) -> None:
+        """Called for each incremental list of refusal log-probability tokens."""
+        pass
+
+    async def on_logprobs_refusal_done(self, event: LogprobsRefusalDoneEvent) -> None:
+        """Called once with the complete list of refusal log-probability tokens."""
+        pass
+
+
+class MaxIterationsReached(Exception):
+    """Raised when stream_until_user_input exceeds the maximum iteration limit."""
+
+    pass

chat_cmpl_stream_handler-0.1.0/chat_cmpl_stream_handler/_patch_stream_tool_call_index.py

@@ -0,0 +1,61 @@
+"""Monkey-patch for openai SDK streaming: fix providers that return
+``tool_call_delta.index = None`` (e.g. Gemini OpenAI-compat endpoint).
+
+The openai SDK assumes ``tool_call_delta.index`` is always an ``int``,
+but some providers (notably Gemini's OpenAI-compatible API) send
+``None``.  This patch normalises the index to its positional order
+before the SDK processes the chunk.
+
+Usage — call ``apply()`` once before any streaming request::
+
+    from chat_cmpl_stream_handler._patch_stream_tool_call_index import apply
+    apply()
+
+It is safe to call ``apply()`` multiple times; only the first call
+takes effect.  The patch must be applied before
+``ChatCompletionStreamState`` instances are created (i.e. before
+``openai_client.beta.chat.completions.stream()`` is called).
+"""
+
+from __future__ import annotations
+
+import logging
+
+from openai.lib.streaming.chat._completions import ChatCompletionStreamState
+from openai.types.chat import ChatCompletionChunk
+
+logger = logging.getLogger(__name__)
+
+_PATCHED = False
+_original_handle_chunk = ChatCompletionStreamState.handle_chunk
+
+
+def _fix_none_tool_call_indices(chunk: ChatCompletionChunk) -> None:
+    """Mutate *chunk* in-place so every ``tool_call.index`` is an int.
+
+    When a provider omits the index (sends ``None``), we fall back to the
+    positional order of the tool-call deltas within the choice, which is the
+    only sane default.
+    """
+    for choice in chunk.choices:
+        if not choice.delta.tool_calls:
+            continue
+        for pos, tc in enumerate(choice.delta.tool_calls):
+            if tc.index is None:
+                tc.index = pos
+
+
+def _patched_handle_chunk(self, chunk: ChatCompletionChunk):
+    _fix_none_tool_call_indices(chunk)
+    return _original_handle_chunk(self, chunk)
+
+
+def apply() -> None:
+    global _PATCHED
+    if _PATCHED:
+        return
+    ChatCompletionStreamState.handle_chunk = _patched_handle_chunk
+    _PATCHED = True
+    logger.debug(
+        "Patched ChatCompletionStreamState.handle_chunk" " for None tool_call index"
+    )

chat_cmpl_stream_handler-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+authors = [{ name = "Allen Chou", email = "f1470891079@gmail.com" }]
+dependencies = ["openai (>=1)"]
+description = "Chat Completion Stream Handler"
+license = { text = "MIT" }
+name = "chat-cmpl-stream-handler"
+readme = "README.md"
+requires-python = ">=3.11,<4"
+version = "0.1.0"
+
+[project.urls]
+Homepage = "https://github.com/allen2c/chat-cmpl-stream-handler"
+"PyPI" = "https://pypi.org/project/chat-cmpl-stream-handler/"
+Repository = "https://github.com/allen2c/chat-cmpl-stream-handler"
+
+[tool.poetry]
+packages = [{ include = "chat_cmpl_stream_handler" }]
+
+[tool.poetry.extras]
+all = []
+
+[tool.poetry.group.dev.dependencies]
+black = { extras = ["jupyter"], version = "*" }
+isort = "*"
+mkdocs-material = "*"
+openai-agents = "*"
+poetry-plugin-export = "*"
+pytest = "*"
+pytest-asyncio = "*"
+pytest-cov = "*"
+pytest-env = "*"
+pytest-xdist = "*"
+rich = "*"
+rich-color-support = "*"
+setuptools = "*"
+twine = "*"
+
+[tool.isort]
+profile = "black"
+
+[tool.flake8]
+ignore = ["E203", "E704", "W503"]
+max-line-length = 88
+
+[tool.pytest.ini_options]
+env = ["ENVIRONMENT=test", "PYTEST_IS_RUNNING=true"]
+
+[build-system]
+build-backend = "poetry.core.masonry.api"
+requires = ["poetry-core>=2.0.0,<3.0.0"]