Sage Chat Tools

The Sage chat surface combines retrieval-backed rules answers with structured tool/card outputs for common DM prep tasks.

Main Flow

The streaming endpoint calls stream_rules_answer, which resolves a mode and executes the LangGraph campaign chat graph:

router -> rules | prep | recap

The graph writes custom events. The frontend consumes them in web/src/lib/api.ts and renders messages/cards in RulesChat.tsx.

Rules Mode

Rules mode can:

• Retrieve and cite sources.
• Answer with streamed prose.
• Abstain when citations are missing.
• Emit a dice-roll card.
• Emit a stat-block card.

Tool call detection is model-driven, but tool execution and persistence are deterministic code paths.

Prep Mode

Prep mode classifies a planning request into a sub-task:

Sub-task	Output
Encounter	Saveable encounter suggestion card.
NPC	Saveable/generated NPC card.
Loot	Loot card.
Table	Rollable table card.
General	Placeholder response.

Each structured output is persisted on RulesChatMessage so reloaded conversations can re-render cards.

Tool Modules

Module	Role
server/app/lib/tools/roll_dice.py	Parse and roll dice notation.
server/app/lib/tools/get_stat_block.py	Resolve visible monster stat blocks.
server/app/lib/encounter_suggest.py	Encounter request extraction and suggestion.
server/app/lib/loot_suggest.py	Loot request extraction and treasure generation.
server/app/lib/table_suggest.py	Rollable table generation and normalization.
server/app/lib/rag/generation.py	Shared model adapters and structured generation helpers.

Frontend Cards

Component	Event
DiceRollCard	dice_roll
StatBlock	stat_block
EncounterChatCard	encounter
NpcChatCard	npc
LootCard	loot
TableCard	table

Change Checklist

• Add backend event serialization and frontend event parsing together.
• Persist card payloads on RulesChatMessage when history should replay them.
• Keep deterministic validation outside the model.
• Add tests for request classification, normalization, and streaming events.
• Gate AI-backed tools with require_ai_access.