Party Validator

Party Validator Skill

Validate, create, and manage D&D party configuration files for accurate speaker mapping.

What This Skill Does

This skill helps manage party configurations to ensure accurate speaker-to-character mapping during session processing:

1. Validate Configurations: Check party config files for correct structure and data
2. Create New Configs: Generate party configuration files from templates
3. Update Configs: Modify existing configurations with new players or characters
4. Compare Configs: Diff multiple party configurations
5. Speaker Mapping: Preview how speakers will be mapped to characters
6. Troubleshoot Issues: Diagnose and fix common configuration problems

Why Party Configs Matter

Party configurations enable:

• Accurate Speaker Mapping: Map SPEAKER_00, SPEAKER_01, etc. to actual players
• Character Attribution: Link dialogue to D&D characters for IC content
• Knowledge Extraction: Properly attribute actions and dialogue to characters
• Consistent Naming: Maintain consistent player/character names across sessions

Configuration File Structure

Location

Party configs are stored in: data/party_<name>.json

Schema

{
  "party_name": "Main Campaign Party",
  "campaign": "Dragon Heist",
  "dm": {
    "name": "Alice",
    "voice_characteristics": "Female, low pitch, authoritative"
  },
  "players": [
    {
      "name": "Bob",
      "voice_characteristics": "Male, mid pitch, energetic",
      "characters": [
        {
          "name": "Thorin Ironfist",
          "class": "Fighter",
          "race": "Dwarf"
        }
      ]
    },
    {
      "name": "Charlie",
      "voice_characteristics": "Male, high pitch, dramatic",
      "characters": [
        {
          "name": "Elara Moonwhisper",
          "class": "Wizard",
          "race": "Elf"
        }
      ]
    }
  ]
}

Required Fields

Root Level:

• party_name (string): Descriptive name for the party
• dm (object): Dungeon Master information
• players (array): List of player objects

DM Object:

• name (string): DM's real name

Player Object:

• name (string): Player's real name
• characters (array): List of character objects (can be empty for new players)

Character Object:

• name (string): Character's name in the game
• class (string): D&D class (optional but recommended)
• race (string): D&D race (optional but recommended)

Optional Fields

• campaign (string): Campaign name or setting
• voice_characteristics (string): Voice description to aid speaker mapping
• session_range (array): e.g., [1, 50] - sessions this config applies to
• notes (string): Additional information about the party
• created_date (string): When configuration was created
• last_updated (string): Last modification date

Usage

Validate Existing Config

User: "Validate the default party configuration" User: "Check if party_main.json is correct" User: "Is the party config valid?"

Validate All Configs

User: "Validate all party configurations" User: "Check all party config files"

Create New Config

User: "Create a new party config called 'oneshot' with 3 players" User: "Set up a party configuration for my new campaign"

Update Existing Config

User: "Add a new player named David to the main party config" User: "Update Bob's character to level 5 Paladin"

Troubleshoot Issues

User: "Why is speaker mapping wrong for session 12?" User: "The DM is being identified as a player. Help me fix the config."

Command Reference

# Validate specific config
python cli.py validate-config --party default

# Validate all configs
python cli.py validate-config --all

# Create new config
python cli.py create-party-config --name oneshot --players Alice Bob Charlie

# Update config
python cli.py update-party-config --name default --add-player David

# Show config
python cli.py show-party-config --name default

# List all configs
python cli.py list-party-configs

MCP Tool Integration

Use mcp__videochunking-dev__validate_party_config to validate configurations.

Validate Specific Config

# Via MCP tool
validate_party_config(config_name="default")

Returns:

{
  "file": "party_default.json",
  "valid": true,
  "player_count": 4,
  "character_count": 4,
  "errors": [],
  "warnings": []
}

Validate All Configs

# Via MCP tool
validate_party_config()  # No config_name = validate all

Returns:

{
  "configs": [
    {
      "file": "party_default.json",
      "valid": true,
      "player_count": 4,
      "character_count": 4,
      "errors": [],
      "warnings": []
    },
    {
      "file": "party_oneshot.json",
      "valid": false,
      "errors": ["Missing 'dm' field"],
      "warnings": ["Player 0 has no characters"]
    }
  ],
  "total_validated": 2
}

Validation Rules

Critical Errors (Must Fix)

• ❌ Missing party_name field
• ❌ Missing dm object
• ❌ Missing players array
• ❌ Invalid JSON syntax
• ❌ DM missing name field
• ❌ Player missing name field
• ❌ Characters array is not a list
• ❌ Duplicate player names
• ❌ Character missing name field

Warnings (Should Review)

• ⚠️ Player has no characters (might be observer or new)
• ⚠️ Character missing class or race (less detailed extraction)
• ⚠️ No voice_characteristics (harder to map speakers)
• ⚠️ Very few players (<2) or many players (>8)
• ⚠️ No campaign specified
• ⚠️ Empty or very short character names

Recommendations

• ℹ️ Add voice_characteristics for better speaker mapping
• ℹ️ Include character class and race for richer knowledge extraction
• ℹ️ Specify campaign name for organization
• ℹ️ Add notes about campaign setting or party dynamics

Common Issues and Solutions

Issue: Missing Required Field

Error: Missing 'dm' field in party_custom.json

Solution:
Add DM information:
{
  "dm": {
    "name": "Your DM Name"
  }
}

Issue: Invalid JSON Syntax

Error: Invalid JSON in party_default.json - Unexpected token at line 15

Solution:
- Check for missing commas between fields
- Ensure all quotes are matched
- Verify no trailing commas
- Use JSON validator: jsonlint.com

Issue: Duplicate Player Names

Error: Duplicate player name 'Bob' found in party_main.json

Solution:
- Use unique player names
- If same person plays different characters across sessions,
  use disambiguating names: "Bob_Character1", "Bob_Character2"
- Or create separate configs per session range

Issue: Player Has No Characters

Warning: Player 'Charlie' has no characters defined

Solutions:
1. Add character to players array:
   "characters": [{"name": "CharName", "class": "Rogue", "race": "Human"}]
2. If player is observer/DM assistant, this is okay (can ignore warning)
3. If new campaign, add character after character creation session

Issue: Wrong Speaker Mapping

Problem: SPEAKER_00 is mapped to wrong player in output

Solutions:
1. Check if voice_characteristics are accurate and distinct
2. Verify player order matches typical speaking order
3. Review diarization settings (may need adjustment)
4. Consider manual speaker label correction post-processing
5. Ensure no players are missing from config

Issue: Character Name Mismatched

Problem: Character name in transcript doesn't match config

Solutions:
1. Update config with actual name used in game
2. Add name variations/aliases to character object
3. Use consistent character names during play
4. Manually correct extracted knowledge if needed

Creating New Party Configs

Template-Based Creation

Use provided template:

cp data/party_template.json data/party_newcampaign.json
# Edit party_newcampaign.json with actual information
python cli.py validate-config --party newcampaign

Interactive Creation

Follow prompts:

python cli.py create-party-config --interactive

Party name: Summer Oneshot
Campaign name (optional): Lost Mine of Phandelver
DM name: Alice

How many players? 4

Player 1 name: Bob
Player 1 voice: Male, deep voice
Player 1 character name: Thorin
Player 1 character class: Fighter
Player 1 character race: Dwarf

... (repeat for all players)

Config saved to: data/party_summer_oneshot.json
Validation: ✅ VALID

Programmatic Creation

from src.party_config import PartyConfig

config = PartyConfig.create(
    party_name="Test Party",
    campaign="Test Campaign",
    dm_name="Alice",
    players=[
        {
            "name": "Bob",
            "voice": "Male, mid pitch",
            "characters": [
                {"name": "Thorin", "class": "Fighter", "race": "Dwarf"}
            ]
        },
        {
            "name": "Charlie",
            "characters": [
                {"name": "Elara", "class": "Wizard", "race": "Elf"}
            ]
        }
    ]
)

config.save("data/party_test.json")
config.validate()  # Returns errors and warnings

Speaker Mapping Preview

Before processing, preview how speakers will be mapped:

python cli.py preview-speaker-mapping --party default --session session_012

Expected Mapping (based on typical speaking order):
  SPEAKER_00 → Alice (DM)
  SPEAKER_01 → Bob (Thorin Ironfist)
  SPEAKER_02 → Charlie (Elara Moonwhisper)
  SPEAKER_03 → David (Grim Stonefist)
  SPEAKER_04 → Eve (Lyra Brightwood)

Notes:
  - Mapping is based on voice_characteristics and typical patterns
  - Actual mapping may vary based on who speaks first
  - Review output after processing for accuracy
  - Adjust voice_characteristics if mapping is incorrect

Configuration Management

Version Control

Commit party configs to git:

git add data/party_*.json
git commit -m "Add main campaign party config"
git push

Backup Configs

Before making changes:

cp data/party_default.json data/party_default.json.backup

Multiple Configs for Same Campaign

Use session ranges or naming:

party_main_sessions_1-10.json   # Original party
party_main_sessions_11-20.json  # New player joined
party_main_sessions_21-30.json  # Player left, character replaced

Or simply:

party_main_early.json
party_main_current.json

Specify during processing:

python cli.py process video.mp4 --party main_current

Advanced Validation

Schema Validation

Use JSON Schema for strict validation:

python cli.py validate-config --party default --strict

# Uses schema file: schemas/party_config_schema.json

Cross-Session Validation

Ensure config matches actual session data:

python cli.py validate-config --party default --check-session session_012

Validation Results:
  ✅ All speakers in session_012 mapped to config players
  ⚠️ SPEAKER_04 in session but only 4 players in config (expected 5 speakers)

Recommendation:
  Check if new player joined for session_012
  Update config or verify diarization didn't over-segment

Historical Validation

Check if configs match historical usage:

python cli.py validate-config --history

Party Config Usage:
  party_default.json:
    Used in: 25 sessions (session_001 to session_025)
    Speaker counts: 5 (consistent)
    Issues: None

  party_oneshot.json:
    Used in: 3 sessions (session_026, session_027, session_028)
    Speaker counts: 4, 4, 5 (inconsistent)
    Issues: Session_028 had extra speaker not in config

Recommendations:
  ⚠️ Review session_028 - possible new player or guest
  ℹ️ Consider creating party_oneshot_v2.json for future sessions

Integration with Other Skills

• session-processor: Use validated configs for session processing
• diagnostics-runner: Includes party config validation in health checks
• campaign-analyzer: Use character names from configs for knowledge extraction
• video-chunk: Validates party config before starting pipeline

Best Practices

1. Create Config Before First Session: Set up party config before processing
2. Include Voice Characteristics: Helps with speaker diarization accuracy
3. Keep Configs Updated: Add new players/characters as they join
4. Version Configs: Track changes in git for history
5. Validate After Changes: Always validate after editing configs
6. Use Descriptive Names: Name configs clearly (party_main, party_oneshot_winter)
7. Document Special Cases: Add notes for temporary players or guests
8. Backup Before Major Changes: Save backups before restructuring
9. Test with Sample Session: Process one session to verify mapping
10. Review First Output: Manually check speaker mapping is correct

Example Workflows

New Campaign Setup

User: "I'm starting a new campaign. Help me set up the party config."

Assistant uses party-validator:
1. Asks for party details (DM, players, characters)
2. Creates new config file: data/party_newcampaign.json
3. Validates structure
4. Previews speaker mapping
5. Confirms ready for session processing

Troubleshooting Bad Mapping

User: "Session 12 has wrong speaker assignments. The DM is labeled as a player."

Assistant uses party-validator:
1. Validates party config: check config is correct
2. Reviews session 12 output: check actual speaker assignments
3. Compares expected vs actual mapping
4. Identifies issue: Speaker order different than expected
5. Suggests: Update voice_characteristics or manually correct session

Config Migration

User: "We had a player change characters. Update the config."

Assistant uses party-validator:
1. Reads current config
2. Updates player's character information
3. Validates updated config
4. Creates backup of old config
5. Recommends: Specify session range for old vs new character

Future Enhancements

Potential features:

• Automatic speaker-to-player mapping based on voice analysis
• Config templates for common party sizes
• Visual config editor (web UI)
• Character progression tracking (levels, abilities)
• Session attendance tracking
• Voice sample collection for better diarization
• Integration with D&D Beyond for character import
• Multi-language support for international campaigns