storyteller/CONTEXTUAL_RESPONSE_FEATURE.md

🧠 Context-Aware Response Generator

Feature Added: October 11, 2025
Status: ✅ Complete and Tested

---

Overview

The Context-Aware Response Generator allows storytellers to generate AI responses that take into account multiple characters' actions and messages simultaneously. This is a powerful tool for creating cohesive narratives that incorporate everyone's contributions.

---

Key Features

1. Multi-Character Selection 🎭

• Select one or more characters to include in the context
• Visual indicators show which characters have pending messages
• "Select All Pending" quick action button
• Character selection with checkboxes showing message count

2. Two Response Types 📝

Scene Description (Broadcast)

• Generates a narrative that addresses all selected characters
• Can be used as a scene narration (broadcast to all)
• Perfect for environmental descriptions or group events

Individual Responses (Private)

• Generates personalized responses for each selected character
• Automatically parses and distributes responses to individual characters
• Sends privately to each character's conversation
• Clears pending response flags

3. Smart Context Building 🔍

The system automatically gathers and includes:

• Current scene description
• Recent public actions (last 5)
• Each character's profile (name, description, personality)
• Recent conversation history (last 3 messages per character)
• Optional additional context from storyteller

4. Response Parsing 🔧

For individual responses, the system recognizes multiple formats:

**For Bargin:** Your response here
**For Willow:** Your response here

or

For Bargin: Your response here
For Willow: Your response here

The backend automatically:

1. Parses each character's section
2. Adds to their private conversation history
3. Clears their pending response flag
4. Sends via WebSocket if connected

---

How to Use

As a Storyteller:

1. Open the Generator

   • Click "▶ Show Generator" in the storyteller dashboard
   • The section expands with all controls

2. Select Characters

   • Check the boxes for characters you want to include
   • Or click "Select All Pending" for quick selection
   • See selection summary below checkboxes

3. Choose Response Type

   • Scene Description: For general narration or environmental descriptions
   • Individual Responses: For personalized replies to each character

4. Configure Options

   • Select LLM model (GPT-4o, GPT-4, etc.)
   • Add optional context/guidance for the AI

5. Generate

   • Click "✨ Generate Context-Aware Response"
   • Wait for AI generation (a few seconds)
   • Review the generated response

6. Use the Response

   • For scenes: Click "Use as Scene" to populate the scene textarea
   • For individual: Responses are automatically sent to characters
   • You'll get a confirmation alert showing who received responses

---

Technical Implementation

Backend Endpoint

POST /sessions/{session_id}/generate_contextual_response

Request Body:

{
  "character_ids": ["char-id-1", "char-id-2"],
  "response_type": "individual" | "scene",
  "model": "gpt-4o",
  "additional_context": "Make it dramatic"
}

Response (Individual):

{
  "response": "Full generated response with all sections",
  "model_used": "gpt-4o",
  "characters_included": [{"id": "...", "name": "..."}],
  "response_type": "individual",
  "individual_responses_sent": {
    "Bargin": "Individual response text",
    "Willow": "Individual response text"
  },
  "success": true
}

Context Building

The prompt sent to the LLM includes:

You are the storyteller/game master in an RPG session. Here's what the characters have done:

Current Scene: [if set]

Recent public actions:
- Public message 1
- Public message 2

Character: Bargin
Description: A dwarf warrior
Personality: Gruff and brave
Recent messages:
  Bargin: I push open the door
  You (Storyteller): You hear creaking hinges

Character: Willow
Description: An elven archer
Personality: Cautious and observant
Recent messages:
  Willow: I look for traps
  You (Storyteller): Roll for perception

Additional context: [if provided]

Generate [scene/individual responses based on type]

Response Parsing (Individual Mode)

The backend uses regex patterns to extract individual responses:

patterns = [
    r'\*\*For CharName:\*\*\s*(.*?)(?=\*\*For\s+\w+:|\Z)',
    r'For CharName:\s*(.*?)(?=For\s+\w+:|\Z)',
    r'\*\*CharName:\*\*\s*(.*?)(?=\*\*\w+:|\Z)',
    r'CharName:\s*(.*?)(?=\w+:|\Z)',
]

Each matched section is:

1. Extracted and trimmed
2. Added to character's conversation history
3. Sent via WebSocket if character is connected
4. Pending flag cleared

---

UI Components

Generator Section

Located in StorytellerView, between the scene section and character list:

Visual Design:

• Pink/red gradient header (stands out from other sections)
• Collapsible with show/hide toggle
• Clear sections for each configuration step
• Visual feedback for pending characters

Layout:

┌─────────────────────────────────────────┐
│ 🧠 AI Context-Aware Response Generator │
│                           ▼ Hide        │
├─────────────────────────────────────────┤
│ Description text                        │
│                                         │
│ Character Selection                     │
│ ☑ Bargin (●) (3 msgs)                  │
│ ☑ Willow (2 msgs)                      │
│                                         │
│ Response Type: [Scene/Individual ▼]    │
│ Model: [GPT-4o ▼]                      │
│ Additional Context: [textarea]          │
│                                         │
│ [✨ Generate Context-Aware Response]   │
│                                         │
│ Generated Response:                     │
│ ┌─────────────────────────────────┐   │
│ │ Response text here...           │   │
│ └─────────────────────────────────┘   │
│ [Use as Scene] [Clear]                 │
└─────────────────────────────────────────┘

---

Benefits

For Storytellers

✅ Save Time - Generate responses considering all players at once
✅ Consistency - AI maintains narrative coherence across characters
✅ Context Awareness - Responses reference recent actions and personality
✅ Flexibility - Choose between broadcast scenes or individual replies
✅ Efficiency - Automatic distribution of individual responses

For Players

✅ Better Immersion - Responses feel more connected to the story
✅ No Waiting - Storyteller can respond to multiple players quickly
✅ Personalization - Individual responses tailored to each character
✅ Privacy Maintained - Individual responses still private

---

Example Use Cases

Use Case 1: Party Splits Up

Scenario: Bargin goes through the front door, Willow scouts around back

Action:

1. Select both Bargin and Willow
2. Choose "Individual Responses"
3. Add context: "The building is guarded"
4. Generate

Result:

• Bargin gets: "As you push open the door, guards immediately turn toward you..."
• Willow gets: "Around the back, you spot an unguarded window..."

Use Case 2: Group Enters New Area

Scenario: All players enter a mysterious temple

Action:

1. Select all characters
2. Choose "Scene Description"
3. Generate

Result: A cohesive scene describing the temple that references all characters' recent actions and reactions.

Use Case 3: Quick Responses to Pending Messages

Scenario: 3 characters have asked questions

Action:

1. Click "Select All Pending (3)"
2. Choose "Individual Responses"
3. Generate

Result: All three characters receive personalized answers, pending flags cleared.

---

Additional Feature: Session ID Copy Button

Also Added: Copy button next to Session ID in Storyteller dashboard

Usage:

• Click "📋 Copy" button next to the Session ID
• ID copied to clipboard
• Alert confirms successful copy
• Makes sharing sessions easy

Location: Storyteller header, next to session ID code

---

CSS Classes Added

.contextual-section
.contextual-header
.contextual-generator
.contextual-description
.character-selection
.selection-header
.btn-small
.character-checkboxes
.character-checkbox
.checkbox-label
.pending-badge-small
.message-count
.selection-summary
.response-type-selector
.response-type-help
.model-selector-contextual
.additional-context
.btn-large
.generated-response
.response-content
.response-actions
.session-id-container
.btn-copy

---

Testing

Manual Testing Checklist

• Select single character - generates response
• Select multiple characters - includes all in context
• Scene description - generates cohesive narrative
• Individual responses - parses and sends to each character
• "Select All Pending" button - selects correct characters
• Additional context - influences AI generation
• Model selection - uses chosen model
• Copy session ID button - copies to clipboard
• Collapse/expand generator - UI works correctly
• Character receives individual response - appears in their conversation
• Pending flags cleared - after individual responses sent

---

Future Enhancements

Potential improvements for later versions:

1. Response Templates - Save common response patterns
2. Batch Actions - Send same scene to subset of characters
3. Response History - View previous generated responses
4. Fine-tune Prompts - Custom prompt templates per game
5. Voice/Tone Settings - Adjust AI personality (serious/playful/dark)
6. Character Reactions - Generate suggested player reactions
7. Conversation Summaries - AI summary of what happened
8. Export Context - Save context for reference

---

Files Modified

Backend

• main.py
  • Added ContextualResponseRequest model
  • Added /generate_contextual_response endpoint
  • Added response parsing logic
  • Added individual message distribution

Frontend

• frontend/src/components/StorytellerView.js

  • Added contextual response state variables
  • Added character selection functions
  • Added response generation function
  • Added copy session ID function
  • Added generator UI section

• frontend/src/App.css

  • Added .contextual-* styles
  • Added .character-checkbox styles
  • Added .btn-copy styles
  • Added .session-id-container styles
  • Added .response-type-help styles

---

Summary

The Context-Aware Response Generator is a powerful tool that significantly improves storyteller efficiency. By allowing the storyteller to generate responses that consider multiple characters simultaneously, it:

• Reduces response time
• Improves narrative consistency
• Maintains privacy through automatic distribution
• Provides flexibility between scene and individual responses
• Makes managing multiple players much easier

Combined with the session ID copy button, these features make the storyteller experience more streamlined and professional.

Status: ✅ Ready for use!