Brainstorm: KPI tool

[MarkSpectarium]

Read issue #19 to get an understanding of what is currently being built.

Then send me proposals of what kind of analytics we could run on top of that data set with those tools to make sure we can actually use this for KPI analytics.

[MarkSpectarium]

KPI Analytics Proposals for json_genius

Based on the json_genius architecture and the Myths data structure (Player entities in live.json, PlayerCharacter entities in chars.json), here are proposed analytics we could build:

---

Tier 1: Foundation KPIs (Essential)

1. Player Census

• Total players, active vs dormant (based on last activity)
• New player acquisition over time (from deviceHistory.firstSeenAt)
• Device distribution (platforms, if available)

2. Retention Cohorts

• D1/D3/D7/D14/D30 retention from eventLog.latestSegmentEntries
• Cohort tables - players grouped by signup week, tracking retention
• Churn identification - players who haven't logged in X days

3. Character Distribution

• Characters per player (min/max/avg from characterRoster.characterIds.length)
• Class popularity - which characterClassId values are most common
• Single-character vs multi-character players

---

Tier 2: Engagement KPIs (Growth)

4. Progression Analytics

• Level distribution - histogram of character levels
• Max level by class - which classes reach endgame
• Progression velocity - levels gained over time
• Stuck points - common levels where progression stalls

5. Character Lifecycle

• Character creation funnel - players who create 1st → 2nd → 3rd characters
• Character abandonment - characters at low levels not played recently
• Main vs alt detection - which character has most activity per player

6. Session Analysis (if eventLog has session data)

• Session frequency - sessions per player per day/week
• Inter-session time - average time between sessions
• Session duration (if timestamps available)

---

Tier 3: Cross-File Analytics (Advanced)

7. Player ↔ Character Joins

Using the relationship Player.characterRoster.characterIds → PlayerCharacter.id:

• Roster composition - what class combinations do players prefer?
• Power correlation - player wallet vs total character levels
• Character investment - avg levels per character by roster size

8. Behavioral Segments

• Engaged explorers - high session count, multiple characters
• Focused progressors - single high-level character
• Dormant accounts - no recent activity
• Power users - top 10% by some engagement metric

---

Tier 4: Time-Series KPIs (Trending)

9. Trend Analysis

• Weekly/monthly player growth
• Retention trend - is D7 retention improving over time?
• Class meta shifts - are certain classes becoming more popular?

10. Funnel Conversion

• If event types exist: Account Created → First Character → Level 5 → Level 10 → etc.
• Drop-off points in the player journey

---

Implementation in json_genius

These could be exposed as:

# Built-in reports
npx json-genius analyze data/LiveTest/ --report player-census
npx json-genius analyze data/LiveTest/ --report retention-cohorts
npx json-genius analyze data/LiveTest/ --report class-distribution

# Custom queries
npx json-genius query live.json \
  --select "payload.characterRoster.characterIds.length" \
  --group-by value --count

# Cross-file joins
npx json-genius query live.json chars.json \
  --join "characterRoster.characterIds → entityId" \
  --select "player.entityId, character.characterClassId"

MCP Tools for KPIs

// New MCP tools
run_kpi_report(report: 'census' | 'retention' | 'progression' | ...)
get_player_segments(segmentation: 'engagement' | 'lifecycle' | ...)
get_retention_cohorts(period: 'daily' | 'weekly', lookback: number)

---

Questions for You

1. Event log granularity: What events are in eventLog.latestSegmentEntries? This determines what session/engagement metrics are possible.

2. Timestamps available: Beyond firstSeenAt, are there lastSeenAt, sessionStarted, etc.?

3. Priority KPIs: Which of the above are most valuable for Myths' current stage? (Early stage = acquisition/retention, Later = engagement/monetization)

4. Export format: Should reports output JSON, CSV, or markdown tables for easy consumption?

[MarkSpectarium]

Refined KPI Proposal (Based on Data Analysis)

After discussing with the TD, here's a refined proposal organized by data availability in the JSON export:

---

Tier 1: Fully Available from JSON Export ✅

These use deviceHistory, stats, characterRoster, and chars.json - complete data.

KPI	Data Source	Priority
D1/D3/D7 Retention	deviceHistory.firstSeenAt vs stats.lastLoginAt	HIGH
Player Census	Count of entities in live.json	HIGH
Character Distribution	characterClassId from chars.json (Thor vs ChacChel %)	HIGH
Characters per Player	characterRoster.characterIds.length	HIGH
Level Progression	Character levels bucketed: 1-5, 6-10, 11-15, 16+	HIGH
Daily New Player Acquisition	Group by deviceHistory.firstSeenAt date	HIGH
Multi-device Players	Count of entries in deviceHistory per player	MEDIUM
Account Age Distribution	stats.createdAt to now	MEDIUM

Implementation: These match what analyze.py already does - json_genius should replicate this first.

---

Tier 2: Recent Window Only (latestSegmentEntries) ⚠️

The JSON export only includes the latest segment (~22.5 events avg). Good for snapshots, not historical trends.

KPI	Event Type	Limitation
Recent Session Count	PlayerEventClientConnected/Disconnected	Last segment only
Recent Purchases	PlayerEventShopPackagePurchase	Last segment only
Recent Dungeon Completions	PlayerEventPortalTrackDungeonCompleted	Last segment only
Recent Level-ups	PlayerEventCharacterLevelUp	Last segment only
Error Rate	PlayerEventIncidentRecorded	Last segment only
Feature Usage	PlayerEventFeatureInteraction	Last segment only

Implementation: Useful for "current state" dashboards, but warn agents about the window limitation.

---

Tier 3: Requires Full Segment Retrieval 🚫

These need historical data beyond the JSON export:

• Complete session history & session duration
• Full monetization LTV calculations
• Long-term behavioral segmentation
• Event-based retention (not just login-based)
• Conversion funnels over time

Note: Would need Metaplay's segment retrieval API, out of scope for json_genius MVP.

---

Recommended json_genius Reports

Based on data availability, prioritize these built-in reports:

# Must-have (Tier 1)
npx json-genius analyze data/LiveTest/ --report retention      # D1/D3/D7
npx json-genius analyze data/LiveTest/ --report player-census  # Counts
npx json-genius analyze data/LiveTest/ --report class-dist     # Thor vs ChacChel
npx json-genius analyze data/LiveTest/ --report progression    # Level buckets

# Nice-to-have (Tier 2 with caveats)
npx json-genius analyze data/LiveTest/ --report recent-activity  # Last segment events

---

MCP Tools (Updated)

// Tier 1 - Full data available
run_retention_report(periods: number[])  // [1, 3, 7] for D1/D3/D7
get_player_census()
get_class_distribution()
get_level_buckets(buckets: number[][])  // [[1,5], [6,10], [11,15], [16,99]]
get_daily_acquisitions(days: number)

// Tier 2 - Recent window, with warnings
get_recent_events(type?: string)  // Returns with "window limited" metadata
get_recent_session_count()

---

This aligns json_genius KPIs with what's actually achievable from the JSON export. Ready to proceed with implementation once issue #19 infrastructure is in place.