unique-toolkit 2026.20.0.dev34__tar.gz → 2026.20.0.dev35__tar.gz

{unique_toolkit-2026.20.0.dev34 → unique_toolkit-2026.20.0.dev35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-toolkit
-Version: 2026.20.0.dev34
+Version: 2026.20.0.dev35
 Summary: 
 Author: Cedric Klinkert, Martin Fadler, Sadique Sheik, Fabian Schläpfer, Pascal Hauri, Ejiroghene Oki-Peter, Rami Azouz, Ricardo Visini, Sanzio Monti
 Author-email: Cedric Klinkert <cedric.klinkert@unique.ch>, Martin Fadler <martin.fadler@unique.ch>, Sadique Sheik <sadique@unique.ch>, Fabian Schläpfer <fabian@unique.ch>, Pascal Hauri <pascal@unique.ch>, Ejiroghene Oki-Peter <oki-peter.ejiroghene@unique.ai>, Rami Azouz <rami.ext@unique.ch>, Ricardo Visini <ricardo.visini@unique.ch>, Sanzio Monti <sanzio.monti@unique.ai>

{unique_toolkit-2026.20.0.dev34 → unique_toolkit-2026.20.0.dev35}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_toolkit"
-version = "2026.20.0.dev34"
+version = "2026.20.0.dev35"
 description = ""
 readme = "README.md"
 requires-python = ">=3.12"
@@ -137,6 +137,10 @@ DEP004 = ["langchain_openai", "langchain_core"]
 #   7. components never call unique_sdk directly (go through a resource)
 #   8. each integrations/<framework>/ stands alone — enabled when real modules land
 #
+# Imports under ``if TYPE_CHECKING:`` are excluded from the graph (see
+# ``exclude_type_checking_imports``) so type-only imports (e.g. ``unique_sdk``)
+# do not violate layer/forbidden contracts. Runtime imports are still enforced.
+#
 # Preference rules from the README that are NOT machine-enforced (import-linter
 # is pass/fail, not tiered): integrations prefer facades over primitives;
 # integrations importing components is "discouraged but allowed".
@@ -144,6 +148,7 @@ DEP004 = ["langchain_openai", "langchain_core"]
 [tool.importlinter]
 root_packages = ["unique_toolkit"]
 include_external_packages = true
+exclude_type_checking_imports = true
 
 [[tool.importlinter.contracts]]
 name = "experimental: integrations stack (integrations → resources → _internal)"

{unique_toolkit-2026.20.0.dev34 → unique_toolkit-2026.20.0.dev35}/unique_toolkit/_common/event_bus.py

@@ -96,7 +96,28 @@ class TypedEventBus(Generic[T]):
     async def publish_and_wait_async(
         self, event: T, *, return_exceptions: bool = False
     ) -> None:
-        """Invoke every handler and await completion."""
-        coros = [self._invoke(h, event) for h in list(self._handlers)]
-        if coros:
-            await asyncio.gather(*coros, return_exceptions=return_exceptions)
+        """Invoke every handler and await completion.
+
+        When ``return_exceptions=True`` failures from one subscriber do not
+        cancel the others, and each swallowed exception is logged. Use this
+        at hot-path publish sites (e.g. ``text_delta``) where a single flaky
+        analytics subscriber should not abort the stream.
+        """
+        handlers = list(self._handlers)
+        coros = [self._invoke(h, event) for h in handlers]
+        if not coros:
+            return
+        if return_exceptions:
+            results = await asyncio.gather(*coros, return_exceptions=True)
+            for handler, result in zip(handlers, results):
+                if isinstance(result, BaseException) and not isinstance(
+                    result, asyncio.CancelledError
+                ):
+                    logger.error(
+                        "Subscriber %r raised during publish; swallowing: %r",
+                        handler,
+                        result,
+                        exc_info=result,
+                    )
+        else:
+            await asyncio.gather(*coros)

{unique_toolkit-2026.20.0.dev34 → unique_toolkit-2026.20.0.dev35}/unique_toolkit/agentic/loop_runner/_responses_stream_handler_utils.py

@@ -2,8 +2,6 @@ from typing import Any, Required, Sequence
 
 from openai.types.responses import (
     ResponseIncludable,
-    ResponseInputItemParam,
-    ResponseOutputItem,
     ResponseTextConfigParam,
     ToolParam,
     response_create_params,
@@ -13,22 +11,15 @@ from typing_extensions import TypedDict
 
 from unique_toolkit import LanguageModelToolDescription
 from unique_toolkit.agentic.loop_runner.base import _ResponsesLoopIterationRunnerKwargs
-from unique_toolkit.chat.service import LanguageModelMessages
 from unique_toolkit.content import ContentChunk
 from unique_toolkit.language_model.schemas import (
-    LanguageModelMessageOptions,
     ResponsesLanguageModelStreamResponse,
+    ResponsesMessageInput,
 )
 
 
 class _ResponsesStreamingHandlerKwargs(TypedDict, total=False):
-    messages: Required[
-        str
-        | LanguageModelMessages
-        | Sequence[
-            ResponseInputItemParam | LanguageModelMessageOptions | ResponseOutputItem
-        ]
-    ]
+    messages: Required[ResponsesMessageInput]
     model_name: Required[str]
     tools: Sequence[LanguageModelToolDescription | ToolParam]
     content_chunks: list[ContentChunk]

{unique_toolkit-2026.20.0.dev34 → unique_toolkit-2026.20.0.dev35}/unique_toolkit/agentic/loop_runner/base.py

@@ -1,10 +1,8 @@
-from typing import Any, Protocol, Required, Sequence, Unpack
+from typing import Any, Protocol, Required, Unpack
 
 from openai.types.chat import ChatCompletionNamedToolChoiceParam
 from openai.types.responses import (
     ResponseIncludable,
-    ResponseInputItemParam,
-    ResponseOutputItem,
     ResponseTextConfigParam,
     ToolParam,
     response_create_params,
@@ -18,8 +16,8 @@ from unique_toolkit.chat.service import LanguageModelMessages
 from unique_toolkit.content import ContentChunk
 from unique_toolkit.language_model.infos import LanguageModelInfo
 from unique_toolkit.language_model.schemas import (
-    LanguageModelMessageOptions,
     ResponsesLanguageModelStreamResponse,
+    ResponsesMessageInput,
 )
 from unique_toolkit.protocols.support import (
     ResponsesSupportCompleteWithReferences,
@@ -55,13 +53,7 @@ class LoopIterationRunner(Protocol):
 class _ResponsesLoopIterationRunnerKwargs(TypedDict, total=False):
     iteration_index: Required[int]
     streaming_handler: Required[ResponsesSupportCompleteWithReferences]
-    messages: Required[
-        str
-        | LanguageModelMessages
-        | Sequence[
-            ResponseInputItemParam | LanguageModelMessageOptions | ResponseOutputItem
-        ]
-    ]
+    messages: Required[ResponsesMessageInput]
     model: Required[LanguageModelInfo]
     tools: list[LanguageModelToolDescription | ToolParam]
     content_chunks: list[ContentChunk]

{unique_toolkit-2026.20.0.dev34 → unique_toolkit-2026.20.0.dev35}/unique_toolkit/agentic/loop_runner/middleware/planning/planning.py

@@ -1,12 +1,14 @@
 import json
 import logging
-from typing import Any, Unpack
+from collections.abc import Sequence
+from typing import Any, TypeGuard, Unpack
 
 from openai import AsyncOpenAI
 from openai.types.responses import (
     Response,
     ResponseFunctionToolCall,
     ResponseInputItemParam,
+    ResponseOutputItem,
     ToolParam,
 )
 from openai.types.responses.function_tool_param import FunctionToolParam
@@ -26,13 +28,17 @@ from unique_toolkit.agentic.loop_runner.middleware.planning.schema import (
     PlanningSchemaConfig,
     get_planning_schema,
 )
-from unique_toolkit.chat.responses_api import convert_messages_to_openai
+from unique_toolkit.chat.responses_api import (
+    _convert_messages_to_openai,
+    convert_messages_to_openai,
+)
 from unique_toolkit.chat.service import LanguageModelStreamResponse
 from unique_toolkit.language_model import (
     LanguageModelAssistantMessage,
     LanguageModelUserMessage,
 )
 from unique_toolkit.language_model.schemas import (
+    LanguageModelMessageOptions,
     LanguageModelMessages,
     ResponsesLanguageModelStreamResponse,
 )
@@ -45,6 +51,30 @@ _PLAN_TOOL_DESCRIPTION = (
     "Record the plan for the next step. Call this tool exactly once."
 )
 
+
+def _is_language_model_messages(
+    msgs: Sequence[object],
+) -> TypeGuard[list[LanguageModelMessageOptions]]:
+    return len(msgs) > 0 and all(
+        isinstance(m, LanguageModelMessageOptions) for m in msgs
+    )
+
+
+def _is_response_input_items(
+    msgs: Sequence[object],
+) -> TypeGuard[list[ResponseInputItemParam]]:
+    return len(msgs) > 0 and all(isinstance(m, dict) for m in msgs)
+
+
+def _is_response_output_items(
+    msgs: Sequence[object],
+) -> TypeGuard[list[ResponseOutputItem]]:
+    return len(msgs) > 0 and all(
+        isinstance(m, BaseModel) and not isinstance(m, LanguageModelMessageOptions)
+        for m in msgs
+    )
+
+
 # Kwargs from _ResponsesLoopIterationRunnerKwargs that make sense to forward to
 # the planning `responses.create` call. We deliberately exclude anything that
 # conflicts with the forced-tool-call setup (`tools`, `tool_choices`, `text`,
@@ -270,6 +300,22 @@ class ResponsesPlanningMiddleware(ResponsesLoopIterationRunner):
                 kwargs["messages"].builder().append(assistant_message).build()
             )
         else:
-            kwargs["messages"] = list(kwargs["messages"]) + [assistant_message]
+            message_items = list(kwargs["messages"])
+            assistant_items = _convert_messages_to_openai([assistant_message])
+            if _is_language_model_messages(message_items):
+                kwargs["messages"] = [*message_items, assistant_message]
+            elif _is_response_input_items(message_items):
+                kwargs["messages"] = [*message_items, *assistant_items]
+            elif _is_response_output_items(message_items):
+                kwargs["messages"] = [
+                    *_convert_messages_to_openai(message_items),
+                    *assistant_items,
+                ]
+            else:
+                raise TypeError(
+                    "messages must be a homogeneous list of "
+                    "LanguageModelMessageOptions, ResponseInputItemParam dicts, "
+                    "or ResponseOutputItem models"
+                )
 
         return await self._loop_runner(**kwargs)

{unique_toolkit-2026.20.0.dev34 → unique_toolkit-2026.20.0.dev35}/unique_toolkit/chat/responses_api.py

@@ -9,7 +9,6 @@ from openai.types.responses import (
     ResponseIncludable,
     ResponseInputItemParam,
     ResponseInputParam,
-    ResponseOutputItem,
     ResponseTextConfigParam,
     ToolParam,
     response_create_params,
@@ -50,6 +49,8 @@ from unique_toolkit.language_model.schemas import (
     LanguageModelToolMessage,
     LanguageModelUserMessage,
     ResponsesLanguageModelStreamResponse,
+    ResponsesMessageInput,
+    ResponsesMessageSequence,
     reasoning_effort_to_openai,
 )
 
@@ -101,9 +102,7 @@ def _convert_to_specific_message(
 
 
 def _convert_messages_to_openai(
-    messages: Sequence[
-        ResponseInputItemParam | LanguageModelMessageOptions | ResponseOutputItem
-    ],
+    messages: ResponsesMessageSequence,
 ) -> ResponseInputParam:
     res = []
     for message in messages:
@@ -121,11 +120,7 @@ def _convert_messages_to_openai(
 
 
 def convert_messages_to_openai(
-    messages: str
-    | LanguageModelMessages
-    | Sequence[
-        ResponseInputItemParam | LanguageModelMessageOptions | ResponseOutputItem
-    ],
+    messages: ResponsesMessageInput,
 ) -> str | list[ResponseInputItemParam]:
     if isinstance(messages, str):
         return messages
@@ -149,11 +144,7 @@ def _prepare_responses_params_util(
     content_chunks: list[ContentChunk] | None,
     temperature: float,
     tools: Sequence[LanguageModelToolDescription | ToolParam] | None,
-    messages: str
-    | LanguageModelMessages
-    | Sequence[
-        ResponseInputItemParam | LanguageModelMessageOptions | ResponseOutputItem
-    ],
+    messages: ResponsesMessageInput,
     reasoning: Reasoning | None,
     text: ResponseTextConfigParam | None,
     other_options: dict[str, Any] | None = None,
@@ -463,11 +454,7 @@ def stream_responses_with_references(
     chat_id: str,
     assistant_id: str,
     model_name: LanguageModelName | str,
-    messages: str
-    | LanguageModelMessages
-    | Sequence[
-        ResponseInputItemParam | LanguageModelMessageOptions | ResponseOutputItem
-    ],
+    messages: ResponsesMessageInput,
     content_chunks: list[ContentChunk] | None = None,
     tools: Sequence[LanguageModelToolDescription | ToolParam] | None = None,
     temperature: float = DEFAULT_COMPLETE_TEMPERATURE,
@@ -531,11 +518,7 @@ async def stream_responses_with_references_async(
     chat_id: str,
     assistant_id: str,
     model_name: LanguageModelName | str,
-    messages: str
-    | LanguageModelMessages
-    | Sequence[
-        ResponseInputItemParam | LanguageModelMessageOptions | ResponseOutputItem
-    ],
+    messages: ResponsesMessageInput,
     content_chunks: list[ContentChunk] | None = None,
     tools: Sequence[LanguageModelToolDescription | ToolParam] | None = None,
     temperature: float = DEFAULT_COMPLETE_TEMPERATURE,

{unique_toolkit-2026.20.0.dev34 → unique_toolkit-2026.20.0.dev35}/unique_toolkit/content/schemas.py

@@ -76,6 +76,22 @@ class ContentChunk(BaseModel):
     created_at: datetime | None = None
     updated_at: datetime | None = None
 
+    def to_sdk_reference(
+        self,
+        sequence_number: int,
+    ) -> unique_sdk.Message.Reference:
+        """Convert ``ContentChunk`` objects to ``unique_sdk.Message.Reference`` TypedDicts."""
+
+        return unique_sdk.Message.Reference(
+            name=self.title or self.key or self.id or "",
+            url=self.url or f"unique://content/{self.id}",
+            sequenceNumber=sequence_number + 1,
+            sourceId=(f"{self.id}_{self.chunk_id}" if self.chunk_id else self.id or ""),
+            source="node-ingestion-chunks",
+            description=None,
+            originalIndex=[sequence_number + 1],
+        )
+
     def to_reference(
         self,
         sequence_number: int,

unique_toolkit-2026.20.0.dev35/unique_toolkit/experimental/_internal/streaming/__init__.py

@@ -0,0 +1,35 @@
+"""Framework-agnostic streaming components.
+
+This subpackage exposes streaming behaviour that is useful beyond a single
+third-party framework: event handler contracts, text state payloads, citation
+normalisation, and other provider-neutral primitives. Concrete framework
+adapters live under :mod:`unique_toolkit.experimental.integrations`.
+"""
+
+from __future__ import annotations
+
+from .common import (
+    ActivityProducer,
+    ActivityProgressUpdate,
+    ActivityStatus,
+    AppendixProducer,
+    StreamEventHandlerProtocol,
+    StreamTextEventHandlerProtocol,
+    StreamToolCallEventHandlerProtocol,
+    TextFlushed,
+    TextState,
+    UsageProducer,
+)
+
+__all__ = [
+    "ActivityProducer",
+    "ActivityProgressUpdate",
+    "ActivityStatus",
+    "AppendixProducer",
+    "StreamEventHandlerProtocol",
+    "StreamTextEventHandlerProtocol",
+    "StreamToolCallEventHandlerProtocol",
+    "TextFlushed",
+    "TextState",
+    "UsageProducer",
+]

unique_toolkit-2026.20.0.dev35/unique_toolkit/experimental/_internal/streaming/common.py

@@ -0,0 +1,208 @@
+"""Framework-agnostic streaming event handler types and lifecycle contract.
+
+These types are **framework-agnostic** on purpose: they live in the
+toolkit's domain-layer ``protocols`` package so alternative framework
+adapters (future providers beyond OpenAI) can realize the same event handler
+shape without pulling in OpenAI-specific imports. Concrete, OpenAI-typed
+event handler protocols live next to their implementations under
+``unique_toolkit.experimental.integrations.openai.streaming.event_routing.protocols``.
+
+This module declares:
+
+* The lifecycle contract every streaming event handler realizes
+  (:class:`StreamEventHandlerProtocol`) plus the accumulated-text value
+  (:class:`TextState`).
+* Role-shaped base protocols that group members shared by every
+  implementation of a role, regardless of the underlying API:
+  :class:`StreamTextEventHandlerProtocol` for text accumulators and
+  :class:`StreamToolCallEventHandlerProtocol` for tool-call accumulators.
+  Framework-specific subprotocols only add the vendor-typed consumer
+  methods (e.g. ``on_chunk`` / ``on_text_delta``).
+* Event-handler bus payload dataclasses (:class:`TextFlushed`,
+  :class:`ActivityProgressUpdate`) — carried on per-event handler
+  :class:`TypedEventBus` instances, adapted by the orchestrator onto the
+  outer :class:`StreamEventBus`.
+* Structural capability protocols event routing aggregate across event handlers
+  (:class:`AppendixProducer`, :class:`ActivityProducer`,
+  :class:`UsageProducer`).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from unique_toolkit._common.event_bus import TypedEventBus
+    from unique_toolkit.language_model.schemas import (
+        LanguageModelFunction,
+        LanguageModelTokenUsage,
+    )
+
+ActivityStatus = Literal["RUNNING", "COMPLETED", "FAILED"]
+"""Lifecycle state of a tool-like activity exposed to subscribers.
+
+Framework-agnostic: the values describe observable progress (running,
+finished, failed) without coupling to any vendor's event taxonomy. Lives
+with :class:`ActivityProgressUpdate` because one is the type of the
+other's ``status`` field.
+"""
+
+
+@dataclass
+class TextState:
+    """Accumulated assistant text: normalised (``full_text``) and raw model output (``original_text``)."""
+
+    full_text: str
+    original_text: str
+
+
+class StreamEventHandlerProtocol(Protocol):
+    """Lifecycle methods shared by every event handler (any OpenAI streaming surface).
+
+    Event handlers that need to surface per-event signals (text flushes, tool
+    activity progress, …) expose an event-handler-owned :class:`TypedEventBus`
+    instead of returning a signal from their lifecycle methods — see
+    :class:`TextFlushed` / :class:`ActivityProgressUpdate` for payloads.
+    """
+
+    async def on_stream_end(self) -> None:
+        """Finalize after the stream is exhausted (flush buffers, release resources)."""
+        ...
+
+    def reset(self) -> None:
+        """Clear all per-run state for reuse."""
+        ...
+
+
+@dataclass(frozen=True, slots=True)
+class TextFlushed:
+    """The text event handler crossed a flush boundary.
+
+    Carried on the event-handler-owned :class:`TypedEventBus` so subscribers
+    (typically the orchestrator) can adapt it into a full :class:`TextUpdate`
+    by attaching request context (``message_id`` / ``chat_id``). The
+    payload mirrors the event handler's current :meth:`get_text` state at the
+    moment of the flush.
+
+    Flush boundaries combine two concerns: replacer hold-back release
+    (e.g. a partial ``[source`` pattern finishing into ``[source1]``) and
+    throttling (e.g. ``send_every_n_events`` on the Chat Completions
+    event handler). The event handler stays ignorant of the outer bus and identity
+    context — it only reports "now is a good time to publish".
+    """
+
+    full_text: str
+    original_text: str
+    chunk_index: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ActivityProgressUpdate:
+    """Event-handler-local description of a single tool-activity progress transition.
+
+    Carried on the event-handler-owned :class:`TypedEventBus` so the orchestrator
+    can adapt it into an :class:`ActivityProgress` outer-bus event by
+    attaching ``message_id`` / ``chat_id``. Event handlers that participate in
+    tool-activity tracking publish one of these per genuine state change
+    (deduplicated at the event handler level).
+    """
+
+    correlation_id: str
+    status: ActivityStatus
+    text: str
+    order: int = 0
+
+
+@runtime_checkable
+class AppendixProducer(Protocol):
+    """Optional capability: the event handler contributes to the final assistant message.
+
+    When present, the event routing aggregates appendices across event handlers and
+    attaches the tuple to :class:`StreamEnded`, so the message persister
+    writes ``full_text + "".join(appendices)`` in a single round-trip. A
+    return value of ``None`` means "nothing to append this run".
+    """
+
+    def get_appendix(self) -> str | None:
+        """Return the text to append, or ``None`` if this run contributed nothing."""
+        ...
+
+
+@runtime_checkable
+class ActivityProducer(Protocol):
+    """Optional capability: the event handler reports tool-activity progress.
+
+    Realizers expose an event-handler-owned :class:`TypedEventBus` publishing
+    :class:`ActivityProgressUpdate` payloads on each genuine state
+    transition (deduplicated at the event handler level). The orchestrator
+    subscribes to this bus and adapts the updates onto the outer
+    :class:`StreamEventBus` by attaching request context. Mirrors
+    :class:`AppendixProducer` in spirit: both are named capabilities the
+    event routing discovers on event handlers at wire-up time.
+    """
+
+    @property
+    def activity_bus(self) -> TypedEventBus[ActivityProgressUpdate]:
+        """Event-handler-owned bus publishing progress updates per state transition."""
+        ...
+
+
+@runtime_checkable
+class UsageProducer(Protocol):
+    """Optional capability: the event handler exposes token usage for a completed stream.
+
+    Different streaming APIs surface usage in different places (for example,
+    Responses has a completed event while other APIs may attach usage to a
+    terminal chunk). This capability lets provider-specific event handlers expose
+    the normalized toolkit usage shape without coupling the base lifecycle
+    protocol to token accounting.
+    """
+
+    def get_usage(self) -> LanguageModelTokenUsage | None:
+        """Return normalized token usage, or ``None`` when unavailable."""
+        ...
+
+
+class StreamTextEventHandlerProtocol(StreamEventHandlerProtocol, Protocol):
+    """Base contract for any event handler that accumulates assistant text from a stream.
+
+    Captures the role members shared by every text event handler regardless of
+    the upstream API: an event-handler-owned :class:`TypedEventBus` publishing
+    :class:`TextFlushed` at flush boundaries, plus :meth:`get_text` for
+    inspecting the accumulated state. Framework-specific subprotocols
+    add only the vendor-typed consumer method (e.g.
+    ``on_chunk(ChatCompletionChunk)`` for Chat Completions,
+    ``on_text_delta(ResponseTextDeltaEvent)`` for Responses).
+
+    Pure state machine by design: no SDK, no outer bus, no knowledge of
+    retrieved chunks — subscribers (typically the orchestrator) adapt
+    :class:`TextFlushed` into full :class:`TextUpdate` events by attaching
+    request context.
+    """
+
+    @property
+    def text_bus(self) -> TypedEventBus[TextFlushed]:
+        """Event-handler-owned bus publishing :class:`TextFlushed` at flush boundaries."""
+        ...
+
+    def get_text(self) -> TextState:
+        """Return accumulated normalised and original text."""
+        ...
+
+
+class StreamToolCallEventHandlerProtocol(StreamEventHandlerProtocol, Protocol):
+    """Base contract for any event handler that accumulates tool calls from a stream.
+
+    Captures the role members shared by every tool-call event handler
+    regardless of the upstream API: :meth:`get_tool_calls` returns the
+    accumulated list of :class:`LanguageModelFunction`. Framework-specific
+    subprotocols add only the vendor-typed consumer method(s) (e.g.
+    ``on_chunk(ChatCompletionChunk)`` for Chat Completions, or the pair
+    ``on_output_item_added`` / ``on_function_arguments_done`` for
+    Responses).
+    """
+
+    def get_tool_calls(self) -> list[LanguageModelFunction]:
+        """Return the list of tool calls observed so far, in arrival order."""
+        ...