# Creator Agent Nodes

Content creation through the creator agent: contextual generation, character creation and per-character derivations (name, description, dialogue instructions) plus thematic lists.

!!! note "Create Character module changes in 0.39.0"
    The [Create Character](#create-character) module now builds its character through the [Generate Character](#generate-character) node, so it follows the Creator agent's [Character Creation settings](/talemate/user-guide/agents/creator/settings/) (including Fast mode). It also gained two inputs:

    - `generate_dialogue_instructions` defaults **on** — existing graphs calling the module now generate dialogue instructions for the new character, which is an extra prompt whenever Fast mode is off (or not consolidating that aspect).
    - `generate_example_dialogue` defaults **off**.

<!-- glossary:generated - everything below this line is generated by `python -m talemate.game.engine.nodes.tools glossary --write` - do not edit -->


_9 nodes._

| Node | Registry path |
| --- | --- |
| [Contextual Generate](#contextual-generate) | `agents/creator/ContextualGenerate` |
| [Create Character](#create-character) | `agents/creator/CreateCharacter` |
| [Determine Character Description](#determine-character-description) | `agents/creator/DetermineCharacterDescription` |
| [Determine Character Dialogue Instructions](#determine-character-dialogue-instructions) | `agents/creator/DetermineCharacterDialogueInstructions` |
| [Determine Character Name](#determine-character-name) | `agents/creator/DetermineCharacterName` |
| [Determine Content Context](#determine-content-context) | `agents/creator/DetermineContentContext` |
| [Generate Character](#generate-character) | `agents/creator/GenerateCharacter` |
| [Generate Thematic List](#generate-thematic-list) | `agents/creator/GenerateThematicList` |
| [Creator Settings](#creator-settings) | `agents/creator/Settings` |

## Contextual Generate

`agents/creator/ContextualGenerate`

Generates text based on the given context.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | The current state of the graph |
| `context_type` | `str` | (optional) The type of context to use in generating the text |
| `context_name` | `str` | (optional) The name of the context to use in generating the text |
| `instructions` | `str` | (optional) The instructions to use in generating the text |
| `length` | `int` | (optional) The length of the text to generate |
| `character` | `character,str` | (optional) The character to generate the text for |
| `original` | `str` | (optional) The original text to use in generating the text |
| `partial` | `str` | (optional) The partial text to use in generating the text |
| `uid` | `str` | (optional) The uid to use in generating the text |
| `generation_options` | `generation_options` | (optional) The generation options to use in generating the text |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` | The updated state of the graph |
| `text` | `str` | The generated text |
| `character` | `character` | The character object resolved from the character input |
| `context_type` | `str` | The context type, passed through |
| `context_name` | `str` | The context name, passed through |
| `instructions` | `str` | The instructions, passed through |
| `original` | `str` | The original text, passed through |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `context_type` | `str` | `"general"` | The type of context to use in generating the text. Choices: `character attribute`, `character detail`, `character dialogue`, `scene intro`, `scene intent`, `scene phase intent`, `scene type description`, `scene type instructions`, `general`, `list`, `scene`, `static history`, …. |
| `context_name` | `str` | `unset` | The name of the context to use in generating the text |
| `instructions` | `str` | `unset` | The instructions to use in generating the text |
| `length` | `int` | `100` | The length of the text to generate |
| `character` | `str` | `unset` | The character to generate the text for |
| `uid` | `str` | `unset` | The uid to use in generating the text |
| `context_aware` | `bool` | `True` | Whether to use the context in generating the text |
| `history_aware` | `bool` | `True` | Whether to use the history in generating the text |

## Create Character

`agents/creator/CreateCharacter`

Node module (base type `core/Graph`) defined in `src/talemate/agents/creator/modules/create-character.json`.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` |  |
| `instructions` | `str` |  |
| `character_name` | `str` | (optional) |
| `description` | `str` | (optional) |
| `generate` | `bool` | (optional) |
| `generate_attributes` | `bool` | (optional) |
| `generate_dialogue_instructions` | `bool` | (optional) |
| `generate_example_dialogue` | `bool` | (optional) |
| `is_active` | `bool` | (optional) |
| `generation_options` | `generation_options` | (optional) |
| `is_player` | `bool` | (optional) |
| `assign_voice` | `bool` | (optional) |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `` |  |
| `character` | `character` |  |
| `actor` | `actor` |  |

## Determine Character Description

`agents/creator/DetermineCharacterDescription`

Determines the description for a character.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | The current state of the graph |
| `character` | `character` | The character to determine the description for |
| `extra_context` | `str` | (optional) Extra context to use in determining the description |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `description` | `str` | The determined description (empty if the model produced nothing) |

## Determine Character Dialogue Instructions

`agents/creator/DetermineCharacterDialogueInstructions`

Determines dialogue (acting) instructions for a character, via the
creator agent. The result is returned but not stored on the character
by this node.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | The current state of the graph |
| `character` | `character` | The character to determine dialogue instructions for |
| `instructions` | `str` | Additional instructions to guide the generation (optional) |
| `update_existing` | `bool` | Whether to base the result on the character's existing dialogue instructions (optional) |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` | The state input, passed through |
| `character` | `character` | The character, passed through |
| `dialogue_instructions` | `str` | The determined dialogue instructions |
| `original` | `str` | The character's dialogue instructions before generation |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `instructions` | `text` | `""` | Any additional instructions to use in determining the dialogue instructions |
| `update_existing` | `bool` | `False` | Whether to update the existing dialogue instructions |

## Determine Character Name

`agents/creator/DetermineCharacterName`

Determines (or clarifies) a character name from an existing or descriptive name.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | The current state of the graph |
| `character_name` | `str` | (optional) The current or descriptive character name |
| `allowed_names` | `list` | (optional) Optional list of allowed names to select from |
| `is_group` | `bool` | (optional) Whether the name describes a group of characters |
| `instructions` | `str` | (optional) Additional instructions to guide name generation |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` | The current state of the graph (pass-through) |
| `character_name` | `str` | The determined name |
| `original` | `str` | The original character_name input |
| `allowed_names` | `list` | The allowed_names input (pass-through) |
| `is_group` | `bool` | The is_group input (pass-through) |
| `instructions` | `str` | The instructions input (pass-through) |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `character_name` | `str` | `""` | The current or descriptive character name |
| `allowed_names` | `list` | `[]` | Optional list of allowed names to select from |
| `is_group` | `bool` | `False` | Whether the name describes a group of characters |
| `instructions` | `text` | `""` | Additional instructions to guide name generation |

## Determine Content Context

`agents/creator/DetermineContentContext`

Determines a fitting content context label (genre / style descriptor)
for the given description, via the creator agent.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | The current state of the graph |
| `description` | `str` | (optional) The description to determine the content context for (required at runtime despite the optional socket) |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `content_context` | `str` | The determined content context |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `description` | `str` | `unset` | Description of the context |

## Generate Character

`agents/creator/GenerateCharacter`

Generates character data through the creator agent's character
generation pipeline, following the agent's "Character Creation"
settings.

With "Fast Character Generation" enabled, the aspects listed in the
agent's "Consolidate" setting are generated with a single
consolidated prompt (response budget from the "One-shot token budget"
setting; aspects the response misses are handled according to the
"Fill in misses" setting - individual follow-up requests or left
empty; a completely unparseable response raises an error). Remaining
aspects - or all of them, with Fast mode disabled - are generated
individually.

This node only generates data - it does not add the character to the
scene. Wire the outputs into an `agents/director/PersistCharacter` node
to persist the character (disable `determine_name` on that node when
wiring a generated name, and wire `description` through as well, so
nothing is generated twice).

Generating example dialogue requires a name: provide `character_name`
or enable `generate_name` - the node errors otherwise.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | The current state of the graph |
| `character_name` | `str` | The current or descriptive character name (optional) |
| `instructions` | `str` | Guiding instructions / content for the creation (optional) |
| `description` | `str` | An existing description to use as context (optional) |
| `generation_options` | `generation_options` | Spice / writing style to shape the description (optional) |
| `generate_name` | `bool` | Whether to generate a name (optional) |
| `generate_description` | `bool` | Whether to generate a description (optional) |
| `generate_attributes` | `bool` | Whether to generate attributes (optional) |
| `generate_dialogue_instructions` | `bool` | Whether to generate dialogue instructions (optional) |
| `generate_example_dialogue` | `bool` | Whether to generate example dialogue lines (optional) |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` | The state input, passed through |
| `character_name` | `str` | The determined (or input) character name |
| `description` | `str` | The generated (or input) description |
| `attributes` | `dict` | The generated attributes (empty if not generated) |
| `dialogue_instructions` | `str` | The generated dialogue instructions (empty if not generated) |
| `example_dialogue` | `list` | The generated example dialogue lines (empty if not generated) |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `generate_name` | `bool` | `False` | Determine a fitting character name |
| `generate_description` | `bool` | `True` | Generate the character description |
| `generate_attributes` | `bool` | `True` | Generate the character sheet (attributes) |
| `generate_dialogue_instructions` | `bool` | `True` | Generate dialogue (acting) instructions |
| `generate_example_dialogue` | `bool` | `False` | Generate example dialogue lines |

## Generate Thematic List

`agents/creator/GenerateThematicList`

Generates a list of thematic items based on the instructions.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` |  |
| `instructions` | `str` | (optional) |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` |  |
| `list` | `list` |  |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `instructions` | `str` | `unset` | The instructions to use in generating the list |
| `iterations` | `int` | `1` | The number of iterations to use in generating the list - 1 iteration will generate 20 items. Range: 1 – 10. |

## Creator Settings

`agents/creator/Settings`

Base node to render creator agent settings.

Every setting of the creator agent is exposed as an output socket named after the setting - see the agent's documentation under [Agents](../../../agents/index.md) for what each setting does.