roomkit 0.7.2__tar.gz → 0.9.0__tar.gz

{roomkit-0.7.2 → roomkit-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roomkit
-Version: 0.7.2
+Version: 0.9.0
 Summary: Pure async Python library for multi-channel conversations
 Project-URL: Homepage, https://roomkit.live
 Project-URL: Documentation, https://www.roomkit.live/docs/
@@ -25,7 +25,7 @@ Requires-Dist: pydantic>=2.9
 Provides-Extra: aicoustics
 Requires-Dist: aic-sdk>=2.1; extra == 'aicoustics'
 Provides-Extra: all
-Requires-Dist: aiortp>=0.3.1; extra == 'all'
+Requires-Dist: aiortp>=0.3.2; extra == 'all'
 Requires-Dist: aiosipua[rtp]>=0.4.1; extra == 'all'
 Requires-Dist: anthropic>=0.30; extra == 'all'
 Requires-Dist: asyncpg>=0.29; extra == 'all'
@@ -162,7 +162,7 @@ Requires-Dist: websockets>=13.0; extra == 'realtime-openai'
 Provides-Extra: redis
 Requires-Dist: redis>=5.0; extra == 'redis'
 Provides-Extra: rtp
-Requires-Dist: aiortp>=0.3.1; extra == 'rtp'
+Requires-Dist: aiortp>=0.3.2; extra == 'rtp'
 Provides-Extra: screen-capture
 Requires-Dist: mss>=9.0; extra == 'screen-capture'
 Provides-Extra: screen-input
@@ -170,6 +170,7 @@ Requires-Dist: pyautogui>=0.9; extra == 'screen-input'
 Provides-Extra: sherpa-onnx
 Requires-Dist: sherpa-onnx>=1.10; extra == 'sherpa-onnx'
 Provides-Extra: sip
+Requires-Dist: aiortp>=0.3.2; extra == 'sip'
 Requires-Dist: aiosipua[rtp]>=0.4.1; extra == 'sip'
 Provides-Extra: smart-turn
 Requires-Dist: numpy>=1.26; extra == 'smart-turn'
@@ -350,7 +351,7 @@ For development:
 git clone https://github.com/roomkit-live/roomkit.git
 cd roomkit
 uv sync --extra dev
-make all                               # ruff check + mypy --strict + pytest
+make all                               # ruff check + ty + pytest
 ```
 
 Requires **Python 3.12+**.
@@ -729,7 +730,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.
 
 ```bash
 uv sync --extra dev
-make all                # ruff check + mypy --strict + pytest
+make all                # ruff check + ty + pytest
 ```
 
 All new code needs tests. Aim for >90% coverage.

{roomkit-0.7.2 → roomkit-0.9.0}/README.md

@@ -140,7 +140,7 @@ For development:
 git clone https://github.com/roomkit-live/roomkit.git
 cd roomkit
 uv sync --extra dev
-make all                               # ruff check + mypy --strict + pytest
+make all                               # ruff check + ty + pytest
 ```
 
 Requires **Python 3.12+**.
@@ -519,7 +519,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.
 
 ```bash
 uv sync --extra dev
-make all                # ruff check + mypy --strict + pytest
+make all                # ruff check + ty + pytest
 ```
 
 All new code needs tests. Aim for >90% coverage.

{roomkit-0.7.2 → roomkit-0.9.0}/pyproject.toml

@@ -52,8 +52,8 @@ video = ["av>=12.0.0", "numpy>=1.26"]
 video-overlay = ["Pillow>=10.0"]
 yolo = ["ultralytics>=8.3"]
 mediapipe = ["mediapipe>=0.10"]
-rtp = ["aiortp>=0.3.1"]
-sip = ["aiosipua[rtp]>=0.4.1"]
+rtp = ["aiortp>=0.3.2"]
+sip = ["aiosipua[rtp]>=0.4.1", "aiortp>=0.3.2"]
 webtransport = ["aioquic>=1.0"]
 twilio = ["twilio>=9.0"]
 phonenumbers = ["phonenumbers>=8.13"]

roomkit-0.9.0/src/roomkit/_version.py

@@ -0,0 +1 @@
+__version__ = "0.9.0"

{roomkit-0.7.2 → roomkit-0.9.0}/src/roomkit/channels/_ai_context.py

@@ -53,6 +53,7 @@ class AIContextHost(Protocol):
         _max_tokens: Default max tokens (overridable per room).
         _thinking_budget: Optional thinking budget for extended thinking.
         _skills: Skill registry for tool injection.
+        _skills_in_prompt: Whether to auto-inject the skills manifest into the prompt.
         _script_executor: Script executor for skill scripts.
         _sandbox: Sandbox executor for ad-hoc command execution.
         _memory: Memory provider for conversation retrieval.
@@ -75,6 +76,7 @@ class AIContextHost(Protocol):
     _max_tokens: int
     _thinking_budget: int | None
     _skills: SkillRegistry | None
+    _skills_in_prompt: bool
     _script_executor: ScriptExecutor | None
     _sandbox: SandboxExecutor | None
     _human_input_handler: HumanInputToolHandler | None
@@ -105,6 +107,7 @@ class AIContextMixin:
     _max_tokens: int
     _thinking_budget: int | None
     _skills: SkillRegistry | None
+    _skills_in_prompt: bool
     _script_executor: ScriptExecutor | None
     _sandbox: SandboxExecutor | None
     _human_input_handler: HumanInputToolHandler | None
@@ -183,15 +186,18 @@ class AIContextMixin:
                 existing_names = {t.name for t in tools}
                 tools.extend(t for t in hi_tools if t.name not in existing_names)
 
-        # Inject skill tools and prompt (infra tools added here, gated tools later)
+        # Inject skill tools and prompt (infra tools added here, gated tools later).
+        # The prompt block is skipped when the host renders its own skills
+        # manifest inside ``system_prompt`` (``skills_in_prompt=False``).
         if self._skills and self._skills.skill_count > 0:
             tools.extend(self._skill_tools())
-            preamble = _SKILLS_PREAMBLE
-            if not self._script_executor:
-                preamble += _SKILLS_NO_SCRIPTS_NOTE
-            skills_xml = self._skills.to_prompt_xml()
-            skill_block = f"\n\n{preamble}\n\n{skills_xml}"
-            system_prompt = (system_prompt or "") + skill_block
+            if self._skills_in_prompt:
+                preamble = _SKILLS_PREAMBLE
+                if not self._script_executor:
+                    preamble += _SKILLS_NO_SCRIPTS_NOTE
+                skills_xml = self._skills.to_prompt_xml()
+                skill_block = f"\n\n{preamble}\n\n{skills_xml}"
+                system_prompt = (system_prompt or "") + skill_block
 
         # Inject sandbox tools and preamble
         if self._sandbox is not None:

{roomkit-0.7.2 → roomkit-0.9.0}/src/roomkit/channels/_ai_events.py

@@ -13,6 +13,11 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger("roomkit.channels.ai")
 
+# Per-event cap on the ``thinking`` payload published to the realtime bus.
+# Producers that must deliver longer text without loss (e.g. the streaming
+# coalescer) split it into multiple events of at most this size.
+THINKING_PREVIEW_LIMIT = 1000
+
 
 class AIEventsMixin:
     """Publishes tool-call and thinking ephemeral events over the realtime backend."""
@@ -80,7 +85,7 @@ class AIEventsMixin:
         """Publish a thinking ephemeral event. Best-effort, never breaks the loop."""
         if self._realtime is None or not room_id:
             return
-        preview_limit = 1000
+        preview_limit = THINKING_PREVIEW_LIMIT
         data: dict[str, Any] = {
             "thinking": thinking[:preview_limit] if len(thinking) > preview_limit else thinking,
             "thinking_length": len(thinking),

{roomkit-0.7.2 → roomkit-0.9.0}/src/roomkit/channels/_ai_generation.py

@@ -87,6 +87,7 @@ class AIGenerationHost(Protocol):
     _max_tool_rounds: int
     _tool_loop_timeout_seconds: float | None
     _tool_loop_warn_after: int
+    _max_empty_retries: int
     _tool_handler: Any
     _active_loops: dict[str, _ToolLoopContext]
     _after_response_hook: Any
@@ -143,6 +144,7 @@ class AIGenerationMixin:
     _max_tool_rounds: int
     _tool_loop_timeout_seconds: float | None
     _tool_loop_warn_after: int
+    _max_empty_retries: int
     _tool_handler: Any
     _active_loops: dict[str, _ToolLoopContext]
     _after_response_hook: Any
@@ -429,16 +431,19 @@ class AIGenerationMixin:
         self, context: AIContext, *, parent_span_id: str | None = None
     ) -> ToolLoopResult:
         """Generate -> execute tools -> re-generate until a text response."""
-        from roomkit.channels.ai import _current_loop_ctx, _ToolLoopContext
+        from roomkit.channels.ai import (
+            _EMPTY_RETRY_NUDGE,
+            _current_loop_ctx,
+            _ToolLoopContext,
+        )
 
-        loop_ctx = _ToolLoopContext()
-        loop_ctx.loop_id = str(id(loop_ctx))
-        parent_lctx = _current_loop_ctx.get()
-        if parent_lctx is not None:
-            loop_ctx.current_participant_role = parent_lctx.current_participant_role
+        loop_ctx = _ToolLoopContext.for_loop(
+            _current_loop_ctx.get(), context.room.room.id if context.room else None
+        )
         _current_loop_ctx.set(loop_ctx)
         self._active_loops[loop_ctx.loop_id] = loop_ctx
         rounds: list[ToolRound] = []
+        empty_retries = 0
         try:
             context, should_cancel = self._drain_steering_queue(context, loop_ctx)
             if should_cancel:
@@ -462,6 +467,28 @@ class AIGenerationMixin:
 
             for round_idx in range(self._max_tool_rounds):
                 if not response.tool_calls or self._tool_handler is None:
+                    # Final answer reached. If it is empty *after* we ran tools,
+                    # the model skipped verbalizing the result — re-prompt once
+                    # (bounded) for the final answer instead of returning nothing.
+                    if (
+                        self._tool_handler is not None
+                        and rounds
+                        and not (response.content or "").strip()
+                        and empty_retries < self._max_empty_retries
+                        and not loop_ctx.cancel_event.is_set()
+                        and not (deadline and asyncio.get_running_loop().time() >= deadline)
+                    ):
+                        empty_retries += 1
+                        logger.warning(
+                            "Empty response after %d tool round(s); re-prompting for "
+                            "final answer (retry %d/%d)",
+                            len(rounds),
+                            empty_retries,
+                            self._max_empty_retries,
+                        )
+                        context.messages.append(AIMessage(role="user", content=_EMPTY_RETRY_NUDGE))
+                        response = await self._generate_with_retry(context)
+                        continue
                     break
 
                 if loop_ctx.cancel_event.is_set():

{roomkit-0.7.2 → roomkit-0.9.0}/src/roomkit/channels/_ai_streaming.py

@@ -8,6 +8,7 @@ import time
 from collections.abc import AsyncIterator
 from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
 
+from roomkit.channels._ai_events import THINKING_PREVIEW_LIMIT
 from roomkit.models.channel import ChannelOutput
 from roomkit.models.enums import ChannelType
 from roomkit.models.event import RoomEvent
@@ -41,6 +42,69 @@ if TYPE_CHECKING:
 logger = logging.getLogger("roomkit.channels.ai")
 
 
+class _ThinkingCoalescer:
+    """Batches per-token thinking deltas into one ``THINKING_DELTA`` publish per window.
+
+    Reasoning models emit one ``StreamThinkingDelta`` per token, and publishing
+    each on the realtime bus is one ephemeral event + fan-out + WS serialise per
+    token — thousands for a long trace, all on the shared event loop. Buffering
+    and publishing once per time/size window (~80 ms / ~256 chars) cuts that
+    10-100x while keeping the reasoning visibly real-time: the UI appends deltas,
+    so a coalesced delta renders identically to many small ones. The complete
+    trace is still published verbatim at ``THINKING_END``.
+
+    A window of ``0`` ms disables batching — every delta publishes immediately.
+    Flushes larger than ``_publish_thinking_event``'s preview cap are split
+    into multiple publishes so a coalesced delta is never truncated, whatever
+    the configured size threshold.
+    """
+
+    def __init__(
+        self,
+        publish: Any,
+        room_id: str | None,
+        round_idx: int,
+        *,
+        flush_ms: float,
+        flush_chars: int,
+    ) -> None:
+        self._publish = publish
+        self._room_id = room_id
+        self._round_idx = round_idx
+        self._flush_ms = flush_ms
+        self._flush_chars = flush_chars
+        self._pending: list[str] = []
+        self._pending_len = 0
+        self._last_publish = time.monotonic()
+
+    async def add(self, delta: str) -> None:
+        """Buffer a delta; publish the batch once the window is exceeded."""
+        self._pending.append(delta)
+        self._pending_len += len(delta)
+        if self._flush_ms <= 0:
+            await self.flush()
+            return
+        elapsed_ms = (time.monotonic() - self._last_publish) * 1000.0
+        if self._pending_len >= self._flush_chars or elapsed_ms >= self._flush_ms:
+            await self.flush()
+
+    async def flush(self) -> None:
+        """Publish whatever is buffered, then reset the window."""
+        if not self._pending:
+            return
+        text = "".join(self._pending)
+        self._pending.clear()
+        self._pending_len = 0
+        self._last_publish = time.monotonic()
+        for i in range(0, len(text), THINKING_PREVIEW_LIMIT):
+            await self._publish(
+                EphemeralEventType.THINKING_DELTA,
+                self._room_id,
+                text[i : i + THINKING_PREVIEW_LIMIT],
+                self._round_idx,
+            )
+
+
 @runtime_checkable
 class AIStreamingHost(Protocol):
     """Contract: capabilities a host class must provide for AIStreamingMixin.
@@ -70,6 +134,9 @@ class AIStreamingHost(Protocol):
     _max_tool_rounds: int
     _tool_loop_timeout_seconds: float | None
     _tool_loop_warn_after: int
+    _max_empty_retries: int
+    _thinking_coalesce_ms: float
+    _thinking_coalesce_chars: int
     _tool_handler: Any
     _active_loops: dict[str, _ToolLoopContext]
     _after_response_hook: Any
@@ -126,6 +193,9 @@ class AIStreamingMixin:
     _max_tool_rounds: int
     _tool_loop_timeout_seconds: float | None
     _tool_loop_warn_after: int
+    _max_empty_retries: int
+    _thinking_coalesce_ms: float
+    _thinking_coalesce_chars: int
     _tool_handler: Any
     _active_loops: dict[str, Any]
     _after_response_hook: Any
@@ -147,6 +217,16 @@ class AIStreamingMixin:
     _publish_tool_event: Any  # see AIStreamingHost
     _telemetry_provider: Any  # see AIStreamingHost
 
+    def _new_thinking_coalescer(self, room_id: str | None, round_idx: int) -> _ThinkingCoalescer:
+        """Coalescer bound to this channel's publish hook and window config."""
+        return _ThinkingCoalescer(
+            self._publish_thinking_event,
+            room_id,
+            round_idx,
+            flush_ms=self._thinking_coalesce_ms,
+            flush_chars=self._thinking_coalesce_chars,
+        )
+
     async def _start_streaming_response(
         self, event: RoomEvent, binding: ChannelBinding, context: RoomContext
     ) -> ChannelOutput:
@@ -190,6 +270,7 @@ class AIStreamingMixin:
         room_id = ai_context.room.room.id if ai_context.room else None
         thinking_parts: list[str] = []
         thinking_started = False
+        coalescer = self._new_thinking_coalescer(room_id, round_idx=0)
 
         async for ev in self._provider.generate_structured_stream(ai_context):
             if isinstance(ev, StreamThinkingDelta):
@@ -199,19 +280,17 @@ class AIStreamingMixin:
                         EphemeralEventType.THINKING_START, room_id, "", 0
                     )
                 thinking_parts.append(ev.thinking)
-                # Publish each delta on the realtime bus so remote subscribers
-                # (browser WS clients, etc.) see the reasoning stream as it
-                # arrives, not only the buffered text at THINKING_END. The
-                # ``thinking`` field carries the per-chunk delta, not the
+                # Buffer each delta and publish in windows on the realtime bus so
+                # remote subscribers (browser WS clients, etc.) stream the
+                # reasoning as it arrives, not only the buffered text at
+                # THINKING_END. The ``thinking`` field carries the delta, not the
                 # accumulator — clients append to their own buffer.
-                if room_id:
-                    await self._publish_thinking_event(
-                        EphemeralEventType.THINKING_DELTA, room_id, ev.thinking, 0
-                    )
+                await coalescer.add(ev.thinking)
                 yield ThinkingDeltaMarker(thinking=ev.thinking)
             elif isinstance(ev, StreamTextDelta):
                 if thinking_started and thinking_parts and room_id:
                     thinking_started = False
+                    await coalescer.flush()
                     await self._publish_thinking_event(
                         EphemeralEventType.THINKING_END,
                         room_id,
@@ -224,6 +303,7 @@ class AIStreamingMixin:
         # Thinking with no following text — close the boundary anyway so
         # subscribers see the reasoning even if the model emitted nothing else.
         if thinking_started and thinking_parts and room_id:
+            await coalescer.flush()
             await self._publish_thinking_event(
                 EphemeralEventType.THINKING_END,
                 room_id,
@@ -235,26 +315,42 @@ class AIStreamingMixin:
         self, event: RoomEvent, binding: ChannelBinding, context: RoomContext
     ) -> ChannelOutput:
         """Return a streaming response that handles tool calls between rounds."""
+        from roomkit.channels.ai import _current_loop_ctx
+
         ai_context = await self._build_context(event, binding, context)  # ty: ignore[unresolved-attribute]
         ai_context, blocked = await self._fire_before_generation_hook(ai_context, event)  # ty: ignore[unresolved-attribute]
         if blocked:
             return ChannelOutput.empty()
+        # The generator below executes when the CONSUMER iterates the
+        # stream — by then handle_event has reset the loop contextvar, so
+        # the parent ctx (participant role, room, the toolset stamped by
+        # _build_context) must be captured NOW and passed explicitly.
         return ChannelOutput(
             responded=True,
-            response_stream=self._run_streaming_tool_loop(ai_context),
+            response_stream=self._run_streaming_tool_loop(
+                ai_context, parent_loop_ctx=_current_loop_ctx.get()
+            ),
             response_metadata=ai_context.response_metadata,
         )
 
-    async def _run_streaming_tool_loop(self, context: AIContext) -> AsyncIterator[StreamDelta]:
+    async def _run_streaming_tool_loop(
+        self, context: AIContext, *, parent_loop_ctx: Any | None = None
+    ) -> AsyncIterator[StreamDelta]:
         """Stream text deltas, executing tool calls between generation rounds."""
-        from roomkit.channels.ai import _current_loop_ctx, _ToolLoopContext
+        from roomkit.channels.ai import (
+            _EMPTY_RETRY_NUDGE,
+            _current_loop_ctx,
+            _ToolLoopContext,
+        )
         from roomkit.telemetry.context import get_current_span
 
-        loop_ctx = _ToolLoopContext()
-        loop_ctx.loop_id = str(id(loop_ctx))
-        parent_ctx = _current_loop_ctx.get()
-        if parent_ctx is not None:
-            loop_ctx.current_participant_role = parent_ctx.current_participant_role
+        # The handle_event ctx is gone from the contextvar by the time this
+        # generator runs (reset in handle_event's finally); the caller
+        # captured it at stream creation.
+        parent_ctx = parent_loop_ctx if parent_loop_ctx is not None else _current_loop_ctx.get()
+        loop_ctx = _ToolLoopContext.for_loop(
+            parent_ctx, context.room.room.id if context.room else None
+        )
         _current_loop_ctx.set(loop_ctx)
         self._active_loops[loop_ctx.loop_id] = loop_ctx
         telemetry = self._telemetry_provider
@@ -287,6 +383,8 @@ class AIStreamingMixin:
             )
 
             _dedup_prefix = ""
+            _saw_tool_call_any = False
+            _empty_retries = 0
 
             for _round_idx in range(self._max_tool_rounds + 1):
                 if loop_ctx.cancel_event.is_set():
@@ -302,6 +400,7 @@ class AIStreamingMixin:
                 text_parts: list[str] = []
                 tool_calls: list[StreamToolCall] = []
                 thinking_started = False
+                coalescer = self._new_thinking_coalescer(room_id, round_idx=_round_idx)
                 _dedup_active = bool(_dedup_prefix)
                 _dedup_offset = 0
                 _dedup_buffer: list[str] = []
@@ -323,23 +422,18 @@ class AIStreamingMixin:
                                 _round_idx,
                             )
                         thinking_parts.append(event.thinking)
-                        # Publish the per-chunk delta on the realtime bus so
-                        # remote WS subscribers stream the reasoning live; the
-                        # buffered THINKING_END below still fires so observers
-                        # joining mid-stream can recover the complete trace.
-                        if room_id:
-                            await self._publish_thinking_event(
-                                EphemeralEventType.THINKING_DELTA,
-                                room_id,
-                                event.thinking,
-                                _round_idx,
-                            )
+                        # Buffer the per-chunk delta and publish in windows on the
+                        # realtime bus so remote WS subscribers stream the reasoning
+                        # live; the buffered THINKING_END below still fires so
+                        # observers joining mid-stream recover the complete trace.
+                        await coalescer.add(event.thinking)
                         # Inline marker so channels can render reasoning in
                         # arrival order with text deltas.
                         yield ThinkingDeltaMarker(thinking=event.thinking)
                     elif isinstance(event, StreamTextDelta):
                         if thinking_started and thinking_parts and room_id:
                             thinking_started = False
+                            await coalescer.flush()
                             await self._publish_thinking_event(
                                 EphemeralEventType.THINKING_END,
                                 room_id,
@@ -457,6 +551,7 @@ class AIStreamingMixin:
                     _dedup_buffer.clear()
 
                 if thinking_started and thinking_parts and room_id:
+                    await coalescer.flush()
                     await self._publish_thinking_event(
                         EphemeralEventType.THINKING_END,
                         room_id,
@@ -465,8 +560,28 @@ class AIStreamingMixin:
                     )
 
                 if not tool_calls:
+                    # Final answer round. If it produced no text *after* a tool
+                    # round, the model skipped verbalizing the result — re-prompt
+                    # once (bounded) for the final answer instead of ending empty.
+                    if (
+                        _saw_tool_call_any
+                        and not "".join(text_parts).strip()
+                        and _empty_retries < self._max_empty_retries
+                        and not (deadline and asyncio.get_running_loop().time() >= deadline)
+                    ):
+                        _empty_retries += 1
+                        logger.warning(
+                            "Streaming empty response after tools; re-prompting for "
+                            "final answer (retry %d/%d)",
+                            _empty_retries,
+                            self._max_empty_retries,
+                        )
+                        context.messages.append(AIMessage(role="user", content=_EMPTY_RETRY_NUDGE))
+                        continue
                     return
 
+                _saw_tool_call_any = True
+
                 # External tools: provider executed them internally.
                 # If ExternalToolHandler is set, hooks were already fired
                 # inline during streaming (see StreamToolCall handling above).