Struct ModelHandle 

pub struct ModelHandle { /* private fields */ }

A cloneable, opaque handle to live completion-model behavior.

The handle is the boundary between typed provider authoring and Rig’s concrete high-level agent facade. It is intentionally not serializable: captured clients, credentials, and transports are live process state. Applications that need persistent model selection should serialize a separate identifier and resolve it to a handle at runtime.

Cloning is cheap and shares the retained model through an Arc. Replacing a handle on one cloned agent has value semantics and does not mutate other agent clones; each in-flight attempt owns its own handle clone, so in-flight work never rebinds. The erased model is retained in a shared Arc, so each completion/stream attempt runs against the same instance: no per-call clone of the model itself, and interior-mutable model state (counters, rotating endpoints, local caches) persists across attempts.

The absence of serde implementations is intentional:

use rig_agent::ModelHandle;

fn requires_serialize<T: serde::Serialize>() {}
requires_serialize::<ModelHandle>();

use rig_agent::ModelHandle;

fn requires_deserialize<T: for<'de> serde::Deserialize<'de>>() {}
requires_deserialize::<ModelHandle>();

Implementations

impl ModelHandle

pub fn new<M>(model: M) -> Self

where M: CompletionModel + 'static,

Erase a typed completion model into a runtime model handle.

pub fn named<M>(label: impl Into<String>, model: M) -> Self

where M: CompletionModel + 'static,

Erase a typed completion model and attach a diagnostic label.

Labels are for logs and routing diagnostics only. They are not stable provider identities and are not serialized.

pub fn label(&self) -> Option<&str>

Returns the optional diagnostic label attached to this handle.

Trait Implementations

impl Clone for ModelHandle

fn clone(&self) -> ModelHandle

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl CompletionModel for ModelHandle

A handle behaves exactly like the model it erased, with capabilities served from the snapshot captured at erasure time.

It deliberately adds no request validation of its own. Both agent surfaces reach a model through CompletionRequestBuilder — runner.rs’s blocking turn calls builder.send(), the streaming turn calls builder.stream() — and the builder already runs CompletionRequest::validate_message_content. Repeating it here would scan the whole history a second time on every model call and buy nothing.

fn completion( &self, request: CompletionRequest, ) -> impl Future<Output = Result<CompletionResponse, CompletionError>> + WasmCompatSend

Generates a completion response for the given completion request.

fn stream( &self, request: CompletionRequest, ) -> impl Future<Output = Result<StreamingCompletionResponse, CompletionError>> + WasmCompatSend

Streams a completion response for the given completion request.

fn capabilities(&self) -> ProviderCapabilities

Provider behavior a runtime should account for when preparing requests.

fn completion_request( &self, prompt: impl Into<Message>, ) -> CompletionRequestBuilder<Self>

where Self: Sized + Clone,

Generates a completion request builder for the given prompt.

impl Debug for ModelHandle

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

Formats the value using the given formatter.