Struct Out 

pub struct Out<'id, Op: Operation> { /* private fields */ }

Where a decoder writes one reply. The 'id brand ties it to that one reply: a writer cannot be kept past the decode step that received it.

use rig_core::operation::Completion;
use rig_core::wire::Out;

// A writer cannot be stashed to write into the reply later.
struct Stash(Option<Out<'static, Completion>>);

fn keep<'id>(stash: &mut Stash, out: Out<'id, Completion>) {
    stash.0 = Some(out);
}

Implementations

impl<'id> Out<'id, Completion>

pub fn open( &mut self, index: usize, block: Block, item: Value, ) -> Result<(), ProviderError>

Open the provider item at wire index as block: it takes the next position in the reply. item is the item as its first event states it, the base its deltas merge into; Null when the block keeps no provider item. An index already open is an error.

pub fn push( &mut self, index: usize, fragment: &str, ) -> Result<(), ProviderError>

Append a fragment to the open item at index: text, reasoning, or a call’s argument JSON, by the item’s block.

pub fn edit( &mut self, index: usize, edit: impl FnOnce(&mut Value), ) -> Result<(), ProviderError>

Edit the item at index in place: apply a delta with merge, or replace the whole item a provider restates when it finishes. Until the reply ends, an index whose block already closed edits that block’s item: the terminal backfill of a field the provider states only at its end.

pub fn close(&mut self, index: usize) -> Result<(), ProviderError>

Close the item at index the provider never stated complete: its block becomes visible with no native, and an opaque item is kept but does not replay. Empty text and reasoning are dropped, and so is a call with no name. A call’s arguments are read by ToolFunction::parse, so malformed ones never fail the reply; a call that never got an id, or reuses one an earlier call took, gets one rig issues.

pub fn finish(&mut self, index: usize) -> Result<(), ProviderError>

Close the item at index the provider stated complete: Self::close, with the item as assembled becoming the block’s native.

pub fn finish_open(&mut self) -> Result<(), ProviderError>

End every item still open as stated complete, for a wire whose end of reply is the provider’s statement that its items are done.

pub fn whole( &mut self, index: usize, block: Block, item: Value, text: &str, ) -> Result<(), ProviderError>

Open and finish the item at index in one step: a whole block a provider states in one piece, item its provider item and text its text, reasoning, argument JSON or base64 image data.

pub fn order_by_index(&mut self)

Order the response’s blocks by wire index rather than by when they opened, for a wire whose indices are the provider’s item order and whose end may state items it never streamed. Call it before the first item opens; blocks with no wire index go last.

pub fn lead(&mut self, index: usize) -> Result<(), ProviderError>

Hold the open item at index first in the response whenever it opened, for a wire that states one block of the turn apart from its order. Its events keep their arrival order. A turn leads with the first item named.

pub fn restate(&mut self, index: usize, text: &str) -> Result<(), ProviderError>

Replace the text, reasoning or argument JSON of the open item at index with text, the whole of it as the provider restates it at its end. The fragments already streamed stand and nothing more streams for them; the block ends holding text.

pub fn fragment( &mut self, index: Option<usize>, fragment: CallFragment<'_>, ) -> Result<(), ProviderError>

Write one fragment of a tool call the provider streams, opening the call at its first fragment. Its id and name may arrive in any fragment, and the first name it is given stays: the call starts streaming once it names a tool, carrying the argument text held until then, and its end states its id. Calls are told apart by index when the wire gives one. A new id under an index starts a new call once the held call’s arguments are a complete object or when it names a tool: some providers send a fresh id, and no name, with every chunk of one call. Without an index (None, or the wire’s null), a fragment with an unseen id opens a call, and one with no id continues the latest call while its arguments are incomplete.

pub fn announce( &mut self, index: usize, announced: Value, ) -> Result<(), ProviderError>

Arguments the provider announced for the call at index, used only if no fragment arrives.

pub fn fresh_index(&mut self) -> usize

An index no provider item uses, for a wire that indexes nothing.

pub fn run( &mut self, block: Block, fragment: &str, ) -> Result<usize, ProviderError>

A fragment on a wire that marks no item boundaries: it continues the block the last fragment went to while block is the same kind, and otherwise closes that block and opens a new one. Returns the block’s index, for merging its provider item.

pub fn end_run(&mut self) -> Result<(), ProviderError>

Close the block Self::run is extending, if any: output of another kind interleaved it.

pub fn cite(&mut self, index: usize, citation: WireCitation)

Add citation to the text item at wire index, open or ended. Its span is resolved to bytes of the text when the item closes, or at once for an item already closed. A span that does not resolve, or covers other text than its quoted, drops the citation with a warning, as do citations of an item that is not text: a citation never fails a reply.

pub fn set_citations(&mut self, index: usize, citations: Vec<WireCitation>)

Put citations in place of the text item’s own, for a provider that restates them; Self::cite otherwise.

impl<'id, Op: Operation> Out<'id, Op>

pub fn end(self, end: Op::End) -> Flow

End the reply with what the provider sent at its end. It consumes the writer: nothing is written after the end.

pub fn unknown(&mut self, payload: UnknownPayload)

A payload the provider sent that this decoder does not model. It reaches the consumer as Item::Unknown.

impl<Op: Operation<Emit = Free>> Out<'_, Op>

pub fn raw(&mut self, raw: Value)

Record the reply’s provider document, the response’s raw. A whole JSON body the transport reported outranks it: a decoder whose reply is not one JSON document records it here.

Only an operation whose decoders build their own events has this. A completion’s raw is what its wire’s Reassembler rebuilds, never what a decoder writes:

use rig_core::operation::Completion;
use rig_core::wire::Out;

fn record(out: &mut Out<'_, Completion>) {
    out.raw(serde_json::json!({ "response_id": "x" }));
}

pub fn event(&mut self, event: Op::Event)

One event of the reply.

Only an operation whose decoders build their own events has this; a completion’s events come from its part handles:

use rig_core::operation::Completion;
use rig_core::streaming::StreamEvent;
use rig_core::wire::Out;

fn reinject(out: &mut Out<'_, Completion>, seen: &StreamEvent) {
    out.event(seen.clone());
}

An event rebuilt from its serialized form is no different:

use rig_core::operation::Completion;
use rig_core::streaming::Transcript;
use rig_core::wire::Out;

fn rebuild(out: &mut Out<'_, Completion>, recorded: serde_json::Value) {
    let Ok(transcript) = Transcript::parse(recorded) else { return };
    for event in transcript.events() {
        out.event(event.clone());
    }
}