OpenAnima 0.2.0
Middleware for conversational NPCs that interact with the player, the world and each other
Loading...
Searching...
No Matches
Classes | Public Member Functions | List of all members
OpenAnima::Core::NPCBrain Class Reference

One NPC: its persona, its memory and the conversation it is having. More...

#include <NPCBrain.h>

Public Member Functions

 NPCBrain ()
 Creates a brain without a backend. Attach one with setProvider().
 
 NPCBrain (std::shared_ptr< OpenAnima::Provider::IProvider > provider)
 
 ~NPCBrain ()
 Destroys the brain and the history it holds, stopping a turn in flight.
 
 NPCBrain (const NPCBrain &)=delete
 
NPCBrain & operator= (const NPCBrain &)=delete
 
 NPCBrain (NPCBrain &&) noexcept
 
NPCBrain & operator= (NPCBrain &&) noexcept
 
void setProvider (std::shared_ptr< OpenAnima::Provider::IProvider > provider)
 
void setSystemPrompt (std::string prompt)
 
void setReplyCatalogue (ActionCatalogue catalogue)
 
const ActionCatalogue & replyCatalogue () const noexcept
 
Completion ask (const std::string &prompt)
 
Completion ask (const std::string &prompt, const Provider::Call &call)
 
Completion ask (const std::string &prompt, const Provider::DeltaSink &onDelta)
 
NpcReply askTurn (const std::string &prompt)
 
NpcReply askTurn (const std::string &prompt, const Provider::DeltaSink &onDialogue)
 
RequestId askTurnAsync (std::string prompt)
 
RequestId askAsync (std::string prompt)
 
void cancel (RequestId turnId)
 
std::optional< Event > poll (std::chrono::milliseconds timeout=std::chrono::milliseconds{0})
 
bool isBusy () const noexcept
 
const std::vector< ChatMessage > & history () const noexcept
 
void clearHistory ()
 Drops the conversation, keeping the backend and the system prompt.
 
std::string ping ()
 

Detailed Description

One NPC: its persona, its memory and the conversation it is having.

Constructor & Destructor Documentation

◆ NPCBrain() [1/3]

OpenAnima::Core::NPCBrain::NPCBrain ( std::shared_ptr< OpenAnima::Provider::IProvider >  provider)
explicit

Creates a brain bound to a backend.

Parameters
providerBackend used for every request.

◆ NPCBrain() [2/3]

OpenAnima::Core::NPCBrain::NPCBrain ( const NPCBrain &  )
delete

A brain is moved, not copied: copying would fork the history while sharing the backend with the copy.

◆ NPCBrain() [3/3]

OpenAnima::Core::NPCBrain::NPCBrain ( NPCBrain &&  )
noexcept

Moves a brain: the history and the backend move with it. A turn in flight keeps running and reports to the brain it was asked from.

Member Function Documentation

◆ ask() [1/3]

Completion OpenAnima::Core::NPCBrain::ask ( const std::string &  prompt)

Sends a prompt and returns the answer, with what the call produced. The prompt and the answer text join the history only when the call succeeds.

Parameters
promptText produced by the player or by the client application.
Returns
The assistant answer, and why generation stopped.
Exceptions
OpenAnimaErrorwhen no backend is attached or the call fails.

Referenced by ask().

◆ ask() [2/3]

Completion OpenAnima::Core::NPCBrain::ask ( const std::string &  prompt,
const Provider::Call &  call 
)

Sends a prompt and reports the answer while it is being produced. The history is touched the same way ask() touches it, and only once the call has succeeded and was not cancelled, so a caller that drew half an answer and then failed or stopped still has the conversation it had before.

Parameters
promptText produced by the player or by the client application.
callWhere the pieces of the answer go, and how the call can be abandoned half way.
Returns
The assembled answer, and why generation stopped.
Exceptions
OpenAnimaErrorwhen no backend is attached or the call fails.

◆ ask() [3/3]

Completion OpenAnima::Core::NPCBrain::ask ( const std::string &  prompt,
const Provider::DeltaSink &  onDelta 
)
inline

Sends a prompt and reports the answer while it is being produced.

Parameters
promptText produced by the player or by the client application.
onDeltaCalled with every piece of the answer as it arrives, in order.
Returns
The assembled answer, and why generation stopped.
Exceptions
OpenAnimaErrorwhen no backend is attached or the call fails.

References ask().

◆ askAsync()

RequestId OpenAnima::Core::NPCBrain::askAsync ( std::string  prompt)

Asks for a turn and returns at once, without waiting for the answer.

The turn reports itself as events; see poll(). The conversation is not touched until the last event of the turn has been collected, so a client that draws the answer as it arrives writes the turn down once it is done drawing it.

Parameters
promptText produced by the player or by the client application.
Returns
The id that names this turn in the events that follow.
Exceptions
OpenAnimaErrorwhen no backend is attached, or when a turn is already in flight on this brain.

◆ askTurn() [1/2]

NpcReply OpenAnima::Core::NPCBrain::askTurn ( const std::string &  prompt)

Asks for a turn as a reply: what the NPC thought, what it says and what it does.

The answer is asked for as JSON, following the schema built from the catalogue, and read back from there. The contract also travels in the instruction that goes with the prompt, so a provider that ignores the schema still answers in it. The whole document joins the history as the assistant turn, which is what lets the NPC read its own thoughts on the next one.

Parameters
promptText produced by the player or by the client application.
Returns
The reply, with the document and the provider metadata.
Exceptions
OpenAnimaErrorwhen no backend is attached, the call fails, or the answer is not the reply that was asked for.

◆ askTurn() [2/2]

NpcReply OpenAnima::Core::NPCBrain::askTurn ( const std::string &  prompt,
const Provider::DeltaSink &  onDialogue 
)

Asks for a turn as a reply and reports the dialogue while it is written.

Parameters
promptText produced by the player or by the client application.
onDialogueCalled with the dialogue as it arrives. Reasoning is not streamed: it comes with the reply, once the turn is over.
Returns
The reply, with the document and the provider metadata.
Exceptions
OpenAnimaErrorwhen no backend is attached, the call fails, or the answer is not the reply that was asked for.

◆ askTurnAsync()

RequestId OpenAnima::Core::NPCBrain::askTurnAsync ( std::string  prompt)

Asks for a reply turn and returns at once, without waiting for the answer.

Its events are the ones of askAsync(), with one difference: a Delta carries the dialogue as it is written, not the JSON that is being written, and the Finished event carries the reply. A cancelled turn leaves the history as it was, as a raw turn does.

Parameters
promptText produced by the player or by the client application.
Returns
The id that names this turn in the events that follow.
Exceptions
OpenAnimaErrorwhen no backend is attached, or when a turn is already in flight on this brain.

◆ cancel()

void OpenAnima::Core::NPCBrain::cancel ( RequestId  turnId)

Asks a turn in flight to stop before the answer is complete.

What the backend had produced by then arrives as the turn's Finished event, and the answer is marked as cancelled. The turn is not written into the conversation, whatever kind of turn it was: only one that ran to the end is. An id that is not the turn in flight is ignored, so a client can call this with an id it collected long ago without checking it first.

Parameters
turnIdTurn to stop, as returned by askAsync().

◆ history()

const std::vector< ChatMessage > & OpenAnima::Core::NPCBrain::history ( ) const
inlinenoexcept
Returns
The conversation so far, in chronological order.

◆ isBusy()

bool OpenAnima::Core::NPCBrain::isBusy ( ) const
noexcept
Returns
Whether a turn has been asked for and not collected yet.

◆ operator=()

NPCBrain & OpenAnima::Core::NPCBrain::operator= ( NPCBrain &&  )
noexcept

Move assignment.

Returns
This brain.

◆ ping()

std::string OpenAnima::Core::NPCBrain::ping ( )

Verifies that the library is linked and operational.

Returns
A human-readable status message.

◆ poll()

std::optional< Event > OpenAnima::Core::NPCBrain::poll ( std::chrono::milliseconds  timeout = std::chrono::milliseconds{0})

Collects the next event of a turn, waiting for one to appear.

Call it until it hands back a Finished or a Failed event: that is what ends the turn and frees the brain for the next one. A turn that ran to the end is then written into the history; one that failed or was cancelled leaves it as it was.

Parameters
timeoutLongest wait for an event. Zero collects what is already waiting and returns at once.
Returns
The event, or nothing when none arrived in time.

◆ replyCatalogue()

const ActionCatalogue & OpenAnima::Core::NPCBrain::replyCatalogue ( ) const
inlinenoexcept
Returns
The actions this NPC may take.

◆ setProvider()

void OpenAnima::Core::NPCBrain::setProvider ( std::shared_ptr< OpenAnima::Provider::IProvider >  provider)

Sets the backend used for later requests.

Parameters
providerBackend used for every request.

◆ setReplyCatalogue()

void OpenAnima::Core::NPCBrain::setReplyCatalogue ( ActionCatalogue  catalogue)

Sets the actions this NPC may take, and with them the shape of its answers. The base catalogue is used until this is called.

Parameters
catalogueActions the NPC may take.

◆ setSystemPrompt()

void OpenAnima::Core::NPCBrain::setSystemPrompt ( std::string  prompt)

Sets the persona or instruction that leads every request. The prompt is resolved on each call and never becomes part of the stored history.

Parameters
promptInstruction sent as the leading system message.

The documentation for this class was generated from the following file: