# Prompt Nodes

Build prompts and run generation from graphs: load and render [prompt templates](../../core-concepts/prompt-templates.md), assemble prompts dynamically (see [Prompt Building](../../core-concepts/prompt_building.md)), and generate a response with a client.

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


_7 nodes._

| Node | Registry path |
| --- | --- |
| [Build Prompt](#build-prompt) | `prompt/BuildPrompt` |
| [Clean Response](#clean-response) | `prompt/CleanResponse` |
| [Generate Response](#generate-response) | `prompt/GenerateResponse` |
| [Load Template](#load-template) | `prompt/LoadTemplate` |
| [Prompt From Template](#prompt-from-template) | `prompt/PromptFromTemplate` |
| [Render Prompt](#render-prompt) | `prompt/RenderPrompt` |
| [Template Variables](#template-variables) | `prompt/TemplateVariables` |

## Build Prompt

`prompt/BuildPrompt`

Builds a prompt from a jinja2 template, exposing common context building
blocks (scene, memory, extra context, dynamic instructions etc.) as
template variables that can be toggled through the node's properties.

Loads the template `{scope}.{template_file}` and renders it against the
active scene using the agent's client for token budgeting. Outputs both the
Prompt object and the rendered prompt text.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | The graph state |
| `agent` | `agent` | The agent whose client is used for rendering and token budgeting |
| `instructions` | `str` | Task instructions made available to the template (optional) |
| `dynamic_context` | `list` | List of DynamicInstruction objects injected as extra context (optional) |
| `dynamic_instructions` | `list` | List of DynamicInstruction objects injected as instructions (optional) |
| `memory_prompt` | `str` | Semantic query / retrieval prompt for the memory context (optional) |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `state` | The state input, passed through |
| `agent` | `agent` | The agent input, passed through |
| `prompt` | `prompt` | The built Prompt object |
| `rendered` | `str` | The rendered prompt text |
| `response_length` | `int` | The configured response length, passed through |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `template_file` | `str` | `"base"` | The template file to use |
| `scope` | `str` | `"common"` | The scope of the template |
| `instructions` | `text` | `""` | The instructions to include in the prompt |
| `reserved_tokens` | `int` | `312` | The number of tokens to reserve to account for any overhead. Range: 16 – 1024. |
| `limit_max_tokens` | `int` | `0` | Limit the maximum number of tokens used for the prompt (0 = client context limit). Min: 0. |
| `include_scene_intent` | `bool` | `True` | Include the scene intent |
| `include_extra_context` | `bool` | `True` | Include the extra context (pins, reinforcements, content classification) |
| `include_memory_context` | `bool` | `True` | Include the memory context |
| `include_scene_context` | `bool` | `True` | Include the scene context |
| `include_character_context` | `bool` | `False` | Include the active character context |
| `include_gamestate_context` | `bool` | `False` | Include the game state context |
| `memory_prompt` | `str` | `""` | Semantic query / retrieval prompt for memory |
| `prefill_prompt` | `str` | `""` | Prefill the prompt with a response |
| `return_prefill_prompt` | `bool` | `False` | Return the prefill prompt with the response |
| `dedupe_enabled` | `bool` | `True` | Enable deduplication |
| `response_length` | `int` | `0` | The length of the response |
| `technical` | `bool` | `False` | Include the technical context where applicable (ids, typing etc.) |

## Clean Response

`prompt/CleanResponse`

Cleans a response

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `response` | `str` | The response to clean |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `cleaned` | `str` | The cleaned response |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `partial_sentences` | `bool` | `True` | partial_sentences |
| `strip_partial_sentences` | `bool` | `True` | Strip partial sentences from the response |

## Generate Response

`prompt/GenerateResponse`

Sends a prompt to the agent and generates a response

Retries up to `attempts` times on an empty response. When a
response_spec is provided its extractors are applied to the
response; otherwise, if the template produced a data structure,
that is used as the extracted value.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | The graph state |
| `agent` | `agent` | The agent to send the prompt to |
| `prompt` | `prompt` | The prompt to send to the agent |
| `action_type` | `str` | Classification of the generated response (optional) |
| `response_length` | `int` | The maximum length of the response (optional) |
| `response_spec` | `response/spec` | (optional) Optional ResponseSpec for extracting structured data from response |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `state` | The state input, passed through |
| `agent` | `agent` | The agent that generated the response |
| `prompt` | `prompt` | The Prompt object, passed through |
| `response` | `str` | The response from the agent |
| `data_obj` | `dict,list` | The data structure of the response (when data_output is enabled) |
| `captured_context` | `str` | Context captured by the template during rendering |
| `rendered_prompt` | `str` | The rendered prompt |
| `response_spec` | `response/spec` | Pass-through of the input response spec |
| `extracted` | `dict` | Dictionary of extracted values (when response_spec provided) |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `data_output` | `bool` | `False` | Output the response as a data structure |
| `data_multiple` | `bool` | `False` | Allow multiple data structures in the response |
| `response_length` | `int` | `256` | The maximum length of the response |
| `action_type` | `str` | `"scene_direction"` | Classification of the generated response. Choices: `analyze`, `conversation`, `create`, `edit`, `narrate`, `scene_direction`, `summarize`, `visualize`, `world_state`. |
| `attempts` | `int` | `1` | The number of attempts (retry on empty response) |

## Load Template

`prompt/LoadTemplate`

Loads the raw unrendered jinja2 template content based on scope and name

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `name` | `str` | (optional) The template name (without .jinja2 extension) |
| `scope` | `str` | (optional) The template scope (optional, defaults to property) |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `template_content` | `str` | The raw unrendered template content as a string |
| `scope` | `str` | The resolved template scope, passed through |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `scope` | `str` | `"scene"` | The template scope. Choices are generated at runtime. |
| `name` | `str` | `""` | The template name to load (without .jinja2 extension) |

## Prompt From Template

`prompt/PromptFromTemplate`

Loads a talemate template prompt

Either a template file or raw template text must be provided (but
not both).

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `template_file` | `str` | The template file to load (optional) |
| `template_text` | `str` | Raw template text to use instead of a file (optional) |
| `variables` | `dict` | The variables to use in the template (optional) |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `prompt` | `prompt` | The Prompt instance |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `scope` | `str` | `"scene"` | The template scope. Choices are generated at runtime. |
| `template_file` | `str` | `""` | The template to load |
| `template_text` | `text` | `""` | The template text to use |
| `dedupe` | `bool` | `True` | Enable prompt deduplication |

## Render Prompt

`prompt/RenderPrompt`

Renders a prompt

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `prompt` | `prompt` | The prompt to render |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `rendered` | `str` | The rendered prompt |

## Template Variables

`prompt/TemplateVariables`

Helper node that returns a pre defined set of common
template variables

Variables:

- scene: The current scene
- scene_title: The scene title (falls back to the scene name)
- max_tokens: The maximum number of tokens in the response
- agent: The relevant agent

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `agent` | `agent` | The relevant agent |
| `merge_with` | `dict` | A dictionary of variables to merge with the pre defined variables (optional) |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `variables` | `dict` | A dictionary of variables |
| `agent` | `agent` | The relevant agent |