Struct Conversation 

pub struct Conversation(pub Conversation);

The agent’s conversation: rig-core’s Conversation, which it derefs to, so a plugin reads and changes it with that type’s methods. Requests send it as it is.

Each change waits in the conversation’s outbox until the kernel saves it and announces it as a ConversationChanged. A value inserted in place of the agent’s own is saved as one reset, after the changes the old one had not saved. Saved through serde.

use rig_ecs::prelude::*;

// `/undo`: the user's last message and everything after it go.
fn undo(mut agents: Query<&mut Conversation, With<Agent>>) {
    for mut conversation in &mut agents {
        let last = conversation.entries().rev().find(|entry| entry.is_users_own());
        if let Some(last) = last.map(|entry| entry.index) {
            conversation.splice(last.., [], Author::plugin("undo"));
        }
    }
}

Tuple Fields

0: Conversation

Methods from Deref<Target = Conversation>

pub fn turns(&self) -> impl DoubleEndedIterator

The turn records, oldest first, with their asides’ ids; the newest is turns().next_back(), found from the end.

pub fn open_turn(&mut self) -> TurnRecord

Records a turn that begins now, numbered after the last record and starting at turn_start. Returns the new record.

pub fn end_turn(&mut self, end: TurnEnd) -> bool

Ends the last turn record, when it is open, with end. Returns whether it was open.

pub fn messages(&self) -> &[Arc<Message>]

The messages, oldest first: what a request sends.

pub fn entries(&self) -> impl DoubleEndedIterator + ExactSizeIterator

The entries, oldest first.

pub fn entry(&self, at: usize) -> Option<Entry>

Entry at, with its author, id and when it was made, to splice back changed.

pub fn id(&self, at: usize) -> Option<MessageId>

The id of entry at.

pub fn key(&self, at: usize) -> Option<MessageKey>

The identity of entry at beyond this conversation.

pub fn index_of_key(&self, key: MessageKey) -> Option<usize>

Where the entry with identity key is now; None when it is not here, also when an entry with its id was made at another time.

pub fn author(&self, at: usize) -> Option<&Author>

Who wrote entry at; None for the user’s own text, the model’s reply, a tool result, or no such entry.

pub fn index_of(&self, id: MessageId) -> Option<usize>

Where entry id is now; None once an edit took it out.

pub fn start_of(&self, id: MessageId) -> usize

Where a span that began at entry id begins now, such as a turn: its index while it is there; the end for an entry not made yet; 0 for one an edit took out, as a summary then stands for what came before it.

pub fn turn_start(&self) -> MessageId

Where a turn starting now begins: the first of the user messages at the end, which it answers, else the first entry it adds.

pub fn asked(&self, start: MessageId) -> impl Iterator<Item = EntryRef<'_>>

The entries a turn that began at start (its turn_start) answers: the user messages in a row from where it begins now (start_of). After a stopped turn they begin with that turn’s tool results and the STOPPED note, before what was sent next.

pub fn request(&self, start: MessageId) -> Option<EntryRef<'_>>

The message that asked for the turn that began at start: the first of the entries it answers (asked) that is a request (EntryRef::is_request).

pub fn halted(&self) -> Option<Halt>

Why the user’s last message is left unanswered, if it was halted. Cleared when an entry is pushed or a splice reaches the end.

pub fn awaits_model(&self) -> bool

Whether the model owes an answer: the last message a model reads is the user’s, and it was not halted. A failed or stopped reply after it is never read (StopReason::is_failure), so the answer is still owed.

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

The tool calls of the last assistant message that nothing answers yet. See pairing::pending_calls.

pub fn validate(&self) -> Result<(), PairingError>

Whether the messages pair every tool call with its result. See pairing::validate.

pub fn asides(&self) -> impl DoubleEndedIterator

The asides, in the order put.

pub fn aside(&self, id: AsideId) -> Option<&Aside>

Aside id.

pub fn aside_position(&self, aside: &Aside) -> usize

Where aside is drawn: before entry position, after entry position - 1. While an edit took out the entry it follows, after the entry that stands for it now (start_of).

pub fn push(&mut self, entry: impl Into<Entry>) -> MessageId

Pushes entry, after a STOPPED entry by Author::rig in the same change when the user stopped the last request; a halt is cleared. Returns the new entry’s id; a pushed entry never reuses one.

pub fn extend( &mut self, messages: impl IntoIterator<Item = impl Into<Arc<Message>>>, )

Pushes each of messages as its own entry without an author, in one change, as push does.

pub fn splice( &mut self, range: impl RangeBounds<usize>, with: impl IntoIterator<Item = Entry>, by: Author, ) -> Spliced

Replaces entries in range, clamped to the conversation, with with, recorded as made by by. An entry of with keeps its id when that id was in the range and no earlier entry of with kept it; any other gets a new id. Nothing merges. A splice reaching the end clears the halt. An empty range replaced by nothing changes and records nothing.

pub fn restore( &mut self, range: impl RangeBounds<usize>, with: impl IntoIterator<Item = Entry>, by: Author, ) -> Spliced

As splice, and an entry of with whose id this conversation made (below the next id), that no entry outside the range holds and no earlier entry of with took, keeps that id and when it was made (Entry::made, else now): entries put back as they were, such as a summary’s originals or an edit undone. Asides that followed such an entry follow it again. Only for entries this conversation held: an entry from elsewhere that carries an id would take one that meant another message here.

use rig_core::completion::Message;
use rig_core::conversation::{Author, Conversation, Entry};

let mut conversation = Conversation::from_messages([
    Message::user("one"),
    Message::assistant("two"),
]);
let ids: Vec<_> = conversation.entries().map(|entry| entry.id).collect();
let originals: Vec<Entry> = (0..2).filter_map(|at| conversation.entry(at)).collect();
let summary = Entry::new(Message::user("a summary"));
conversation.splice(.., [summary], Author::plugin("compact"));
let undone = conversation.restore(.., originals, Author::plugin("undo"));
assert_eq!(undone.restored, ids);
assert!(conversation.entries().map(|entry| entry.id).eq(ids));

pub fn set_entries(&mut self, entries: Vec<Entry>, by: Author) -> Spliced

Makes the conversation hold entries, as made by by: one restore of the range between the longest start and end it shares with them (the same messages, ids and authors), so entries taken from it keep their ids. Nothing when they are equal.

pub fn edit_each( &mut self, by: Author, edit: impl FnMut(EntryRef<'_>) -> Option<Message>, ) -> Vec<MessageId>

Rewrites entries in place, as made by by: edit sees each entry, oldest first, and returns the message to put in its place, or None to leave it. The entries it rewrote keep their ids and authors, and the whole edit is one change: a splice of the entries from the first rewritten to the last. Nothing is recorded when it rewrote none. Returns the ids of the entries it rewrote.

use rig_core::completion::Message;
use rig_core::conversation::{Author, Conversation};

let mut conversation = Conversation::from_messages([
    Message::user("one"),
    Message::user("two"),
]);
let before = conversation.id(1);
let changed = conversation.edit_each(Author::plugin("shout"), |entry| {
    (entry.index == 1).then(|| Message::user("TWO"))
});
assert_eq!(changed, before.into_iter().collect::<Vec<_>>());
assert_eq!(conversation.messages().get(1).map(|message| &**message), Some(&Message::user("TWO")));
assert_eq!(conversation.id(1), before);

pub fn normalize(&mut self, by: Author) -> Normalized

Repairs the entries as pairing::normalize does, saved with set_entries as made by by, so merged entries keep the first’s id, author and made-time. An aside that followed an entry merged into another follows that one; one that followed a dropped entry follows the entry before it (each move recorded, by by). Returns what it repaired.

pub fn reread(&mut self, from_log: Conversation) -> Result<(), ApplyError>

Takes everything a log holds from from_log, a value read from that log: entries, saved asides, halt, next ids, lineage and revision. This value’s unsaved asides stay, with their ids. For a host whose log was rewritten under the value it holds.

Errors

ApplyError::Mismatch, changing nothing, while either value has unsaved changes, or when an unsaved aside’s id is a saved one’s in from_log.

pub fn halt(&mut self, halt: Halt) -> bool

Leaves the user’s last message unanswered, for halt. Whether it was halted now: not when the model owes no answer.

pub fn resume(&mut self) -> bool

Asks the model again for an answer to the user’s last message, also a halted one; whether the last message is the user’s.

pub fn add_aside(&mut self, aside: Aside) -> AsideId

Puts aside after the asides already put and returns its id. An unsaved aside is not recorded.

pub fn replace_aside(&mut self, id: AsideId, aside: Aside) -> bool

Replaces aside id with aside, in its place; whether there was one. Replacing a saved aside with an unsaved one records its removal.

pub fn remove_aside(&mut self, id: AsideId) -> Option<Aside>

Removes aside id and returns it, or None if there was none.

pub fn apply(&mut self, change: &ChangeRecord) -> Result<(), ApplyError>

Applies a recorded change verbatim, such as one read from a log or sent by a process that mirrors this conversation. It is not put in the outbox. Fails, changing nothing, when it does not fit.

pub fn dated<R>( &mut self, at: u64, edit: impl FnOnce(&mut Conversation) -> R, ) -> R

Makes the edits of edit as made at at, in milliseconds since the Unix epoch, such as messages imported at the times their source logged them: their records carry that time, which a writer keeps, and the entries they make were made then. An edit dated inside, by a nested call, keeps its own time.

use rig_core::conversation::Conversation;
use rig_core::message::Message;

let mut conversation = Conversation::new();
conversation.dated(1_790_848_800_000, |conversation| {
    conversation.push(Message::user("Imported"))
});
let at = conversation.unsaved().first().and_then(|recorded| recorded.at);
assert_eq!(at, Some(1_790_848_800_000));

pub fn unsaved(&self) -> &[ChangeRecord]

The changes made that nobody has saved yet, oldest first.

pub fn take_unsaved(&mut self) -> Vec<ChangeRecord>

Takes the changes made that nobody has saved yet, to save them.

pub fn revision(&self) -> u64

The changes behind this value, one per record: those of the log it continues (lineage) when it was last loaded or saved, then each applied or made since. An unsaved aside counts none.

pub fn lineage(&self) -> Lineage

The saved log this value continues: Lineage::EMPTY when it was begun here from nothing and never saved, Lineage::DETACHED when it was read back from its serde form.

pub fn continues(&self, lineage: Lineage, changes: u64) -> bool

Whether this value’s unsaved changes, appended to the log of lineage that holds changes changes, give this value: it continues that log, holding all of its changes and since then only its unsaved ones. A value begun here from nothing continues any empty log.

pub fn continue_log(&mut self, lineage: Lineage, changes: u64)

Marks this value as holding the changes changes of the log of lineage, then its unsaved ones: what a store does once it loaded the value from that log or saved it there.

pub fn view(&self) -> Conversation

A copy with an empty outbox, for edits never saved (a preview, a reset’s state).

pub fn request_view(&self) -> Conversation

A view without the asides, for a model request’s copy: a request never sends them, and one is built per model call.

Trait Implementations

impl Clone for Conversation

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Component for Conversation

where Self: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

A constant indicating the storage type used for this component.

type Mutability = Mutable

A marker type to assist Bevy with determining if this component is mutable, or immutable. Mutable components will have Component<Mutability = Mutable>, while immutable components will instead have Component<Mutability = Immutable>.

fn register_required_components( _requiree: ComponentId, required_components: &mut RequiredComponentsRegistrator<'_, '_>, )

Registers required components.

fn on_discard() -> Option<ComponentHook>

Gets the on_discard ComponentHook for this Component if one is defined.

fn clone_behavior() -> ComponentCloneBehavior

Called when registering this component, allowing to override clone function (or disable cloning altogether) for this component.

fn relationship_accessor() -> Option<ComponentRelationshipAccessor<Self>>

Returns ComponentRelationshipAccessor required for working with relationships in dynamic contexts.

fn on_add() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_add ComponentHook for this Component if one is defined.

fn on_insert() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_insert ComponentHook for this Component if one is defined.

fn on_remove() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_remove ComponentHook for this Component if one is defined.

fn on_despawn() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_despawn ComponentHook for this Component if one is defined.

fn map_entities<E>(_this: &mut Self, _mapper: &mut E)

where E: EntityMapper,

Maps the entities on this component using the given EntityMapper. This is used to remap entities in contexts like scenes and entity cloning. When deriving Component, this is populated by annotating fields containing entities with #[entities]

const HAS_SUMMARY_TICK: bool = false

Set this constant to true if the component should track a summary tick.

impl Debug for Conversation

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

Formats the value using the given formatter.

impl Default for Conversation

fn default() -> Self

Returns the “default value” for a type.

impl Deref for Conversation

type Target = Conversation

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for Conversation

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<'de> Deserialize<'de> for Conversation

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<Conversation> for Conversation

fn from(conversation: Conversation) -> Self

Converts to this type from the input type.

impl FromReflect for Conversation

fn from_reflect(reflect: &dyn PartialReflect) -> Option<Self>

Constructs a concrete instance of Self from a reflected value.

fn take_from_reflect( reflect: Box<dyn PartialReflect>, ) -> Result<Self, Box<dyn PartialReflect>>

Attempts to downcast the given value to Self using, constructing the value using from_reflect if that fails.

impl GetTypeRegistration for Conversation

fn get_type_registration() -> TypeRegistration

Returns the default TypeRegistration for this type.

fn register_type_dependencies(_registry: &mut TypeRegistry)

Registers other types needed by this type.

impl PartialEq for Conversation

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialReflect for Conversation

fn get_represented_type_info(&self) -> Option<&'static TypeInfo>

Returns the TypeInfo of the type represented by this value.

fn to_dynamic(&self) -> Result<Box<dyn PartialReflect>, ReflectCloneError>

Converts this reflected value into its dynamic representation based on its kind.

fn try_apply(&mut self, value: &dyn PartialReflect) -> Result<(), ApplyError>

Tries to apply a reflected value to this value.

fn reflect_kind(&self) -> ReflectKind

Returns a zero-sized enumeration of “kinds” of type.

fn reflect_ref(&self) -> ReflectRef<'_>

Returns an immutable enumeration of “kinds” of type.

fn reflect_mut(&mut self) -> ReflectMut<'_>

Returns a mutable enumeration of “kinds” of type.

fn reflect_owned(self: Box<Self>) -> ReflectOwned

Returns an owned enumeration of “kinds” of type.

fn try_into_reflect( self: Box<Self>, ) -> Result<Box<dyn Reflect>, Box<dyn PartialReflect>>

Attempts to cast this type to a boxed, fully-reflected value.

fn try_as_reflect(&self) -> Option<&dyn Reflect>

Attempts to cast this type to a fully-reflected value.

fn try_as_reflect_mut(&mut self) -> Option<&mut dyn Reflect>

Attempts to cast this type to a mutable, fully-reflected value.

fn into_partial_reflect(self: Box<Self>) -> Box<dyn PartialReflect>

Casts this type to a boxed, reflected value.

fn as_partial_reflect(&self) -> &dyn PartialReflect

Casts this type to a reflected value.

fn as_partial_reflect_mut(&mut self) -> &mut dyn PartialReflect

Casts this type to a mutable, reflected value.

fn reflect_clone(&self) -> Result<Box<dyn Reflect>, ReflectCloneError>

Attempts to clone Self using reflection.

fn apply(&mut self, value: &(dyn PartialReflect + 'static))

Applies a reflected value to this value.

fn reflect_clone_and_take<T>(&self) -> Result<T, ReflectCloneError>

where T: 'static, Self: Sized + TypePath,

For a type implementing PartialReflect, combines reflect_clone and take in a useful fashion, automatically constructing an appropriate ReflectCloneError if the downcast fails.

fn reflect_hash(&self) -> Option<u64>

Returns a hash of the value (which includes the type).

fn reflect_partial_eq( &self, _value: &(dyn PartialReflect + 'static), ) -> Option<bool>

Returns a “partial equality” comparison result.

fn reflect_partial_cmp( &self, _value: &(dyn PartialReflect + 'static), ) -> Option<Ordering>

Returns a “partial comparison” result.

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

Debug formatter for the value.

fn is_dynamic(&self) -> bool

Indicates whether or not this type is a dynamic type.

impl Reflect for Conversation

fn into_any(self: Box<Self>) -> Box<dyn Any>

Returns the value as a Box<dyn Any>.

fn as_any(&self) -> &dyn Any

Returns the value as a &dyn Any.

fn as_any_mut(&mut self) -> &mut dyn Any

Returns the value as a &mut dyn Any.

fn into_reflect(self: Box<Self>) -> Box<dyn Reflect>

Casts this type to a boxed, fully-reflected value.

fn as_reflect(&self) -> &dyn Reflect

Casts this type to a fully-reflected value.

fn as_reflect_mut(&mut self) -> &mut dyn Reflect

Casts this type to a mutable, fully-reflected value.

fn set(&mut self, value: Box<dyn Reflect>) -> Result<(), Box<dyn Reflect>>

Performs a type-checked assignment of a reflected value to this value.

impl Serialize for Conversation

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Conversation

impl TypePath for Conversation

fn type_path() -> &'static str

Returns the fully qualified path of the underlying type.

fn short_type_path() -> &'static str

Returns a short, pretty-print enabled path to the type.

fn type_ident() -> Option<&'static str>

Returns the name of the type, or None if it is anonymous.

fn crate_name() -> Option<&'static str>

Returns the name of the crate the type is in, or None if it is anonymous.

fn module_path() -> Option<&'static str>

Returns the path to the module the type is in, or None if it is anonymous.

impl Typed for Conversation

fn type_info() -> &'static TypeInfo

Returns the compile-time info for the underlying type.