Struct CompletionResponse 

pub struct CompletionResponse {
    pub choice: Vec<AssistantContent>,
    pub usage: Usage,
    pub message_id: Option<String>,
    pub response_id: Option<String>,
    pub provider_request_id: Option<String>,
    pub provider: String,
    pub model: Option<String>,
    pub raw: Value,
    /* private fields */
}

General completion response struct: the completion choice plus normalized response metadata. The completion choice contains one or more assistant content items.

This type is concrete — it carries no provider-typed payload. Callers who hold a concrete model and need a provider’s own wire response typed call that model’s inherent raw_completion method, which performs the same request and returns the provider’s native type. Callers who do not hold the concrete model — an agent erases it at construction — read the same value, serialized, from CompletionResponse::raw, which every provider seam populates.

Fields

choice: Vec<AssistantContent>

The completion choice (represented by one or more assistant message content) returned by the completion model provider

usage: Usage

Tokens used during prompting and responding

message_id: Option<String>

The identifier the provider assigned to the assistant message itself, when it issued one — an OpenAI Responses output-message msg_ ID or an Anthropic msg_ ID. Only IDs the provider would recognize on a replayed assistant message belong here; identifiers that name the whole response (an OpenAI chat chatcmpl- ID, a Gemini responseId) go in CompletionResponse::response_id instead.

The Responses API path uses it to pair reasoning input items with their output items across turns, and it is what agent history promotes into Message::Assistant’s id.

response_id: Option<String>

The identifier the provider assigned to the response as a whole, when it reported one — an OpenAI chat chatcmpl- ID, a Gemini responseId, a Cohere generation ID. Response-scoped: useful for logging, telemetry (gen_ai.response.id), and support requests, but never replayed to a provider as a message ID.

provider_request_id: Option<String>

The provider’s transport-level request identifier, taken from the HTTP response headers (Anthropic request-id, OpenAI/xAI x-request-id) or the provider SDK’s response metadata (Bedrock) — the id provider support asks for when investigating a request. Never the body’s message.id/response id; those are Self::message_id and Self::response_id. None means the provider did not report one — that is a documented outcome (e.g. Gemini sends no id header), never an error.

provider: String

Stable descriptor name of the provider that produced this response, for example "openai". Always populated, including for responses derived from a stream that ended before its terminal record.

model: Option<String>

Provider-reported model identifier for the response.

This is the model named by the wire response, not the model that was requested; it is None when the provider reports no identifier.

raw: Value

The provider’s own response for this call: the value the model’s inherent raw_completion would have returned, serialized. It is the response as rig’s wire type parsed it — fields that type does not model are not here. Every provider seam populates it, unconditionally — the same parity the pre-normalization raw_response: T had.

An escape hatch for provider-specific data rig does not normalize — it never replaces a normalized field, and every normalized field means the same thing whatever this holds. Value::Null means the value was built without a provider behind it — CompletionResponse::new without with_raw (test doubles, hand-built responses), or a response persisted before the field existed — never that the provider sent nothing: no provider seam produces Null.

Typed access is recoverable: provider raw types are Deserialize, so provider::CompletionResponse::deserialize(&raw) returns the provider’s own type, and NormalizeCompletionResponse converts forward.

Implementations

impl CompletionResponse

pub fn new( choice: Vec<AssistantContent>, usage: Usage, provider: impl Into<String>, ) -> Self

Create a response from its required parts; optional metadata starts unset and is filled in with the with_* helpers.

pub fn finish_reason(&self) -> Option<FinishReason>

Why the model stopped generating, when the provider reported it.

pub fn identity(&self) -> ResponseIdentity

This response’s identity metadata as one ResponseIdentity carrier.

pub fn with_finish_reason(self, finish_reason: FinishReason) -> Self

Attach the normalized finish reason, reconciled against the choice via FinishReason::reconcile_with_output.

pub fn with_optional_finish_reason( self, finish_reason: Option<FinishReason>, ) -> Self

Attach the normalized finish reason when the provider reported one.

This is the Option form of CompletionResponse::with_finish_reason and applies the same reconciliation. Provider conversions that hold an Option<FinishReason> use this rather than assigning the field, so the tool-call upgrade is never skipped.

impl CompletionResponse

pub fn with_message_id(self, message_id: impl Into<String>) -> Self

Attach the provider-assigned message ID.

An empty string is treated as absent: gateways that echo "" for fields they don’t populate must not produce a Some("") that differs between the buffered and streaming paths. All identifier and model setters share this rule so the invariant lives here rather than at every provider call site.

pub fn with_optional_message_id( self, message_id: Option<impl Into<String>>, ) -> Self

Attach the provider-assigned message ID when the provider reported one.

pub fn with_response_id(self, response_id: impl Into<String>) -> Self

Attach the provider-assigned response-scoped ID.

pub fn with_optional_response_id( self, response_id: Option<impl Into<String>>, ) -> Self

Attach the provider-assigned response-scoped ID when the provider reported one.

pub fn with_provider_request_id(self, request_id: impl Into<String>) -> Self

Attach the provider’s transport-level request identifier.

pub fn with_optional_provider_request_id( self, request_id: Option<impl Into<String>>, ) -> Self

Attach the provider’s transport-level request identifier when the provider reported one.

pub fn with_model(self, model: impl Into<String>) -> Self

Attach the provider-reported model identifier.

An empty string is treated as absent, matching the identifier setters.

pub fn with_optional_model(self, model: Option<impl Into<String>>) -> Self

Attach the provider-reported model identifier when the response carried one.

pub fn with_raw(self, raw: impl Into<Value>) -> Self

Attach the provider’s own response, serialized — the value the model’s inherent raw method would have returned. Every provider seam calls this; see the raw field for the exact meaning of the payload (and of Value::Null).

Trait Implementations

impl Clone for CompletionResponse

fn clone(&self) -> CompletionResponse

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CompletionResponse

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for CompletionResponse

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<StreamingCompletionResponse> for CompletionResponse

fn from(value: StreamingCompletionResponse) -> CompletionResponse

Converts to this type from the input type.

impl Serialize for CompletionResponse

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl TryFrom<CompletionResponse> for CompletionResponse

type Error = CompletionError

The type returned in the event of a conversion error.

fn try_from(response: CompletionResponse) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<CompletionResponse> for CompletionResponse

type Error = CompletionError

The type returned in the event of a conversion error.

fn try_from(resp: CompletionResponse) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<GenerateContentResponse> for CompletionResponse

Normalize a Gemini generateContent response.

type Error = CompletionError

The type returned in the event of a conversion error.

fn try_from(response: GenerateContentResponse) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Interaction> for CompletionResponse

Normalize a Gemini Interactions API payload.

type Error = CompletionError

The type returned in the event of a conversion error.

fn try_from(response: Interaction) -> Result<Self, Self::Error>

Performs the conversion.