================================================================================
SC2 Pattern Learning System - Data Structure Reference
================================================================================

This is a concise structure-only reference. For examples and detailed explanations,
see PATTERN_LEARNING_DATA_FORMAT_GUIDE.txt

================================================================================
FILE OVERVIEW
================================================================================

data/
├── comments.json           - Player comments with game context
├── patterns.json          - Build order patterns with signatures
├── learning_stats.json    - System statistics and metadata
└── *.backup               - Automatic backup files

================================================================================
1. comments.json
================================================================================

ROOT:
{
  "comments": [CommentEntry, ...],
  "keyword_index": {
    "keyword": ["comment_id", ...]
  }
}

CommentEntry:
{
  "id": string,
  "raw_comment": string,
  "cleaned_comment": string,
  "comment": string,
  "keywords": [string, ...],
  "game_data": GameData,
  "timestamp": string,
  "has_player_comment": boolean
}

GameData:
{
  "opponent_name": string,
  "opponent_race": string,
  "result": string,
  "map": string,
  "duration": string,
  "date": string,
  "build_order": [BuildStep, ...]
}

BuildStep:
{
  "supply": number,
  "name": string,
  "time": number
}

================================================================================
2. patterns.json
================================================================================

ROOT:
{
  "pattern_001": PatternEntry,
  "pattern_002": PatternEntry,
  ...
}

PatternEntry:
{
  "signature": PatternSignature,
  "comment_id": string,
  "game_id": string,
  "keywords": [string, ...],
  "comment": string,
  "sample_count": number,
  "last_seen": string,
  "strategy_type": string,
  "race": string,
  "confidence": number,
  "game_data": GameData,
  "has_player_comment": boolean
}

PatternSignature:
{
  "early_game": [BuildStepEntry, ...],
  "key_timings": {},
  "opening_sequence": [BuildStepEntry, ...]
}

BuildStepEntry:
{
  "unit": string,
  "time": number,
  "supply": number,
  "count": number,
  "order": number
}

================================================================================
3. learning_stats.json
================================================================================

ROOT:
{
  "total_keywords": number,
  "total_patterns": number,
  "keyword_breakdown": {
    "keyword": count,
    ...
  },
  "pattern_breakdown": {
    "pattern_type": count,
    ...
  },
  "ai_learned_patterns": number,
  "expert_patterns": number,
  "last_saved": string
}

================================================================================
DATA TYPES
================================================================================

string          - Text value
number          - Numeric value (integer or float)
boolean         - true or false
[string, ...]   - Array of strings
[Type, ...]     - Array of specified type
{key: value}    - Object/dictionary
{}              - Empty object

================================================================================
FIELD DESCRIPTIONS
================================================================================

COMMENTS.JSON:
- id: Unique identifier (format: "comment_XXX")
- raw_comment: Original player input
- cleaned_comment: Processed version (no punctuation)
- comment: Backward compatibility field
- keywords: Extracted strategic terms
- game_data: Full game context
- timestamp: ISO datetime string
- has_player_comment: true = expert, false = AI

GAME DATA:
- opponent_name: Full opponent name
- opponent_race: "Protoss" | "Terran" | "Zerg" | "Random"
- result: "Victory" | "Defeat" | "Tie"
- map: Map name
- duration: "Xm Ys" format
- date: "YYYY-MM-DD HH:MM:SS" format
- build_order: Sequence of build steps

BUILD STEP:
- supply: Supply count when built
- name: Unit/building name
- time: Seconds from game start

PATTERNS.JSON:
- signature: Build order fingerprint
- comment_id: Reference to source comment
- game_id: Unique game identifier
- keywords: Associated strategic terms
- comment: Pattern description
- sample_count: Times pattern seen
- last_seen: ISO timestamp
- strategy_type: AI-classified strategy
- race: "zerg" | "terran" | "protoss" | "unknown"
- confidence: 0.0 to 1.0
- game_data: Full game context
- has_player_comment: true = expert, false = AI

PATTERN SIGNATURE:
- early_game: First 60 supply worth
- key_timings: Critical building timings (currently empty)
- opening_sequence: First 10 consolidated steps

BUILD STEP ENTRY:
- unit: Unit/building name
- time: Game time in seconds
- supply: Supply count when built
- count: Number of consecutive identical units
- order: Strategic order in sequence

LEARNING STATS.JSON:
- total_keywords: Count of unique keywords
- total_patterns: Count of unique patterns
- keyword_breakdown: Frequency map of keywords
- pattern_breakdown: Frequency map of pattern types
- ai_learned_patterns: Count of AI-generated patterns
- expert_patterns: Count of expert patterns
- last_saved: ISO timestamp of last update

================================================================================
RELATIONSHIPS
================================================================================

comments.json → patterns.json:
  pattern.comment_id → comment.id
  pattern.comment == comment.comment

comments.json → learning_stats.json:
  keyword_breakdown counts from comments.keywords
  total_keywords = unique keywords in comments

patterns.json → learning_stats.json:
  total_patterns = count of patterns
  ai_learned_patterns = patterns with has_player_comment=false
  expert_patterns = patterns with has_player_comment=true

================================================================================
VALIDATION
================================================================================

REQUIRED FIELDS:
- All root-level fields must exist
- game_data must have all fields
- build_order must have at least 1 step
- keywords array must have at least 1 keyword

VALUE CONSTRAINTS:
- opponent_name: length > 1
- result: "Victory" | "Defeat" | "Tie"
- confidence: 0.0 <= value <= 1.0
- sample_count: >= 1
- timestamp: Valid ISO 8601 format
- race: Valid race name or "unknown"

================================================================================
END OF STRUCTURE REFERENCE
================================================================================