# Context ID Nodes

Context IDs address pieces of scene context (character attributes, world entries, etc.) with a uniform string format so they can be read, written, pinned and rendered generically.

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


_11 nodes._

| Node | Registry path |
| --- | --- |
| [Character Context IDs](#character-context-ids) | `context_id/CharacterContextIDs` |
| [Compress Context ID Part](#compress-context-id-part) | `context_id/CompressContextIDPart` |
| [Context ID Get Value](#context-id-get-value) | `context_id/ContextIDGetValue` |
| [Context ID Meta Entries](#context-id-meta-entries) | `context_id/ContextIDMetaEntries` |
| [Context ID Set Value](#context-id-set-value) | `context_id/ContextIDSetValue` |
| [Is Pin Active](#is-pin-active) | `context_id/IsPinActive` |
| [Path to Context ID](#path-to-context-id) | `context_id/PathToContextID` |
| [Remove Pin](#remove-pin) | `context_id/RemovePin` |
| [Render Context IDs](#render-context-ids) | `context_id/RenderContextIDs` |
| [Scan Context IDs](#scan-context-ids) | `context_id/ScanContextIDs` |
| [Set Pin](#set-pin) | `context_id/SetPin` |

## Character Context IDs

`context_id/CharacterContextIDs`

Unpack a character into context ID items for its various context entries
(attributes, details, description, acting instructions and example dialogue).

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `character` | `character` | The character to get context ID items for |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `character` | `character` | The character input, passed through |
| `attributes` | `list` | List of context ID items for the character's attributes |
| `details` | `list` | List of context ID items for the character's details |
| `description` | `context_id_item` | Context ID item for the character's description |
| `acting_instructions` | `context_id_item` | Context ID item for the character's acting instructions |
| `example_dialogue` | `list` | List of context ID items for the character's example dialogue |

## Compress Context ID Part

`context_id/CompressContextIDPart`

Compress a context ID part name into the short hash identifier used inside
context IDs (truncated SHA256).

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `part` | `str` | The part name to compress |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `uncompressed` | `str` | The original part, passed through |
| `compressed` | `str` | The compressed part |

## Context ID Get Value

`context_id/ContextIDGetValue`

Get the value of a context ID

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `context_id_item` | `context_id_item` |  |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `context_id_item` | `context_id_item` |  |
| `value` | `any` |  |

## Context ID Meta Entries

`context_id/ContextIDMetaEntries`

Get all defined context ID meta entries for the active scene, sorted by
context ID.

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `meta_entries` | `list` | List of context ID meta entries |
| `context_id_types` | `list` | List of unique context ID types found in the entries |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `filter_creative` | `bool` | `False` | Filter creative context ID meta entries |

## Context ID Set Value

`context_id/ContextIDSetValue`

Set the value of a context ID entry in the active scene.

The target entry can be given either as a context ID item or as a path
string (one of the two must be set). Raises an error if the entry cannot
be resolved.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | The graph state |
| `context_id_item` | `context_id_item` | The context ID item to set the value for (optional) |
| `path` | `str` | The context ID path to set the value for (optional) |
| `value` | `any` | The value to set |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` | The state input, passed through |
| `context_id_item` | `context_id_item` | The context ID item that was set |
| `path` | `str` | The path input, passed through |
| `value` | `any` | The value that was set |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `path` | `str` | `""` | The path to set the value for |

## Is Pin Active

`context_id/IsPinActive`

Check whether the world state pin for a context entry is currently active.

The target entry can be given either as a context ID item or as a path
string (one of the two must be set).

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | The graph state |
| `context_id_item` | `context_id_item` | The context ID item to check (optional) |
| `path` | `str` | The context ID path to check (optional) |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` | The state input, passed through |
| `context_id_item` | `context_id_item` | The context ID item that was checked |
| `path` | `str` | The path input, passed through |
| `active` | `bool` | Whether the pin is active |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `path` | `str` | `""` | The path to the context ID item |

## Path to Context ID

`context_id/PathToContextID`

Resolve a context ID path string into a context ID item and retrieve its
current value from the active scene.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `path` | `str` | The context ID path to resolve |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `context_id` | `context_id` | The resolved context ID (None if the path could not be resolved) |
| `context_id_item` | `context_id_item` | The resolved context ID item (None if the path could not be resolved) |
| `human_id` | `str` | Human readable identifier of the resolved item |
| `as_dict` | `dict` | The resolved item as a dictionary (empty if not resolved) |
| `name` | `str` | The name of the resolved item |
| `value` | `any` | The current value stored at the context ID |
| `exists` | `bool` | Whether the path resolved to an existing context ID item |
| `context_type` | `str` | The context type of the resolved item |
| `path` | `str` | The path input, passed through |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `path` | `str` | `""` | The path to convert to a context ID |

## Remove Pin

`context_id/RemovePin`

Remove the world state pin for a context entry and reload the scene's
active pins.

The target entry can be given either as a context ID item or as a path
string (one of the two must be set).

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | The graph state |
| `context_id_item` | `context_id_item` | The context ID item to unpin (optional) |
| `path` | `str` | The context ID path to unpin (optional) |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` | The state input, passed through |
| `context_id_item` | `context_id_item` | The context ID item that was unpinned |
| `path` | `str` | The path input, passed through |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `path` | `str` | `""` | The path to the context ID item |

## Render Context IDs

`context_id/RenderContextIDs`

Render a list of context ID items to prompt-ready text using the
`common.context_id_items` prompt template.

A single item may be passed instead of a list and will be wrapped
automatically.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `items` | `list,context_id_item` | List of context ID items to render (a single item is also accepted) |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `items` | `list` | The list of items that was rendered |
| `rendered` | `str` | The rendered text |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `display_mode` | `str` | `"compact"` | Display mode. Choices: `compact`, `subsection`, `normal`. |

## Scan Context IDs

`context_id/ScanContextIDs`

Scan text for context ID references, resolve them against the active scene
and return the results in various formats.

Resolved items are rendered through the `common.context_id_items` prompt
template and also wrapped in a dynamic instruction that can be injected
into agent prompts.

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `text` | `str` | The text to scan for context IDs |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `dynamic_instruction` | `dynamic_instruction` | Dynamic instruction containing the rendered context items |
| `rendered` | `str` | The rendered text of the resolved items |
| `context_id_items` | `list` | List of resolved context ID items |
| `unresolved` | `list` | List of context ID references that could not be resolved |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `header` | `str` | `"Relevant Context"` | The header of the dynamic instruction |
| `display_mode` | `str` | `"compact"` | The display mode of the dynamic instruction. Choices: `compact`, `subsection`, `normal`. |

## Set Pin

`context_id/SetPin`

Create or update a world state pin for a context entry, pinning it into the
AI context. The target entry can be given either as a context ID item or as
a path (one of the two must be set).

**Inputs**

| Input | Type | Description |
| --- | --- | --- |
| `state` | `any` | The graph state |
| `context_id_item` | `context_id_item` | The context ID item to pin (optional) |
| `path` | `str` | The context ID path to pin (optional) |
| `condition` | `str` | AI-evaluated condition that determines whether the pin is active (optional) |
| `condition_state` | `bool` | The current evaluation state of the condition (optional) |
| `active` | `bool` | Whether the pin is active (optional) |
| `decay` | `int` | Number of cycles the pin remains active once set, 0 for no decay (optional) |

**Outputs**

| Output | Type | Description |
| --- | --- | --- |
| `state` | `any` | The state input, passed through |
| `context_id_item` | `context_id_item` | The context ID item that was pinned |
| `path` | `str` | The path input, passed through |
| `condition` | `str` | The condition that was set |
| `condition_state` | `bool` | The condition state that was set |
| `active` | `bool` | The active state that was set |
| `decay` | `int` | The decay that was set |

**Properties**

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `path` | `str` | `""` | The path to the context ID item |
| `condition` | `str` | `""` | The condition to set the pin |
| `condition_state` | `bool` | `False` | The condition state to set the pin |
| `active` | `bool` | `False` | The active state to set the pin |
| `decay` | `int` | `0` | Number of cycles the pin remains active once set |