Mirrors/talemate
1
0
Fork 0
mirror of https://github.com/vegu-ai/talemate.git synced 2026-09-02 20:20:40 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
06dc7b6428dda9744311af25bf4f656fcb00a8a2
talemate/docs/user-guide/node-editor/reference/events.md
veguAI f5d41c04c8 0.37.0 (#267) 
0.37.0

- **Director Planning** — Multi-step todo lists in director chat plus a Generate long progress action for multi-beat scene arcs.
- **Auto Narration** — Unified auto-narration replacing the old Narrate after Dialogue toggle, with a chance slider and weighted action mix.
- **LLM Prompt Templates Manager** — Dedicated UI tab for viewing, creating, editing, and deleting prompt templates.
- **Character Folders** — Collapsible folders in the World Editor character list, synced across linked scenes.
- **OpenAI Compatible TTS** — Connect any number of OpenAI-compatible TTS servers in parallel.
- **KoboldCpp TTS Auto-Setup** — KoboldCpp clients with a TTS model loaded register themselves as a TTS backend.
- **Model Testing Harness** — Bundled scene that runs basic capability tests against any connected LLM.

Plus 27 improvements and 28 bug fixes
2026-05-12 21:01:51 +03:00

889 lines
34 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Events
List of currently supported events.
!!! warning "Events not listed here"
There are some other events defined in the talemate codebase that are purposefully not listed here yet.
The reason for this is that there is an ongoing cleanup process and some of them may not stick around in their current form.
You can of course still hook into them, but be aware that they may change or be removed in the future.
## Event Index
| Event | Category |
|-------|----------|
| [`game_loop`](#game_loop) | Game Loop |
| [`game_loop_actor_iter`](#game_loop_actor_iter) | Game Loop |
| [`game_loop_ai_character_iter`](#game_loop_ai_character_iter) | Game Loop |
| [`game_loop_player_character_iter`](#game_loop_player_character_iter) | Game Loop |
| [`game_loop_new_message`](#game_loop_new_message) | Game Loop |
| [`player_turn_start`](#player_turn_start) | Game Loop |
| [`scene_init`](#scene_init) | Scene Loop |
| [`scene_loop_init`](#scene_loop_init) | Scene Loop |
| [`scene_loop_init_after`](#scene_loop_init_after) | Scene Loop |
| [`scene_loop_start_cycle`](#scene_loop_start_cycle) | Scene Loop |
| [`scene_loop_end_cycle`](#scene_loop_end_cycle) | Scene Loop |
| [`scene_loop_error`](#scene_loop_error) | Scene Loop |
| [`regenerate.msg.character`](#regeneratemsgcharacter) | Regenerate |
| [`regenerate.msg.narrator`](#regeneratemsgnarrator) | Regenerate |
| [`regenerate.msg.reinforcement`](#regeneratemsgreinforcement) | Regenerate |
| [`regenerate.msg.context_investigation`](#regeneratemsgcontext_investigation) | Regenerate |
| [`agent.conversation.before_generate`](#agentconversationbefore_generate) | Conversation Agent |
| [`agent.conversation.inject_instructions`](#agentconversationinject_instructions) | Conversation Agent |
| [`agent.conversation.generated`](#agentconversationgenerated) | Conversation Agent |
| [`agent.creator.contextual_generate.before`](#agentcreatorcontextual_generatebefore) | Creator Agent |
| [`agent.creator.contextual_generate.after`](#agentcreatorcontextual_generateafter) | Creator Agent |
| [`agent.creator.autocomplete.before`](#agentcreatorautocompletebefore) | Creator Agent |
| [`agent.creator.autocomplete.after`](#agentcreatorautocompleteafter) | Creator Agent |
| [`agent.editor.revision-analysis.before`](#agenteditorrevision-analysisbefore) | Editor Agent |
| [`agent.editor.revision-analysis.after`](#agenteditorrevision-analysisafter) | Editor Agent |
| [`agent.editor.revision-revise.before`](#agenteditorrevision-revisebefore) | Editor Agent |
| [`agent.editor.revision-revise.after`](#agenteditorrevision-reviseafter) | Editor Agent |
| [`agent.narrator.before_generate`](#agentnarratorbefore_generate) | Narrator Agent |
| [`agent.narrator.inject_instructions`](#agentnarratorinject_instructions) | Narrator Agent |
| [`agent.narrator.generated`](#agentnarratorgenerated) | Narrator Agent |
| [`agent.director.guide.before_generate`](#agentdirectorguidebefore_generate) | Director Agent |
| [`agent.director.guide.inject_instructions`](#agentdirectorguideinject_instructions) | Director Agent |
| [`agent.director.guide.generated`](#agentdirectorguidegenerated) | Director Agent |
| [`agent.director.generate_choices.before_generate`](#agentdirectorgenerate_choicesbefore_generate) | Director Agent |
| [`agent.director.generate_choices.inject_instructions`](#agentdirectorgenerate_choicesinject_instructions) | Director Agent |
| [`agent.director.generate_choices.generated`](#agentdirectorgenerate_choicesgenerated) | Director Agent |
| [`agent.director.character_management.before_persist_character`](#agentdirectorcharacter_managementbefore_persist_character) | Director Agent |
| [`agent.director.character_management.after_persist_character`](#agentdirectorcharacter_managementafter_persist_character) | Director Agent |
| [`agent.world_state.time`](#agentworld_statetime) | World State Agent |
| [`agent.summarization.scene_analysis.before`](#agentsummarizationscene_analysisbefore) | Summarization Agent |
| [`agent.summarization.scene_analysis.cached`](#agentsummarizationscene_analysiscached) | Summarization Agent |
| [`agent.summarization.scene_analysis.before_deep_analysis`](#agentsummarizationscene_analysisbefore_deep_analysis) | Summarization Agent |
| [`agent.summarization.scene_analysis.after_deep_analysis`](#agentsummarizationscene_analysisafter_deep_analysis) | Summarization Agent |
| [`agent.summarization.scene_analysis.after`](#agentsummarizationscene_analysisafter) | Summarization Agent |
| [`agent.summarization.summarize.before`](#agentsummarizationsummarizebefore) | Summarization Agent |
| [`agent.summarization.summarize.after`](#agentsummarizationsummarizeafter) | Summarization Agent |
| [`agent.summarization.before_build_archive`](#agentsummarizationbefore_build_archive) | Summarization Agent |
| [`agent.summarization.after_build_archive`](#agentsummarizationafter_build_archive) | Summarization Agent |
| [`agent.summarization.layered_history.finalize`](#agentsummarizationlayered_historyfinalize) | Summarization Agent |
| [`agent.summarization.rag_build_sub_instruction`](#agentsummarizationrag_build_sub_instruction) | Summarization Agent |
| [`agent.tts.prepare.before`](#agentttspreparebefore) | TTS Agent |
| [`agent.tts.prepare.after`](#agentttsprepareafter) | TTS Agent |
| [`agent.tts.generate.before`](#agentttsgeneratebefore) | TTS Agent |
| [`agent.tts.generate.after`](#agentttsgenerateafter) | TTS Agent |
| [`agent.visual.generation.before_generate`](#agentvisualgenerationbefore_generate) | Visual Agent |
| [`agent.visual.generation.after_generate`](#agentvisualgenerationafter_generate) | Visual Agent |
## Game Loop
---
### game_loop
Triggered at the start of each game loop iteration, before the actor turns are processed. This is the master signal for the per-iteration game loop and runs once per scene loop cycle when the game loop is triggered.
!!! payload "Payload"
| Name | Type | Description |
|------|------|-------------|
| `scene` | `Scene` | The scene object |
| `had_passive_narration` | `bool` | Whether passive narration has already fired this iteration |
---
### game_loop_actor_iter
Triggered after either a player or AI character has had a turn.
!!! payload "Payload"
| Name | Type | Description |
|------|------|-------------|
| `scene` | `Scene` | The scene object |
| `actor` | `Actor` | The actor object |
| `game_loop` | `GameLoopEvent` | The parent game loop event for this iteration |
---
### game_loop_ai_character_iter
Triggered after the AI character has had a turn.
!!! payload "Payload"
| Name | Type | Description |
|------|------|-------------|
| `scene` | `Scene` | The scene object |
| `character` | `Character` | The character object |
| `game_loop` | `GameLoopEvent` | The parent game loop event for this iteration |
---
### game_loop_player_character_iter
Triggered after the player character has had a turn.
!!! payload "Payload"
| Name | Type | Description |
|------|------|-------------|
| `scene` | `Scene` | The scene object |
| `character` | `Character` | The character object |
| `game_loop` | `GameLoopEvent` | The parent game loop event for this iteration |
---
### game_loop_new_message
Triggered when a new message is added to the scene history.
!!! payload "Payload"
| Name | Type | Description |
|------|------|-------------|
| `scene` | `Scene` | The scene object |
| `message` | `SceneMessage` | The message object |
---
### player_turn_start
Triggered when the user turn starts. User input has not yet happened at this point.
!!! payload "Payload"
| Name | Type | Description |
|------|------|-------------|
| `scene` | `Scene` | The scene object |
---
## Scene Loop
### scene_init
Triggered once during scene startup, before the scene loop begins running. Use this to perform one-time setup that needs to happen as soon as a scene is loaded.
!!! payload "Payload"
| Name | Type | Description |
|------|------|-------------|
| `scene` | `Scene` | The scene object |
---
### scene_loop_init
Triggered when the scene loop is initialised. Fires once at the start of the very first scene loop cycle, after agent nodes and commands have been registered.
!!! payload "Payload"
| Name | Type | Description |
|------|------|-------------|
| `scene` | `Scene` | The scene object |
---
### scene_loop_init_after
Fires immediately after [`scene_loop_init`](#scene_loop_init). Use this when you need to react to scene loop initialisation but want to run after handlers attached to `scene_loop_init` have completed.
!!! payload "Payload"
| Name | Type | Description |
|------|------|-------------|
| `scene` | `Scene` | The scene object |
---
### scene_loop_start_cycle
Triggered when the scene loop starts a new cycle.
!!! payload "Payload"
| Name | Type | Description |
|------|------|-------------|
| `scene` | `Scene` | The scene object |
---
### scene_loop_end_cycle
Triggered when the scene loop ends a cycle.
!!! payload "Payload"
| Name | Type | Description |
|------|------|-------------|
| `scene` | `Scene` | The scene object |
---
### scene_loop_error
Triggered when an unhandled exception escapes the scene loop. Internal control-flow exceptions (like `ActedAsCharacter` and `GenerationCancelled`) are handled before this fires, so this signal indicates a real error condition that listeners may want to log or recover from.
!!! payload "Payload"
| Name | Type | Description |
|------|------|-------------|
| `scene` | `Scene` | The scene object |
---
## Regenerate Events
### regenerate.msg.character
Triggered after regeneration replaces a *CharacterMessage*.
!!! payload "Payload"
| Name | Type | Description |
|------|------|-------------|
| `scene` | `Scene` | The scene in which regeneration happened |
| `message` | `CharacterMessage` | The regenerated character message |
| `character` | `Character` | The character associated with the message |
---
### regenerate.msg.narrator
Triggered after regeneration replaces a *NarratorMessage*.
!!! payload "Payload"
| Name | Type | Description |
|------|------|-------------|
| `scene` | `Scene` | The scene object |
| `message` | `NarratorMessage` | The regenerated narrator message |
| `character` | `None` | Not applicable (always `None`) |
---
### regenerate.msg.reinforcement
Triggered when a *ReinforcementMessage* is regenerated.
!!! payload "Payload"
| Name | Type | Description |
|------|------|-------------|
| `scene` | `Scene` | The scene object |
| `message` | `ReinforcementMessage` | The regenerated reinforcement message |
| `character` | `None` | Not applicable |
---
### regenerate.msg.context_investigation
Triggered when a *ContextInvestigationMessage* is regenerated.
!!! payload "Payload"
| Name | Type | Description |
|------|------|-------------|
| `scene` | `Scene` | The scene object |
| `message` | `ContextInvestigationMessage` | The regenerated context investigation message |
| `character` | `None` | Not applicable |
## Conversation Agent Events
### agent.conversation.before_generate
Emitted **just before** the Conversation agent sends the prompt to the model.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `ConversationAgent` | The agent instance |
| `actor` | `Actor` | The speaking actor |
| `character` | `Character` | Shortcut to `actor.character` |
---
### agent.conversation.inject_instructions
Emitted while constructing the prompt, **before** the prompt is sent to the model.
Handlers can mutate `dynamic_instructions` to inject extra task instructions.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `ConversationAgent` | The agent instance |
| `character` | `Character` | Target character |
| `dynamic_instructions` | `list[DynamicInstruction]` | **Mutable.** Append strings here to include them near the top of the prompt |
---
### agent.conversation.generated
Emitted **after** the Conversation agent receives the model output but **before** the message is pushed to history.
Handlers can edit `generation` in-place to clean up or transform the text (the Editor agent does this).
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `ConversationAgent` | The agent instance |
| `actor` | `Actor` | Actor that spoke |
| `character` | `Character` | The speaking character |
| `response` | `str` | **Mutable.** Final text lines that will be turned into messages |
## Creator Agent Events
### agent.creator.contextual_generate.before
Contextual generation are things like character attributes, details, scene introductions, etc.
Emitted **before** the Creator agent sends the prompt to the model.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `CreatorAgent` | The agent instance |
| `character` | `Character` | The character that the contextual generation is for |
| `template_vars` | `dict` | Variables that will be fed into the prompt – **mutable** |
| `dynamic_instructions` | `list[DynamicInstruction]` | **Mutable.** Push additional `DynamicInstruction` objects to influence generation |
### agent.creator.contextual_generate.after
Emitted **after** the Creator agent receives the model output but **before** the message is pushed to history.
Handlers can edit `response` in-place to clean up or transform the text (the Editor agent does this).
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `CreatorAgent` | The agent instance |
| `response` | `str` | **Mutable.** Final text lines that will be turned into messages |
| `template_vars` | `dict` | Variables that were fed into the prompt – **mutable** |
| `dynamic_instructions` | `list[DynamicInstruction]` | **Mutable.** Push additional `DynamicInstruction` objects to influence generation |
### agent.creator.autocomplete.before
Autocomplete generation for character action or narrative text.
Emitted **before** the Creator agent sends the prompt to the model.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `CreatorAgent` | The agent instance |
| `input` | `str` | The input text that the autocomplete is for |
| `type` | `str` | The type of autocomplete (e.g. `dialogue`, `narrative`) |
| `character` | `Character` | The character that the autocomplete is for |
| `template_vars` | `dict` | Variables that will be fed into the prompt – **mutable** |
| `dynamic_instructions` | `list[DynamicInstruction]` | **Mutable.** Push additional `DynamicInstruction` objects to influence generation |
### agent.creator.autocomplete.after
Emitted **after** the Creator agent receives the model output but **before** the message is pushed to history.
Handlers can edit `response` in-place to clean up or transform the text (the Editor agent does this).
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `CreatorAgent` | The agent instance |
| `response` | `str` | **Mutable.** Final text lines that will be turned into messages |
| `input` | `str` | The input text that the autocomplete is for |
| `type` | `str` | The type of autocomplete (e.g. `dialogue`, `narrative`) |
| `character` | `Character` | The character that the autocomplete is for |
| `template_vars` | `dict` | Variables that were fed into the prompt – **mutable** |
| `dynamic_instructions` | `list[DynamicInstruction]` | **Mutable.** Push additional `DynamicInstruction` objects to influence generation |
## Editor Agent Events
### agent.editor.revision-revise.before
Emitted **before** the Editor agent requests the revision-revise prompt.
Handlers can add extra revise instructions via `dynamic_instructions` or adjust `template_vars`.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `EditorAgent` | The agent instance |
| `template_vars` | `dict` | Variables that will be fed into the prompt – **mutable** |
| `dynamic_instructions` | `list[DynamicInstruction]` | **Mutable.** Push additional `DynamicInstruction` objects to influence generation |
---
### agent.editor.revision-revise.after
Emitted **after** the Editor agent receives the model output but **before** the message is pushed to history.
Handlers can edit `response` in-place to clean up or transform the text (the Editor agent does this).
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `EditorAgent` | The agent instance |
| `response` | `str` | **Mutable.** Final text lines that will be turned into messages |
| `template_vars` | `dict` | Variables that were fed into the prompt – **mutable** |
| `dynamic_instructions` | `list[DynamicInstruction]` | **Mutable.** Push additional `DynamicInstruction` objects to influence generation |
---
### agent.editor.revision-analysis.before
Emitted **before** the Editor agent requests the revision-rewrite prompt.
Handlers can add extra analysis instructions via `dynamic_instructions` or adjust `template_vars`.
!!! note
The signal is named `revision-analysis.*` for historical reasons — it was
introduced when analysis and rewrite were two separate prompts. They are
now combined into a single prompt (`editor.revision-rewrite`), but the
signal name is kept for backward compatibility.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `EditorAgent` | The agent instance |
| `template_vars` | `dict` | Variables that will be fed into the prompt – **mutable** |
| `dynamic_instructions` | `list[DynamicInstruction]` | **Mutable.** Push additional `DynamicInstruction` objects to influence analysis |
---
### agent.editor.revision-analysis.after
Emitted after the revision-rewrite prompt returns. Intended as a
notification hook for observers of the rewrite flow.
!!! warning
Historically this signal fired between a separate analysis prompt and a
rewrite prompt, with `response` carrying the raw analysis text that
handlers could mutate before the rewrite ran. Analysis and rewrite are
now combined into a single prompt, so there is no separable "analysis
text" — `response` is not set on the emission and any mutation is
discarded. Use [`agent.editor.revision-revise.after`](#agenteditorrevision-reviseafter)
if you need to inspect or replace the final rewritten text.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `EditorAgent` | The agent instance |
| `template_vars` | `dict` | Same vars used for the prompt |
## Narrator Agent Events
### agent.narrator.before_generate
Emitted **before** the Narrator agent sends the prompt to the model.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `NarratorAgent` | The agent instance |
---
### agent.narrator.inject_instructions
Emitted while constructing the prompt, **before** the prompt is sent to the model.
Handlers can mutate `dynamic_instructions` to inject extra task instructions.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `NarratorAgent` | The agent instance |
| `dynamic_instructions` | `list[DynamicInstruction]` | **Mutable.** Append strings here to include them near the top of the prompt |
---
### agent.narrator.generated
Emitted **after** the Narrator agent receives the model output but **before** the message is pushed to history.
Handlers can edit `generation` in-place to clean up or transform the text (the Editor agent does this).
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `NarratorAgent` | The agent instance |
| `response` | `str` | **Mutable.** Final text lines that will be turned into messages |
## Director Agent Events
### agent.director.guide.before_generate
Emitted before the Director **guidance** module runs to craft guidance text.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `DirectorAgent` | The agent instance |
---
### agent.director.guide.inject_instructions
Runs just after the previous event. Same payload – gives one more chance to adjust `dynamic_instructions`.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `DirectorAgent` | The agent instance |
| `dynamic_instructions` | `list[DynamicInstruction]` | **Mutable.** Add strings to influence the prompt |
---
### agent.director.guide.generated
Fires after guidance text is generated, but before it is cached or written to context.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `DirectorAgent` | The agent instance |
| `response` | `str` | **Mutable.** The guidance text |
---
### agent.director.generate_choices.before_generate
Emitted before the Director generates player choice actions.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `DirectorAgent` | The agent instance |
| `character` | `Character` | The character that the choices are for |
---
### agent.director.generate_choices.inject_instructions
Run before the Director generates player choice actions, gives one more chance to adjust `dynamic_instructions`.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `DirectorAgent` | The agent instance |
| `character` | `Character` | The character that the choices are for |
| `dynamic_instructions` | `list[DynamicInstruction]` | **Mutable.** Add strings to influence the prompt |
---
### agent.director.generate_choices.generated
After choices text is ready.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `DirectorAgent` | The agent instance |
| `response` | `str` | **Mutable.** Text that describes available choices |
| `choices` | `list[str]` | **Mutable.** List of of generated choices |
| `character` | `Character` | The character that the choices are for |
---
### agent.director.character_management.before_persist_character
Emitted **before** a new character is persisted into the scene by the director's character management module. The blank `Character` instance has been created and is attached to the emission, but it has not yet been added to the scene as an actor and no attribute / detail / dialogue templates have been applied.
Useful for adjusting the character object (e.g. seeding default attributes, voice assignment hints, color overrides) before the rest of the persist pipeline runs.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `DirectorAgent` | The agent instance |
| `character` | `Character` | **Mutable.** The character about to be persisted |
---
### agent.director.character_management.after_persist_character
Emitted **after** the character has been fully persisted: actor added, generation templates applied, voice assigned (if enabled), character activated and committed to memory. The default `on-persist-character-generate-visual` module hooks into this signal to optionally generate a portrait.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `DirectorAgent` | The agent instance |
| `character` | `Character` | The character that was just persisted |
## World State Agent Events
### agent.world_state.time
Emitted when the world state agent advances the time in the scene.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `WorldStateAgent` | The agent instance |
| `duration` | `str` | The duration of the time passage (ISO 8601 duration) |
| `human_duration` | `str` | The human-readable duration of the time passage |
| `narrative` | `str` | The narrative direction of the time passage |
## Summarization Agent Events
### agent.summarization.scene_analysis.before
Emitted just before the summarizer performs a scene analysis prompt. Handlers can tweak `template_vars` or inject `dynamic_instructions` to influence the analysis.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `SummarizeAgent` | The agent instance |
| `template_vars` | `dict` | **Mutable.** Variables used in the prompt |
| `analysis_type` | `str` | `conversation` or `narration` |
| `dynamic_instructions` | `list[DynamicInstruction]` | **Mutable** |
---
### agent.summarization.scene_analysis.cached
Fired when a cached analysis is reused instead of generating a new one. Same payload as above plus `response` containing cached analysis text.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `SummarizeAgent` | The agent instance |
| `template_vars` | `dict` | **Mutable.** Variables used in the prompt |
| `analysis_type` | `str` | `conversation` or `narration` |
| `dynamic_instructions` | `list[DynamicInstruction]` | **Mutable** |
| `response` | `str` | The cached analysis text |
---
### agent.summarization.scene_analysis.before_deep_analysis
Occurs before running deep analysis passes (context investigations). Payload is `SceneAnalysisDeepAnalysisEmission`.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `SummarizeAgent` | The agent instance |
| `analysis` | `str` | Current analysis text |
| `analysis_type` | `str` | Same as above |
| `analysis_sub_type` | `str` | e.g. `progress`, `query`, etc. |
| `max_content_investigations` | `int` | Upper bound for investigations |
| `character` | `Character` | Character in focus (may be None) |
---
### agent.summarization.scene_analysis.after_deep_analysis
Fired immediately after deep analysis completes. Payload identical to previous event; handlers may alter `analysis`.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `SummarizeAgent` | The agent instance |
| `analysis` | `str` | Current analysis text |
| `analysis_type` | `str` | Same as above |
| `analysis_sub_type` | `str` | e.g. `progress`, `query`, etc. |
| `max_content_investigations` | `int` | Upper bound for investigations |
| `character` | `Character` | Character in focus (may be None) |
---
### agent.summarization.scene_analysis.after
Emitted after scene analysis is done and stored in scene state. Payload: `SceneAnalysisEmission` with `response` populated.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `SummarizeAgent` | The agent instance |
| `template_vars` | `dict` | **Mutable.** Variables used in the prompt |
| `analysis_type` | `str` | `conversation` or `narration` |
| `dynamic_instructions` | `list[DynamicInstruction]` | **Mutable** |
| `response` | `str` | The analysis text |
### agent.summarization.summarize.before
Emitted before the summarizer performs a summarize prompt. Handlers can tweak `template_vars` or inject `dynamic_instructions` to influence the summarize.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `SummarizeAgent` | The agent instance |
| `text` | `str` | The text to summarize |
| `template_vars` | `dict` | **Mutable.** Variables used in the prompt |
| `dynamic_instructions` | `list[DynamicInstruction]` | **Mutable** |
| `extra_instructions` | `str` | **Mutable.** any additional instructions |
| `generation_options` | `GenerationOptions` | **Mutable.** Generation options |
| `summarization_history` | `list[str]` | **Mutable.** any previous historical summaries |
---
### agent.summarization.summarize.after
Emitted after the summarizer performs a summarize prompt. Handlers can inspect or replace `response`.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `SummarizeAgent` | The agent instance |
| `text` | `str` | The text to summarize |
| `template_vars` | `dict` | **Mutable.** Variables used in the prompt |
| `dynamic_instructions` | `list[DynamicInstruction]` | **Mutable** |
| `extra_instructions` | `str` | **Mutable.** any additional instructions |
| `generation_options` | `GenerationOptions` | **Mutable.** Generation options |
| `summarization_history` | `list[str]` | **Mutable.** any previous historical summaries |
| `response` | `str` | **Mutable.** The summary text |
---
### agent.summarization.before_build_archive
Fires at the very top of `build_archive`, before the summarizer decides whether new archive entries need to be produced. Handlers can short-circuit or instrument the archive-building pass.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `SummarizeAgent` | The agent instance |
| `generation_options` | `GenerationOptions \| None` | Generation options that will be used for any summarization prompts performed during the build |
---
### agent.summarization.after_build_archive
Fires after `build_archive` has finished processing all eligible history entries (whether or not anything was actually summarized this pass).
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `SummarizeAgent` | The agent instance |
| `generation_options` | `GenerationOptions \| None` | The generation options that were used during the build |
---
### agent.summarization.layered_history.finalize
Emitted while finalizing a layered history archive entry. Handlers can inspect or replace the entry before it is added to the layered history. The emission exposes a `response` property that is a shortcut for `entry.text`, so handlers that only want to rewrite the summary text can mutate `response` directly.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `SummarizeAgent` | The agent instance |
| `entry` | `LayeredArchiveEntry \| None` | **Mutable.** The layered archive entry being finalized |
| `summarization_history` | `list[str]` | **Mutable.** Previous summaries used as context |
| `response` | `str \| None` | **Mutable.** Shortcut for `entry.text` |
---
### agent.summarization.rag_build_sub_instruction
Fires when the summarizer assembles the additional sub-instruction used when fetching RAG context. Mixins (and external handlers) listen on this signal to append guidance about *how* the retrieved context should be interpreted.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `SummarizeAgent` | The agent instance |
| `sub_instruction` | `str \| None` | **Mutable.** Concatenated sub-instruction to attach to the RAG query |
## TTS Agent Events
### agent.tts.prepare.before
Emitted **before** an optional `prepare_fn` runs against an audio chunk (e.g. text normalization, audio-tag rewriting, voice selection). Only fires for chunks that declare a `prepare_fn`.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `chunk` | `Chunk` | The TTS chunk about to be prepared |
| `context` | `GenerationContext` | The full generation context (all chunks for the current request) |
| `wav_bytes` | `bytes \| None` | Always `None` at this point |
---
### agent.tts.prepare.after
Fires after a chunk's `prepare_fn` has run but before audio generation starts. Handlers can inspect (or mutate) the now-prepared chunk.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `chunk` | `Chunk` | The prepared TTS chunk |
| `context` | `GenerationContext` | The full generation context |
| `wav_bytes` | `bytes \| None` | Always `None` at this point |
---
### agent.tts.generate.before
Emitted **immediately before** the chunk is sent to the active TTS backend for synthesis.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `chunk` | `Chunk` | The TTS chunk about to be synthesised |
| `context` | `GenerationContext` | The full generation context |
| `wav_bytes` | `bytes \| None` | Always `None` at this point |
---
### agent.tts.generate.after
Fires after the TTS backend returns audio for a chunk and before the audio is played back. Handlers can inspect (or replace) the produced audio via `wav_bytes`.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `chunk` | `Chunk` | The TTS chunk that was synthesised |
| `context` | `GenerationContext` | The full generation context |
| `wav_bytes` | `bytes \| None` | **Mutable.** The synthesised audio bytes (None if generation failed) |
## Visual Agent Events
### agent.visual.generation.before_generate
Emitted **before** the visual agent dispatches a generation request to the active backend (text-to-image or image-edit).
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `VisualAgent` | The agent instance |
| `request` | `GenerationRequest` | The request that is about to be sent to the backend |
| `response` | `GenerationResponse` | A response shell with `id` populated; not yet filled in |
---
### agent.visual.generation.after_generate
Fires after a generation request has completed and the resulting image has been delivered to the frontend (and optionally auto-saved as a scene asset). The same emission instance from `before_generate` is reused, so `response` now carries the generated image data.
!!! payload "Payload"
| Field | Type | Notes |
|-------|------|-------|
| `agent` | `VisualAgent` | The agent instance |
| `request` | `GenerationRequest` | The original request |
| `response` | `GenerationResponse` | The completed response, including base64 image data |
Reference in New Issue View Git Blame Copy Permalink