One NPC: its persona, its memory and the conversation it is having.
More...
#include <NPCBrain.h>
One NPC: its persona, its memory and the conversation it is having.
◆ NPCBrain() [1/3]
Creates a brain bound to a backend.
- Parameters
-
| provider | Backend 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.
◆ 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
-
| prompt | Text produced by the player or by the client application. |
- Returns
- The assistant answer, and why generation stopped.
- Exceptions
-
Referenced by ask().
◆ ask() [2/3]
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
-
| prompt | Text produced by the player or by the client application. |
| call | Where the pieces of the answer go, and how the call can be abandoned half way. |
- Returns
- The assembled answer, and why generation stopped.
- Exceptions
-
◆ ask() [3/3]
Sends a prompt and reports the answer while it is being produced.
- Parameters
-
| prompt | Text produced by the player or by the client application. |
| onDelta | Called with every piece of the answer as it arrives, in order. |
- Returns
- The assembled answer, and why generation stopped.
- Exceptions
-
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
-
| prompt | Text produced by the player or by the client application. |
- Returns
- The id that names this turn in the events that follow.
- Exceptions
-
| OpenAnimaError | when 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
-
| prompt | Text produced by the player or by the client application. |
- Returns
- The reply, with the document and the provider metadata.
- Exceptions
-
| OpenAnimaError | when no backend is attached, the call fails, or the answer is not the reply that was asked for. |
◆ askTurn() [2/2]
Asks for a turn as a reply and reports the dialogue while it is written.
- Parameters
-
| prompt | Text produced by the player or by the client application. |
| onDialogue | Called 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
-
| OpenAnimaError | when 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
-
| prompt | Text produced by the player or by the client application. |
- Returns
- The id that names this turn in the events that follow.
- Exceptions
-
| OpenAnimaError | when 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
-
◆ 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=()
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
-
| timeout | Longest 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()
Sets the backend used for later requests.
- Parameters
-
| provider | Backend 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
-
| catalogue | Actions 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
-
| prompt | Instruction sent as the leading system message. |
The documentation for this class was generated from the following file:
- /home/runner/work/OpenAnima/OpenAnima/include/OpenAnima/Core/NPCBrain.h