Struct Out 

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

Where a decoder writes one reply. The 'id brand ties it, and every part handle it hands out, to that one reply: a handle cannot be used with another reply’s writer or kept past its own.

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

// A text part opened on one reply cannot grow on another.
fn cross<'a, 'b>(a: &mut Out<'a, Completion>, b: &mut Out<'b, Completion>) {
    let part = a.text();
    b.push_text(&part, "x");
}

use rig_core::operation::{Completion, TextPart};
use rig_core::wire::Out;

// A handle cannot outlive its reply to be used on a later one.
struct Stash(Option<TextPart<'static>>);

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

Implementations

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

pub fn text(&mut self) -> TextPart<'id>

Open a text part. Nothing is emitted until its first fragment.

pub fn push_text(&mut self, part: &TextPart<'id>, text: &str)

Append to an open text part.

pub fn text_params( &mut self, part: &TextPart<'id>, additional_params: AdditionalParams, )

Merge provider metadata into an open text part. Metadata is content: the part starts here if no text started it.

pub fn close_text(&mut self, part: TextPart<'id>)

Close a text part. One with neither text nor metadata is dropped.

pub fn reasoning(&mut self) -> ReasoningPart<'id>

Open a reasoning part. Nothing is emitted until its first fragment.

pub fn push_reasoning(&mut self, part: &ReasoningPart<'id>, text: &str)

Append to an open reasoning part.

pub fn close_reasoning(&mut self, part: ReasoningPart<'id>, seal: Seal)

Close a reasoning part, sealed to the reply’s issuer. One with nothing to replay is dropped.

pub fn reasoning_block(&mut self, reasoning: Reasoning)

A whole reasoning part the provider sent in one piece.

pub fn call( &mut self, id: CallId, name: ToolName, ) -> Result<CallPart<'id>, ProviderError>

Open a tool call with its id and name. A provider id already used by another call of this reply is ProviderError::DuplicateCallId.

Both are required, so no call opens without an id:

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

fn idless(out: &mut Out<'_, Completion>, name: ToolName) {
    let _ = out.call(None, name);
}

or without a name:

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

fn nameless(out: &mut Out<'_, Completion>, id: CallId) {
    let _ = out.call(id, "");
}

pub fn push_arguments(&mut self, part: &CallPart<'id>, json: &str)

Append a fragment of an open call’s argument JSON.

pub fn decorate_call( &mut self, part: &CallPart<'id>, signature: Option<String>, additional_params: Option<Value>, )

Attach a provider signature and metadata to an open call.

pub fn close_call(&mut self, part: CallPart<'id>) -> Result<(), ProviderError>

Close a call: it becomes visible. Arguments that do not parse are ProviderError::MalformedToolInput.

pub fn abandon_call(&mut self, part: CallPart<'id>)

Drop an open call: it never becomes visible.

pub fn tool_call(&mut self, call: ToolCall) -> Result<(), ProviderError>

A whole tool call the provider sent in one piece.

pub fn image(&mut self, image: Image)

An image part.

pub fn content( &mut self, content: AssistantContent, ) -> Result<(), ProviderError>

A whole part of an already assembled response.

pub fn message_id(&mut self, id: impl Into<String>)

Record the assistant message id. It outranks the one the end names.

pub fn issued_by(&mut self, issuer: impl Into<Issuer>)

Name the issuer of this reply’s reasoning: a gateway relaying another provider’s models.

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

Buffer one fragment of the tool call the provider streams under index. The call opens when its id and name are both known; a provider id another call already has is ProviderError::DuplicateCallId.

pub fn announce_pending(&mut self, index: usize, arguments: Value)

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

pub fn decorate_pending( &mut self, provider_id: &str, signature: Option<String>, additional_params: Option<Value>, )

Attach a signature and metadata to the buffered call the provider names provider_id. What it already has wins.

pub fn decorate_pending_at( &mut self, index: usize, signature: Option<String>, additional_params: Option<Value>, )

Attach a signature and metadata to the buffered call at index.

pub fn pending_calls(&self) -> Vec<usize>

The wire indices of the buffered calls, in order.

pub fn pending_id(&self, index: usize) -> Option<String>

The provider id of the buffered call at index, when it has one.

pub fn pending_name(&self, index: usize) -> String

The tool name the buffered call at index has so far.

pub fn pending_has_arguments(&self, index: usize) -> bool

Whether the buffered call at index received argument bytes that are not blank, or announced arguments.

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

Close the buffered call at index: it becomes visible, under the provider’s id or, for a wire that sent none, one rig issues. A call with no name is dropped; if_malformed decides for one whose arguments do not parse.

pub fn drop_pending(&mut self, index: usize)

Drop the buffered call at index: it never becomes visible.

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 raw(&mut self, raw: Value)

Record the reply’s provider document, the response’s raw, for any operation. A whole JSON body the transport reported outranks it, and a raw the decoder writes onto its response is replaced: a decoder whose reply is not one JSON document records it here.

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 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());
    }
}