axio-responses 0.11.0__py3-none-any.whl

axio_responses/__init__.py

@@ -0,0 +1,67 @@
+"""The OpenAI Responses API as axio speaks it.
+
+``convert_messages`` and ``convert_tools`` build the request. ``Responses`` reads the stream it
+answers with. Both halves are here rather than in a transport because two transports speak this
+API: the public ``/v1/responses`` endpoint and the ChatGPT backend Codex uses.
+"""
+
+from __future__ import annotations
+
+from .reader import (
+    Annotation,
+    AnnotationAdded,
+    AnnotationSource,
+    ArgumentsDelta,
+    ArgumentsDone,
+    Completed,
+    ContentPartDone,
+    Created,
+    Failed,
+    Incomplete,
+    IncompleteDetails,
+    InputDetails,
+    ItemAdded,
+    ItemDone,
+    OutputDetails,
+    OutputItem,
+    ReasoningDeltaEvent,
+    RefusalDeltaEvent,
+    ResponseError,
+    ResponseObject,
+    Responses,
+    ResponseUsage,
+    StreamFailure,
+    TextDeltaEvent,
+)
+from .request import STOP_REASONS, convert_messages, convert_tools, tool_output
+
+__all__ = [
+    "STOP_REASONS",
+    "Annotation",
+    "AnnotationAdded",
+    "AnnotationSource",
+    "ArgumentsDelta",
+    "ArgumentsDone",
+    "ContentPartDone",
+    "Completed",
+    "Created",
+    "Failed",
+    "Incomplete",
+    "IncompleteDetails",
+    "InputDetails",
+    "ItemAdded",
+    "ItemDone",
+    "OutputDetails",
+    "OutputItem",
+    "ReasoningDeltaEvent",
+    "RefusalDeltaEvent",
+    "ResponseError",
+    "ResponseObject",
+    "ResponseUsage",
+    "Responses",
+    "StreamFailure",
+    "TextDeltaEvent",
+    "convert_messages",
+    "convert_tools",
+    "tool_output",
+]

axio_responses/reader.py

@@ -0,0 +1,460 @@
+"""Reading a Responses stream: the payload shapes, and what each event becomes.
+
+The vocabulary is the published ``ResponseStreamEvent`` union. An event missing from ``Responses``
+is one the API added after this was written, not one nobody named. A test reading with
+``strict=True`` holds that against the schema.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from typing import Final
+
+from axio.events import (
+    BlockEnd,
+    Citation,
+    IterationEnd,
+    IterationStart,
+    ProviderEvent,
+    ProviderOutput,
+    ReasoningDelta,
+    ReasoningSignature,
+    Refusal,
+    StreamEvent,
+    TextDelta,
+    ToolInputDelta,
+    ToolUseStart,
+)
+from axio.exceptions import StreamError
+from axio.types import StopReason, Usage, stop_reason_from
+from axio_sse import Payload, Reader, Wire, on
+
+from .request import PROVIDER, STOP_REASONS
+
+logger = logging.getLogger("axio.responses")
+
+#: Item types this reader turns into content of its own. Everything else is the API's own tooling
+#: — a search it ran, a file it read, code it executed — and has to travel back unread.
+_INTERPRETED: Final = frozenset({"message", "reasoning", "function_call"})
+
+
+@dataclass(frozen=True, slots=True)
+class InputDetails(Wire):
+    cached_tokens: int = 0
+    cache_write_tokens: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class OutputDetails(Wire):
+    reasoning_tokens: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class ResponseUsage(Wire):
+    """Both slices arrive inside their totals here, so the reader adds nothing to either."""
+
+    input_tokens: int = 0
+    output_tokens: int = 0
+    input_tokens_details: InputDetails = field(default_factory=InputDetails)
+    output_tokens_details: OutputDetails = field(default_factory=OutputDetails)
+
+
+@dataclass(frozen=True, slots=True)
+class OutputItem(Wire):
+    type: str = ""
+    id: str = ""
+    call_id: str = ""
+    name: str = ""
+    #: Present on a ``reasoning`` item when the request asked for it. Opaque, and sent back on
+    #: the next request.
+    encrypted_content: str = ""
+    #: The item exactly as it arrived. An item this reader does not interpret has to go back whole
+    #: on the next request, and no shape declared here would hold a type nobody has published yet.
+    raw: Payload = field(default_factory=Payload)
+
+
+@dataclass(frozen=True, slots=True)
+class IncompleteDetails(Wire):
+    reason: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class ResponseError(Wire):
+    message: str = ""
+    code: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class ResponseObject(Wire):
+    id: str = ""
+    model: str = ""
+    status: str = ""
+    usage: ResponseUsage = field(default_factory=ResponseUsage)
+    output: list[OutputItem] = field(default_factory=list)
+    error: ResponseError = field(default_factory=ResponseError)
+    incomplete_details: IncompleteDetails = field(default_factory=IncompleteDetails)
+
+
+@dataclass(frozen=True, slots=True)
+class AnnotationSource(Wire):
+    url: str = ""
+    filename: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class Annotation(Wire):
+    """One attribution. It arrives under a url shape, a file shape and the older flat citation, so
+    each field is declared wherever a shape put it. The whole object travels in ``raw``."""
+
+    text: str = ""
+    title: str | None = None
+    url: str | None = None
+    file_id: str | None = None
+    source: AnnotationSource = field(default_factory=AnnotationSource)
+    start_index: int | None = None
+    end_index: int | None = None
+    raw: Payload = field(default_factory=Payload)
+
+
+@dataclass(frozen=True, slots=True)
+class Created(Wire, name="response.created"):
+    response: ResponseObject = field(default_factory=ResponseObject)
+
+
+@dataclass(frozen=True, slots=True)
+class Completed(Wire, name="response.completed"):
+    response: ResponseObject = field(default_factory=ResponseObject)
+
+
+@dataclass(frozen=True, slots=True)
+class Incomplete(Wire, name="response.incomplete"):
+    response: ResponseObject = field(default_factory=ResponseObject)
+
+
+@dataclass(frozen=True, slots=True)
+class Failed(Wire, name="response.failed"):
+    response: ResponseObject = field(default_factory=ResponseObject)
+
+
+@dataclass(frozen=True, slots=True)
+class StreamFailure(Wire, name="error"):
+    """The stream's own error, which carries no response object."""
+
+    message: str = ""
+    code: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class TextDeltaEvent(Wire, name="response.output_text.delta"):
+    delta: str = ""
+    #: Which output item this belongs to. Fixed at zero, every delta of a multi-item response
+    #: shared one index while the events that close a block kept the real one.
+    output_index: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class ReasoningDeltaEvent(Wire, name="response.reasoning_summary_text.delta", also="response.reasoning_text.delta"):
+    """Both reasoning channels read the same. A model that sends the text rather than the summary
+    would otherwise think in silence."""
+
+    delta: str = ""
+    output_index: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class RefusalDeltaEvent(Wire, name="response.refusal.delta"):
+    delta: str = ""
+    output_index: int = 0
+    raw: Payload = field(default_factory=Payload)
+
+
+@dataclass(frozen=True, slots=True)
+class AnnotationAdded(Wire, name="response.output_text.annotation.added"):
+    #: Which output item the cited text belongs to. The deltas and the closing event are indexed
+    #: by this, not by content_index.
+    output_index: int = 0
+    #: Which content part inside that item, which axio has no index of its own for.
+    content_index: int = 0
+    annotation: Annotation = field(default_factory=Annotation)
+
+
+@dataclass(frozen=True, slots=True)
+class ContentPartDone(Wire, name="response.content_part.done"):
+    output_index: int = 0
+    content_index: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class ItemDone(Wire, name="response.output_item.done"):
+    output_index: int = 0
+    item: OutputItem = field(default_factory=OutputItem)
+
+
+@dataclass(frozen=True, slots=True)
+class ItemAdded(Wire, name="response.output_item.added"):
+    output_index: int = 0
+    item: OutputItem = field(default_factory=OutputItem)
+
+
+@dataclass(frozen=True, slots=True)
+class ArgumentsDelta(Wire, name="response.function_call_arguments.delta"):
+    item_id: str = ""
+    output_index: int = 0
+    delta: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class ArgumentsDone(Wire, name="response.function_call_arguments.done"):
+    item_id: str = ""
+    name: str = ""
+    arguments: str = ""
+
+
+class Responses(Reader[StreamEvent]):
+    """Every event the Responses API sends, and what each one becomes.
+
+    The vocabulary is the published ``ResponseStreamEvent`` union. An event missing from this body
+    is one the API added after it was written, not one nobody named. A test reading
+    with ``strict=True`` holds that against the schema.
+
+    One instance reads one response. Its state is the usage, the stop reason and the id map.
+    """
+
+    def __init__(self) -> None:
+        self.usage = Usage(0, 0)
+        self.stop_reason: StopReason | None = None
+        # item_id -> call_id, so a ToolInputDelta carries the id ToolUseStart announced.
+        self.call_ids: dict[str, str] = {}
+
+    @on(TextDeltaEvent)
+    def _text(self, wire: TextDeltaEvent) -> Iterator[StreamEvent]:
+        yield TextDelta(index=wire.output_index, delta=wire.delta)
+
+    @on(ReasoningDeltaEvent)
+    def _reasoning(self, wire: ReasoningDeltaEvent) -> Iterator[StreamEvent]:
+        yield ReasoningDelta(index=wire.output_index, delta=wire.delta)
+
+    @on(RefusalDeltaEvent)
+    def _refusal(self, wire: RefusalDeltaEvent) -> Iterator[StreamEvent]:
+        """A refusal arrives instead of the text, never beside it, so dropping it answers nothing."""
+        self.stop_reason = StopReason.refusal
+        yield Refusal(index=wire.output_index, text=wire.delta, raw=dict(wire.raw))
+
+    @on(AnnotationAdded)
+    def _annotation(self, wire: AnnotationAdded) -> Iterator[StreamEvent]:
+        """What the text just sent was attributed to."""
+        note = wire.annotation
+        yield Citation(
+            index=wire.output_index,
+            cited_text=note.text,
+            title=note.title,
+            url=note.url or note.source.url or None,
+            source_id=note.file_id or note.source.filename or None,
+            start=note.start_index,
+            end=note.end_index,
+            # This API counts characters. Google counts bytes, so the unit travels with them.
+            unit="char",
+            raw=dict(note.raw),
+        )
+
+    @on(Created)
+    def _created(self, wire: Created) -> Iterator[StreamEvent]:
+        """Which model actually served the turn, which need not be the one asked for."""
+        yield IterationStart(iteration=0, id=wire.response.id or None, model=wire.response.model or None)
+
+    @on(ContentPartDone)
+    def _content_part_done(self, wire: ContentPartDone) -> None:
+        """One content part inside an item is complete.
+
+        Not a BlockEnd: axio indexes a block by output item, and the item's own done event closes
+        it. Emitting both closed every block twice, so a consumer that finalises on BlockEnd
+        finalised a block it had already finished.
+        """
+
+    @on(ItemDone)
+    def _item_done(self, wire: ItemDone) -> Iterator[StreamEvent]:
+        """The finished item, which for reasoning is the only place its proof arrives.
+
+        Sent back on the next request, it lets the model see the reasoning it had already done.
+        Without it a turn that reasoned and then called a tool starts the next round blind.
+        """
+        if wire.item.type == "reasoning" and wire.item.encrypted_content:
+            yield ReasoningSignature(
+                index=wire.output_index,
+                signature=wire.item.encrypted_content,
+                id=wire.item.id,
+                provider=PROVIDER,
+            )
+        elif wire.item.type not in _INTERPRETED:
+            # The request says store=False, so this API keeps nothing: every item it produced is
+            # expected back on the next one. Watched as a ProviderEvent and never stored, the next
+            # request was missing the search the model had just answered from.
+            yield ProviderOutput(
+                index=wire.output_index,
+                provider=PROVIDER,
+                kind=wire.item.type,
+                data=dict(wire.item.raw),
+                id=wire.item.id,
+            )
+        yield BlockEnd(index=wire.output_index)
+
+    @on(ItemAdded)
+    def _item_added(self, wire: ItemAdded) -> Iterator[StreamEvent]:
+        item = wire.item
+        if item.type != "function_call":
+            logger.info("Output item added: type=%s", item.type)
+            return
+        if item.id:
+            self.call_ids[item.id] = item.call_id
+        logger.info("Tool call started: %s (call_id=%s, item_id=%s)", item.name, item.call_id, item.id)
+        yield ToolUseStart(index=wire.output_index, tool_use_id=item.call_id, name=item.name, provider=PROVIDER)
+
+    @on(ArgumentsDelta)
+    def _arguments(self, wire: ArgumentsDelta) -> Iterator[StreamEvent]:
+        call_id = self._call_id(wire.item_id)
+        logger.debug("Tool args delta: call_id=%s, +%d chars", call_id, len(wire.delta))
+        yield ToolInputDelta(index=wire.output_index, tool_use_id=call_id, partial_json=wire.delta)
+
+    # ── what only moves this turn's state ────────────────────────────────────────────────────
+
+    @on(Completed)
+    def _completed(self, wire: Completed) -> None:
+        response = wire.response
+        self._count(response.usage)
+        # Not `or "completed"`: a missing or wrongly typed status reads as the empty string here,
+        # and coercing it to success made an envelope that never said it finished into a whole
+        # answer. Unnamed, it falls to the raise below with the empty string as its name.
+        status = response.status
+        if self.stop_reason == StopReason.refusal:
+            # The status enum has no refusal member, so a declined response still completes.
+            pass
+        elif status not in STOP_REASONS:
+            # Not a finished answer, whatever else it is. Returned as IterationEnd(error) the
+            # caller is told only `Transport stopped with: error`, and the status is what they can
+            # act on.
+            raise StreamError(f"Responses completed with an unknown status: {status!r}")
+        else:
+            self.stop_reason = STOP_REASONS[status]
+            # A finished response still holding a call wants the tool run first. Only a
+            # finished one: rewritten, a cancelled or filtered turn passes the dispatch gate.
+            if self.stop_reason is StopReason.end_turn and any(
+                item.type == "function_call" for item in response.output
+            ):
+                self.stop_reason = StopReason.tool_use
+        logger.info(
+            "Response completed: status=%s, stop=%s, in=%d, out=%d",
+            status,
+            self.stop_reason,
+            self.usage.input_tokens,
+            self.usage.output_tokens,
+        )
+
+    @on(Incomplete)
+    def _incomplete(self, wire: Incomplete) -> None:
+        """A response the API cut short. Left unread it ends the turn as ``end_turn``, which tells
+        the agent a truncated answer is a whole one."""
+        self._count(wire.response.usage)
+        reason = wire.response.incomplete_details.reason
+        self.stop_reason = stop_reason_from(reason, STOP_REASONS, provider="Responses")
+        logger.warning("Response incomplete: reason=%s, stop=%s", reason or "unstated", self.stop_reason)
+
+    @on(ArgumentsDone)
+    def _arguments_done(self, wire: ArgumentsDone) -> None:
+        # Arguments carry whatever the user typed, and INFO is on in most deployments.
+        call_id = self._call_id(wire.item_id)
+        logger.info("Tool args complete: %s call_id=%s, %d chars", wire.name or "?", call_id, len(wire.arguments))
+        logger.debug("Tool args for call_id=%s: %.200s", call_id, wire.arguments)
+
+    # ── what ends the turn ───────────────────────────────────────────────────────────────────
+
+    @on(Failed)
+    def _failed(self, wire: Failed) -> None:
+        message = wire.response.error.message or "Unknown error"
+        logger.error("Response failed: %s", message)
+        raise StreamError(f"Responses API error: {message}")
+
+    @on(StreamFailure)
+    def _errored(self, wire: StreamFailure) -> None:
+        """Left unread the turn simply stopped and reported a normal finish."""
+        message = wire.message or "Unknown error"
+        logger.error("Stream error: %s (code=%s)", message, wire.code or "none")
+        raise StreamError(f"Responses API error: {message}")
+
+    # ── named, and deliberately not read ─────────────────────────────────────────────────────
+
+    @on(
+        "response.queued",
+        "response.in_progress",
+        "response.content_part.added",
+        "response.output_text.done",
+        "response.refusal.done",
+        "response.reasoning_summary_part.added",
+        "response.reasoning_summary_part.done",
+        "response.reasoning_summary_text.done",
+        "response.reasoning_text.done",
+    )
+    def _expected(self, payload: Payload) -> None:
+        """The envelope opening, and the whole of things already sent delta by delta.
+
+        Named rather than forwarded because reading them would send the same content twice, and
+        because this list is closed. It is the protocol's own bookkeeping, so it does not grow when
+        a tool is added.
+        """
+
+    # ── everything else, forwarded rather than dropped ───────────────────────────────────────
+
+    def unmatched(self, name: str, payload: Payload) -> Iterator[StreamEvent]:
+        """Anything this reader does not interpret, passed on under the provider's own name.
+
+        Almost all of it is the API running a tool on its own side. Each such tool has its own
+        event family. That set depends on which tools exist and which the caller declared, not on
+        the protocol. Named one by one, the list goes stale the day a tool is added. It also
+        reports a new tool as news about the protocol when it is news about the tools.
+
+        So nothing is listed and nothing is dropped. A consumer that wants the shell commands the
+        model ran, or the searches it made, matches on ``kind``. Any other consumer ignores it.
+        """
+        yield ProviderEvent(
+            provider=PROVIDER,
+            kind=name,
+            data=dict(payload),
+            index=payload.number("output_index", default=-1) if "output_index" in payload else None,
+        )
+
+    # ── the turn, once it is over ────────────────────────────────────────────────────────────
+
+    def _call_id(self, item_id: str) -> str:
+        """The call id for this item, or the item id while no mapping for it has arrived."""
+        return self.call_ids.get(item_id, item_id)
+
+    def _count(self, usage: ResponseUsage) -> None:
+        """The token counts, whose slices this API reports inside their totals. Nothing is added."""
+        self.usage = Usage.reported(
+            input_tokens=usage.input_tokens,
+            output_tokens=usage.output_tokens,
+            cache_read_tokens=usage.input_tokens_details.cached_tokens,
+            cache_write_tokens=usage.input_tokens_details.cache_write_tokens,
+            reasoning_tokens=usage.output_tokens_details.reasoning_tokens,
+        )
+
+    def finished(self) -> IterationEnd:
+        """What the turn added up to. The API sends no event that means this.
+
+        A stream that ended without one of its terminal events did not finish. The connection was
+        cut. Reported as ``end_turn``, a truncated answer is stored and returned as a whole one.
+        So it is raised, the way a transport reports any other broken stream.
+        """
+        if self.stop_reason is None:
+            raise StreamError("Responses stream ended without response.completed, response.incomplete or an error")
+        stop = self.stop_reason
+        logger.debug(
+            "Stream complete: stop_reason=%s, input_tokens=%d, output_tokens=%d",
+            stop,
+            self.usage.input_tokens,
+            self.usage.output_tokens,
+        )
+        if stop is StopReason.error:
+            raise StreamError("Responses stopped with an error the reader did not name")
+        return IterationEnd(iteration=0, stop_reason=stop, usage=self.usage)

axio_responses/request.py

@@ -0,0 +1,206 @@
+"""Building a Responses request: instructions, input items, and tool declarations."""
+
+from __future__ import annotations
+
+import base64
+import json
+import logging
+from typing import Any, Final
+
+from axio.blocks import (
+    AudioBlock,
+    ImageBlock,
+    ProviderBlock,
+    ReasoningBlock,
+    TextBlock,
+    ToolResultBlock,
+    ToolUseBlock,
+    VideoBlock,
+    proof,
+    replayable,
+)
+from axio.messages import Message
+from axio.schema import strip_title
+from axio.tool import Tool
+from axio.types import StopReason
+
+logger = logging.getLogger(__name__)
+
+#: What this protocol is called wherever its name is written: on the proofs it issues, on the
+#: items it expects back, and on the events it forwards. The Codex transport speaks this same
+#: protocol, so its turns say "openai" too rather than naming a fifth provider.
+PROVIDER: Final = "openai"
+
+STOP_REASONS: dict[str, StopReason] = {
+    "completed": StopReason.end_turn,
+    "end_turn": StopReason.end_turn,
+    "stop": StopReason.end_turn,
+    "max_output_tokens": StopReason.max_tokens,
+    "length": StopReason.max_tokens,
+    "cancelled": StopReason.cancelled,
+    "content_filter": StopReason.refusal,
+}
+
+
+def convert_tools(tools: list[Tool[Any]]) -> list[dict[str, Any]]:
+    """Convert axio Tool list to Responses API function tool dicts."""
+    return [
+        {
+            "type": "function",
+            "name": tool.name,
+            "description": tool.description,
+            "parameters": strip_title(tool.input_schema),
+        }
+        for tool in tools
+    ]
+
+
+def tool_output(content: str | list[TextBlock | ImageBlock | AudioBlock | VideoBlock]) -> str | list[dict[str, Any]]:
+    """A tool result as the output this API takes.
+
+    ``json.dumps`` on the blocks raises. They are slotted dataclasses, not JSON. A tool that
+    returned anything but a string crashed the request before it was sent.
+
+    The API takes a string, or a list of ``input_text``, ``input_image`` and ``input_file`` parts.
+    Text and images travel as themselves. Audio and video have no part of their own here. They
+    are named in text instead. The model is told what the tool produced, rather than handed a turn
+    with a gap in it.
+    """
+    if isinstance(content, str):
+        return content
+    parts: list[dict[str, Any]] = []
+    for block in content:
+        if isinstance(block, TextBlock):
+            parts.append({"type": "input_text", "text": block.text})
+        elif isinstance(block, ImageBlock):
+            encoded = base64.b64encode(block.data).decode("ascii")
+            parts.append({"type": "input_image", "image_url": f"data:{block.media_type};base64,{encoded}"})
+        elif isinstance(block, (AudioBlock, VideoBlock)):
+            parts.append({"type": "input_text", "text": f"[{block.media_type}, which this API takes no part for]"})
+    # An empty list would say the tool returned nothing at all.
+    return parts or ""
+
+
+def _flush_text(items: list[dict[str, Any]], parts: list[dict[str, Any]]) -> None:
+    """Emit the assistant text collected so far, keeping it in the order the turn stored it.
+
+    The text goes back as a plain string. An ``output_text`` part belongs to an output message,
+    which the API requires to carry ``id``, ``type`` and ``status`` as well; sent without them it
+    matches no input item the API defines.
+
+    Inserted at an index counted back from the tail instead, the text moved behind a call it
+    introduced whenever reasoning was stored after that call.
+    """
+    if parts:
+        items.append({"role": "assistant", "content": "".join(part["text"] for part in parts)})
+        parts.clear()
+
+
+def convert_messages(messages: list[Message], system: str) -> tuple[str, list[dict[str, Any]]]:
+    """Convert axio Message list to Responses API input array.
+
+    Returns (instructions, input_items).
+    """
+    items: list[dict[str, Any]] = []
+
+    for msg in messages:
+        if msg.role == "user":
+            # Every result in the turn, whatever else it carries beside them.
+            tool_results = [b for b in msg.content if isinstance(b, ToolResultBlock)]
+            if tool_results:
+                for tr in tool_results:
+                    items.append(
+                        {
+                            "type": "function_call_output",
+                            "call_id": tr.tool_use_id,
+                            "output": tool_output(tr.content),
+                        }
+                    )
+            rest = [b for b in msg.content if not isinstance(b, ToolResultBlock)]
+            if rest:
+                content_parts: list[dict[str, Any]] = []
+                for b in rest:
+                    if isinstance(b, TextBlock):
+                        content_parts.append({"type": "input_text", "text": b.text})
+                    elif isinstance(b, ImageBlock):
+                        encoded = base64.b64encode(b.data).decode("ascii")
+                        data_uri = f"data:{b.media_type};base64,{encoded}"
+                        content_parts.append({"type": "input_image", "image_url": data_uri})
+                if content_parts:
+                    items.append({"role": "user", "content": content_parts})
+
+        elif msg.role == "system":
+            # A system message inside the history, not the prompt carried in ``instructions``.
+            text = "".join(b.text for b in msg.content if isinstance(b, TextBlock))
+            if text:
+                items.append({"role": "system", "content": [{"type": "input_text", "text": text}]})
+
+        elif msg.role == "assistant":
+            content_parts_a: list[dict[str, Any]] = []
+            for b in msg.content:
+                if isinstance(b, ReasoningBlock):
+                    # `id` and `summary` are required beside the proof. The flush follows that test,
+                    # or a dropped block splits one run of text in two. `proof` leaves out what
+                    # another provider issued: sent here it is not encrypted content at all.
+                    if b.id and (encrypted := proof(b, PROVIDER)):
+                        _flush_text(items, content_parts_a)
+                        items.append(
+                            {
+                                "type": "reasoning",
+                                "id": b.id,
+                                "encrypted_content": encrypted,
+                                "summary": [],
+                            }
+                        )
+                    else:
+                        logger.debug("Dropping a reasoning block with no encrypted content to replay")
+                elif isinstance(b, ProviderBlock):
+                    # Back exactly as it arrived. This API keeps no copy of the turn, so an item
+                    # from a tool it ran itself is only in the request if we put it there.
+                    if replayable(b, PROVIDER):
+                        _flush_text(items, content_parts_a)
+                        items.append(dict(b.data))
+                elif isinstance(b, TextBlock):
+                    content_parts_a.append({"type": "output_text", "text": b.text})
+                elif isinstance(b, ToolUseBlock):
+                    _flush_text(items, content_parts_a)
+                    items.append(
+                        {
+                            "type": "function_call",
+                            "call_id": b.id,
+                            "name": b.name,
+                            "arguments": json.dumps(b.input),
+                            "status": "completed",
+                        }
+                    )
+            _flush_text(items, content_parts_a)
+
+    # A call the history has no result for. The API pairs the two by call_id, and the model reads
+    # them in order, so the stand-in goes where the result would have been.
+    answered = {i["call_id"] for i in items if i.get("type") == "function_call_output"}
+    placed: list[dict[str, Any]] = []
+    for item in items:
+        placed.append(item)
+        if item.get("type") != "function_call" or item.get("call_id") in answered:
+            continue
+        call_id = item.get("call_id", "")
+        # As we go: a call_id appearing twice took a stand-in each time.
+        answered.add(call_id)
+        logger.warning("Synthesizing placeholder output for orphan function_call: call_id=%s", call_id)
+        placed.append(
+            {
+                "type": "function_call_output",
+                "call_id": call_id,
+                "output": "[Tool was not executed - context was interrupted or compacted]",
+            }
+        )
+    items = placed
+
+    # Once, over the whole array. The API refuses a reasoning item with nothing after it, and only
+    # the last item has nothing after it. Trimmed per turn, reasoning that the next turn's own
+    # items follow was dropped from the middle of the conversation.
+    while items and items[-1].get("type") == "reasoning":
+        logger.debug("Dropping a trailing reasoning item, which has no following item")
+        items.pop()
+
+    return system, items

axio_responses-0.11.0.dist-info/METADATA

@@ -0,0 +1,106 @@
+Metadata-Version: 2.5
+Name: axio-responses
+Version: 0.11.0
+Summary: The OpenAI Responses API as axio speaks it: request items in, StreamEvents out
+Project-URL: Documentation, https://docs.axio-agent.com
+Project-URL: Homepage, https://github.com/mosquito/axio-agent
+Project-URL: Repository, https://github.com/mosquito/axio-agent
+License: MIT
+Keywords: agent,llm,openai,responses,streaming
+Requires-Python: >=3.12
+Requires-Dist: axio
+Requires-Dist: axio-sse
+Description-Content-Type: text/markdown
+
+# axio-responses
+
+[![PyPI](https://img.shields.io/pypi/v/axio-responses)](https://pypi.org/project/axio-responses/)
+[![Python](https://img.shields.io/pypi/pyversions/axio-responses)](https://pypi.org/project/axio-responses/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+The OpenAI Responses API as [axio](https://github.com/mosquito/axio-agent) speaks it: request items
+in, `StreamEvent`s out.
+
+Both halves live here rather than in a transport because two transports speak this API — the public
+`/v1/responses` endpoint and the ChatGPT backend Codex uses. It knows nothing about HTTP and opens
+no connection.
+
+## Installation
+
+```bash
+pip install axio-responses
+```
+
+## Usage
+
+### Building the request
+
+<!-- name: test_readme_building_a_request -->
+```python
+from axio.blocks import TextBlock
+from axio.messages import Message
+from axio_responses import convert_messages, convert_tools
+
+messages, system, tools = [Message(role="user", content=[TextBlock(text="hi")])], "be brief", []
+
+instructions, items = convert_messages(messages, system)
+payload = {
+    "model": "gpt-5.6",
+    "instructions": instructions,
+    "input": items,
+    "stream": True,
+    "tools": convert_tools(tools),
+}
+assert payload["instructions"] == "be brief"
+```
+
+`convert_messages` returns the system prompt separately, because this API takes it as
+`instructions` rather than as a message. Tool calls and their outputs become `function_call` and
+`function_call_output` items beside the messages, not blocks inside them.
+
+### Reading the stream
+
+`Responses` is an `axio_sse.Reader`: one `@on(...)` method per event, dispatching on the payload's
+own `type`. Its class body names only the events it interprets. The API publishes one event family
+per tool it can run, so that set grows with the tools and not with the protocol; everything else is
+forwarded through `unmatched()` rather than dropped.
+
+<!-- name: test_readme_reading_the_stream -->
+```python
+from collections.abc import AsyncIterator
+
+import aiohttp
+from axio.events import StreamEvent
+from axio_responses import Responses
+
+
+async def stream(resp: aiohttp.ClientResponse) -> AsyncIterator[StreamEvent]:
+    turn = Responses()
+    async for made in turn.over(resp.content.iter_any(), until="[DONE]"):
+        yield made
+    yield turn.finished()
+```
+
+Events axio has no type for — the API's own hosted tools, its audio, its bookkeeping — travel as
+`ProviderEvent` under the provider's own name rather than being dropped.
+
+### Holding it against the schema
+
+<!-- name: test_readme_names_are_published -->
+```python
+from axio_responses import Responses
+
+PUBLISHED_EVENTS = {"response.output_text.delta", "response.completed", "response.refusal.delta"}
+
+# Every name the reader claims is one the schema publishes. A typo is a handler that never runs.
+assert Responses.names() >= PUBLISHED_EVENTS
+```
+
+`names()` answers what the reader claims, so a test can hold it against the union OpenAI publishes.
+The check is `<=`, not `==`: the reader deliberately names fewer events than the API sends. Reading
+with `strict=True` raises `UnknownEvent` on a name it does not claim, which is how a test fails on
+the day OpenAI adds one.
+
+## License
+
+MIT

axio_responses-0.11.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+axio_responses/__init__.py,sha256=ZmgtSVdrdthL792dhFz8VsCXBXh5qlhdU3jT5X9KRF8,1491
+axio_responses/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+axio_responses/reader.py,sha256=md_7t4VLcQdW0GnWpLEu9BYfqRCK2zMuvMqa-sIv5CY,19087
+axio_responses/request.py,sha256=Mjxt1gL_XC0siOlPphwVRJXvJjUHX5PotQV6xUBmUdI,9038
+axio_responses-0.11.0.dist-info/METADATA,sha256=ABzRft35cLcd54rLuTNj0UkfgShje3sRtZGepRTvUp0,3713
+axio_responses-0.11.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+axio_responses-0.11.0.dist-info/RECORD,,

axio_responses-0.11.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any