Feature: Macro System with {{char}}, {{user}}, {{speaker}} substitution #17

New issue

Open

opened 2025-12-10 01:38:56 +00:00 by blightbow · 0 comments

blightbow commented

2025-12-10 01:38:56 +00:00

Owner

Summary

Implement a macro substitution system for prompt templates, compatible with SillyTavern/V3 character card conventions but adapted for multi-user MUD environments.

Key Design: `{{user}}` vs `{{speaker}}`

Problem: SillyTavern character cards reference {{user}} as a fixed relationship:

"{{char}} is married to {{user}}"
"{{char}} swore to protect {{user}}"

In MUDs, many players interact with one assistant. If {{user}} = current speaker, everyone becomes the spouse/ward.

Solution: Two distinct macros:

Macro	Binding	Use Case
`{{char}}`	Fixed (assistant's character)	"{{char}} is a blacksmith"
`{{user}}`	Fixed (configured partner entity)	"{{char}} loves {{user}}" - from character card
`{{speaker}}`	Dynamic (per-message sender)	"{{speaker}} approaches" - runtime

Macro Categories

Identity Macros

{{char}} - Assistant character name (fixed)
{{char_key}} - Assistant character dbref
{{user}} - Configured partner entity (fixed)
{{user_key}} - Configured partner dbref
{{speaker}} - Current message sender (dynamic)
{{speaker_key}} - Current message sender dbref

Location Macros

{{location}} - Current room name
{{location_desc}} - Current room description
{{exits}} - Available exits (formatted)
{{present}} - Characters in room (excluding self)

Game State Macros

{{time}} - In-game time (if available)
{{weather}} - Weather state (if available)
{{date}} - In-game date (if available)

Implementation

New Files

macros.py - MacroRegistry, MacroContext, resolve_macros()

Modified Files

assistant_script.py - Add db.user_entity attribute
helpers/ - Add set_user_entity(), get_user_entity(), clear_user_entity()
prompt_templates.py - Call macro resolution

Commands

aisetup /macro - List available macros
aisetup /macro user <entity> - Set {{user}} binding
aisetup /macro user clear - Remove binding

Tests

tests/test_macros.py

References

V3 Character Card Spec: https://github.com/kwaroran/character-card-spec-v3
SillyTavern macro system: script.js:substituteParams()

## Summary Implement a macro substitution system for prompt templates, compatible with SillyTavern/V3 character card conventions but adapted for multi-user MUD environments. ## Key Design: `{{user}}` vs `{{speaker}}` **Problem:** SillyTavern character cards reference `{{user}}` as a fixed relationship: - "{{char}} is married to {{user}}" - "{{char}} swore to protect {{user}}" In MUDs, many players interact with one assistant. If `{{user}}` = current speaker, everyone becomes the spouse/ward. **Solution:** Two distinct macros: | Macro | Binding | Use Case | |-------|---------|----------| | `{{char}}` | Fixed (assistant's character) | "{{char}} is a blacksmith" | | `{{user}}` | Fixed (configured partner entity) | "{{char}} loves {{user}}" - from character card | | `{{speaker}}` | Dynamic (per-message sender) | "{{speaker}} approaches" - runtime | ## Macro Categories ### Identity Macros - `{{char}}` - Assistant character name (fixed) - `{{char_key}}` - Assistant character dbref - `{{user}}` - Configured partner entity (fixed) - `{{user_key}}` - Configured partner dbref - `{{speaker}}` - Current message sender (dynamic) - `{{speaker_key}}` - Current message sender dbref ### Location Macros - `{{location}}` - Current room name - `{{location_desc}}` - Current room description - `{{exits}}` - Available exits (formatted) - `{{present}}` - Characters in room (excluding self) ### Game State Macros - `{{time}}` - In-game time (if available) - `{{weather}}` - Weather state (if available) - `{{date}}` - In-game date (if available) ## Implementation ### New Files - `macros.py` - MacroRegistry, MacroContext, resolve_macros() ### Modified Files - `assistant_script.py` - Add `db.user_entity` attribute - `helpers/` - Add `set_user_entity()`, `get_user_entity()`, `clear_user_entity()` - `prompt_templates.py` - Call macro resolution ### Commands - `aisetup /macro` - List available macros - `aisetup /macro user <entity>` - Set {{user}} binding - `aisetup /macro user clear` - Remove binding ### Tests - `tests/test_macros.py` ## References - V3 Character Card Spec: https://github.com/kwaroran/character-card-spec-v3 - SillyTavern macro system: `script.js:substituteParams()`