pub struct RequestPlan { /* private fields */ }Expand description
Mutable preparation for exactly one model request.
use reef_core::runtime::model;
let plan = model::RequestPlan::new();
let request = plan.try_into_request(vec![]).unwrap();
plan.sampling_mut(); // freezing consumes the only mutable preparation valueImplementations§
Source§impl RequestPlan
impl RequestPlan
Sourcepub fn system_instruction(&self) -> &[Part]
pub fn system_instruction(&self) -> &[Part]
Returns the ordered system instruction.
Sourcepub fn push_system_instruction(&mut self, part: Part) -> &mut Self
pub fn push_system_instruction(&mut self, part: Part) -> &mut Self
Appends one system-instruction block.
Sourcepub fn extend_system_instruction(
&mut self,
parts: impl IntoIterator<Item = Part>,
) -> &mut Self
pub fn extend_system_instruction( &mut self, parts: impl IntoIterator<Item = Part>, ) -> &mut Self
Appends system-instruction blocks in iteration order.
Sourcepub fn clear_system_instruction(&mut self) -> &mut Self
pub fn clear_system_instruction(&mut self) -> &mut Self
Removes every system-instruction block.
Sourcepub fn tools(&self) -> &[ClientTool]
pub fn tools(&self) -> &[ClientTool]
Returns the client-local tool lane.
Sourcepub fn push_tool(&mut self, tool: ClientTool) -> &mut Self
pub fn push_tool(&mut self, tool: ClientTool) -> &mut Self
Appends one client-local tool descriptor.
Sourcepub fn extend_tools(
&mut self,
tools: impl IntoIterator<Item = ClientTool>,
) -> &mut Self
pub fn extend_tools( &mut self, tools: impl IntoIterator<Item = ClientTool>, ) -> &mut Self
Appends client-local tool descriptors in iteration order.
Sourcepub fn clear_tools(&mut self) -> &mut Self
pub fn clear_tools(&mut self) -> &mut Self
Removes every client-local tool descriptor.
Sourcepub const fn sampling_mut(&mut self) -> &mut SamplingParams
pub const fn sampling_mut(&mut self) -> &mut SamplingParams
Returns the sampling controls for mutation.
Sourcepub fn extensions(&self) -> &[Envelope]
pub fn extensions(&self) -> &[Envelope]
Returns the provider-hosted extension lane.
Sourcepub fn push_extension(&mut self, extension: Envelope) -> &mut Self
pub fn push_extension(&mut self, extension: Envelope) -> &mut Self
Appends one provider-hosted extension.
Sourcepub fn extend_extensions(
&mut self,
extensions: impl IntoIterator<Item = Envelope>,
) -> &mut Self
pub fn extend_extensions( &mut self, extensions: impl IntoIterator<Item = Envelope>, ) -> &mut Self
Appends provider-hosted extensions in iteration order.
Sourcepub fn clear_extensions(&mut self) -> &mut Self
pub fn clear_extensions(&mut self) -> &mut Self
Removes every provider-hosted extension.
Sourcepub fn push_ephemeral(&mut self, part: Part) -> &mut Self
pub fn push_ephemeral(&mut self, part: Part) -> &mut Self
Appends one volatile per-Step block.
Sourcepub fn extend_ephemeral(
&mut self,
parts: impl IntoIterator<Item = Part>,
) -> &mut Self
pub fn extend_ephemeral( &mut self, parts: impl IntoIterator<Item = Part>, ) -> &mut Self
Appends volatile per-Step blocks in iteration order.
Sourcepub fn clear_ephemeral(&mut self) -> &mut Self
pub fn clear_ephemeral(&mut self) -> &mut Self
Removes every volatile per-Step block.
Sourcepub fn try_into_request(
self,
messages: Vec<Item>,
) -> Result<Request, RequestError>
pub fn try_into_request( self, messages: Vec<Item>, ) -> Result<Request, RequestError>
Consumes the writable window and freezes a validated, model-visible request.
§This is the item-to-message projection
It is the crate’s only one, and there is no second message vocabulary to
project into: the projected value is the same closed Item history
minus everything the model must not see. Two rules apply, in this order.
ModelVisibility. EveryModelVisibility::Hiddenrecord is omitted, whatever its variant. A provider therefore never has to consultItemvisibility itself: by construction every item inRequest::messagesisModelVisibility::Visible.- The exchange grammar, checked over what survives rule 1. Hiding an assistant record hides the calls it carries, so a result that is still visible has become an orphan and is refused rather than sent; hiding a result whose call is visible leaves that call unanswered and is refused too. Reef’s own commits cannot produce either, because a committed result takes the visibility of the record carrying its call.
What this projection deliberately does not do is normalise segments
across providers. Deciding that one provider’s Segment::Thinking is
unusable by another requires knowing both providers’ rules, which core
does not and must not learn. A composition layer that changes model
mid-session performs that rewrite in a
ModelHooks::before_model
registration, returning
BeforeModelDecision::Modify
with a request re-frozen through this same boundary.
This is the only Request construction boundary: it validates system
instructions, applies visibility projection, closes tool-call/result
exchanges, owns both tool lanes, and rejects invalid input before
Client::generate can be invoked.
§Errors
Freezing refuses a request no provider should be asked to answer. Nothing
is validated lazily and no partial Request escapes, so a caller that
gets an error has changed nothing.
The system instruction is checked first, block by block, and each variant
carries the offending block’s index:
EmptySystemInstructionText
for a text block with no text,
NonTextSystemInstruction for a
block whose kind is known but is not text, and
UnknownSystemInstruction for
one whose numeric kind has no portable interpretation. A system
instruction of zero blocks is valid; a present block that says nothing is
not.
The rest is the exchange grammar, applied to what survives the visibility rule above. It fails when the history is not a closed sequence of call-and-answer:
ToolExchangeNotClosedif a user, system, or assistant record appears while an earlier call is still unanswered.EmptyToolCallId,EmptyToolCallName, orDuplicateToolCallIdfor a call that cannot be correlated: identities are unique across the whole request, not merely within one assistant record.EmptyToolResultId,EmptyToolResultName,OrphanToolResult, orToolResultNameMismatchfor a result that answers no pending call or answers it under another tool’s name.UnresolvedToolCalls, with a count, if the history ends with calls nobody answered.
The last two are also how a half-hidden exchange is refused, and the reason is the projection above rather than provider etiquette: hiding an assistant record hides the calls it carries, so a still-visible result has become an orphan, and hiding only the result leaves its call unanswered. Reef’s own commits cannot produce either, because a committed result takes the visibility of the record carrying its call — so seeing one of these from a rewritten history means the rewrite split an exchange in half.