KcDAI

KcDAI is a TypeScript skill-based analysis pipeline for multi-platform gaming analytics.
It supports Steam, iOS, and Android platforms, fetching game metadata, marketing analytics, attribution data, and generating comprehensive reports with cross-platform insights.

Table of Contents

• What This Repository Does
• Quick Start
• Architecture Overview
• Repository Structure
• Skills (Detailed)
• Planner as an Agent
• Execution Flow Example
• Configuration
• Example Output (Shape)
• Roadmap
• Contributing
• License

What This Repository Does

Given a game name and platform (for example, Hades on Steam or Jurassic World Alive on iOS), this project:

Steam Platform Analysis

1. Resolves the Steam app ID
2. Fetches Steam app details
3. Fetches recent Steam user reviews
4. Infers marketing/pricing strategy
5. Computes sentiment statistics from review text

Mobile Platform Analysis (iOS/Android)

1. Fetches attribution data from AppsFlyer
2. Retrieves campaign performance from Meta Ads
3. Analyzes Unity Ads monetization and ROAS
4. Processes SKAdNetwork postbacks (iOS)
5. Performs cross-platform attribution analysis
6. Generates marketing optimization recommendations

Cross-Platform Intelligence

• Compares performance across platforms
• Analyzes attribution overlap
• Optimizes budget allocation
• Provides actionable marketing insights

6. Produces a comprehensive JSON report with platform-specific recommendations

Quick Start

Prerequisites

• Node.js 18+ (or newer)
• npm

Install dependencies

npm install

Run

# Steam game analysis
npm run dev -- "Hades"

# iOS game marketing analysis
npm run dev -- "Jurassic World Alive sur ios"

# Android attribution analysis  
npm run dev -- "Pokemon GO attribution sur android"

# Cross-platform marketing report
npm run dev -- "Clash Royale market analysis sur ios attribution_analysis"

If no game is provided, the app defaults to Hades on Steam.

Architecture Overview

The project uses a lightweight agent-like pipeline:

• Planner (src/planner.ts): produces a plan (ordered skill steps).
  • Uses an LLM-based planner if OPENAI_API_KEY is available.
  • Falls back to a safe default deterministic plan.
  • Sanitizes LLM output against an allowlist of skills.
• Executor (src/executor.ts): runs the plan asynchronously step by step.
  • Merges each skill output into a shared context object.
  • Logs start/success/failure with timings per skill.
• Registry (src/registry.ts): stores available skills and resolves them by name.
• Skills (src/skills/*.ts): concrete handlers that do the actual work.

In short: createPlan(...) -> executePlan(...) -> final report.

flowchart TD
    %% Input and Planning
    CLI[CLI Input: game name] --> Planner[Planner: createPlan]
    Planner -->|LLM or Default| Executor[Executor: executePlan]
    
    %% Skill Execution Flow
    Executor --> AppID[fetch_steam_app_id]
    AppID -->|appId| Details[fetch_steam_details]
    AppID -->|appId| Reviews[fetch_steam_reviews]
    
    Details -->|details| Marketing[analyze_marketing]
    Reviews -->|steamReviews| Sentiment[analyze_review_sentiment]
    
    Marketing -->|marketing| Report[generate_report]
    Sentiment -->|reviewSentiment| Report
    Details -->|details| Report
    AppID -->|appId| Report
    
    Report -->|report| Format[format_response]
    Format -->|responseText| Output[Final JSON Output]
    
    %% Context Flow
    Context[Shared Execution Context] -.->|merges results| AppID
    Context -.->|merges results| Details
    Context -.->|merges results| Reviews
    Context -.->|merges results| Marketing
    Context -.->|merges results| Sentiment
    Context -.->|merges results| Report
    Context -.->|merges results| Format
    
    %% Styling
    classDef input fill:#e1f5fe
    classDef planning fill:#f3e5f5
    classDef execution fill:#e8f5e8
    classDef steam fill:#fff3e0
    classDef analysis fill:#fce4ec
    classDef output fill:#f1f8e9
    
    class CLI input
    class Planner,Executor planning
    class AppID,Details,Reviews execution
    class Marketing,Sentiment analysis
    class Report,Format,Output output

Loading

Repository Structure

• src/index.ts - entrypoint, loads skills, calls planner + executor
• src/planner.ts - LLM-backed plan generation + fallback + validation
• src/executor.ts - async pipeline execution with logging
• src/registry.ts - skill registration and lookup
• src/types.ts - core plan/step types
• src/nlp.ts - natural language processing for platform/intent detection
• src/dag.ts - DAG representation of skill dependencies and execution flow
• src/skills/steam.ts - Steam data fetching skills
• src/skills/analysis.ts - marketing + sentiment + report skills
• src/skills/marketing-analytics.ts - AppsFlyer, Meta, Unity, SKAdNetwork skills
• src/skills/cross-platform.ts - Cross-platform analysis and optimization

Skills (Detailed)

Steam skills (src/skills/steam.ts)

• fetch_steam_app_id

  • Input: { game, platform }
  • Output: { appId }
  • Note: currently uses a small hardcoded mapping (extend as needed).

• fetch_steam_details

  • Input: { appId }
  • Calls: https://store.steampowered.com/api/appdetails
  • Output: { details }

• fetch_steam_reviews

  • Input: { appId }
  • Calls: https://store.steampowered.com/appreviews/{appId}
  • Params include json=1, filter=recent, language=english, num_per_page=50
  • Output:
    • steamReviews.query_summary
    • steamReviews.reviews as { text, voted_up }[]

Marketing Analytics skills (src/skills/marketing-analytics.ts)

AppsFlyer Integration

• fetch_appsflyer_conversions

  • Input: { game, platform }
  • Output: { appsflyerConversions } with install data
  • Requires: APPSFLYER_API_KEY, APPSFLYER_APP_ID

• fetch_appsflyer_campaigns

  • Input: { game, platform }
  • Output: { appsflyerCampaigns } with performance metrics
  • Requires: APPSFLYER_API_KEY, APPSFLYER_APP_ID

Meta Ads Integration

• fetch_meta_campaigns

  • Input: { game, platform }
  • Output: { metaCampaigns } with campaign data
  • Requires: META_ACCESS_TOKEN, META_AD_ACCOUNT_ID

• fetch_meta_ad_performance

  • Input: { metaCampaigns }
  • Output: { metaAdPerformance } with insights and metrics

Unity Ads Integration

• fetch_unity_monetization_stats

  • Input: { game, platform }
  • Output: { unityMonetization } with revenue data
  • Requires: UNITY_API_KEY, UNITY_ORGANIZATION_ID

• analyze_unity_roas

  • Input: { unityMonetization, appsflyerCampaigns }
  • Output: { unityRoasAnalysis } with ROI calculations

SKAdNetwork Integration (iOS)

• fetch_skadnetwork_postbacks

  • Input: { game, platform }
  • Output: { skadnetworkPostbacks } with attribution data

• analyze_skadnetwork_conversion_value

  • Input: { skadnetworkPostbacks }
  • Output: { skadnetworkAnalysis } with engagement insights

Cross-Platform skills (src/skills/cross-platform.ts)

• compare_platform_performance

  • Input: Multiple platform data sources
  • Output: { platformComparison } with cross-platform metrics

• analyze_attribution_overlap

  • Input: Attribution data from multiple sources
  • Output: { attributionOverlap } with deduplication insights

• optimize_cross_platform_roi

  • Input: Performance and attribution data
  • Output: { crossPlatformOptimization } with budget recommendations

• generate_marketing_report

  • Input: All marketing analytics data
  • Output: { marketingReport } with comprehensive insights

Analysis skills (src/skills/analysis.ts)

• analyze_marketing

  • Input: { details }
  • Logic: inspects price and discount
  • Output: marketing object (pricing_strategy, price)

• analyze_review_sentiment

  • Input: { steamReviews }
  • Uses sentiment
  • Output:
    • reviewSentiment.avgScore
    • reviewSentiment.distribution (positive, negative, neutral)
    • reviewSentiment.agreementWithVotes
    • reviewSentiment.sample_size

• generate_report

  • Input: context built by prior steps
  • Output: final report object with platform-specific insights

Planner as an Agent

src/planner.ts acts like a planning agent:

• It asks an LLM to produce JSON plan steps.
• It accepts only allowed skill names.
• It enforces required constraints:
  • fetch_steam_app_id included first (with { game })
  • generate_report included as final output step
• If LLM output is invalid or unavailable, it falls back to the default static plan.

This gives flexibility without sacrificing reliability.

Execution Flow Example

Default plan order:

1. fetch_steam_app_id
2. fetch_steam_details
3. fetch_steam_reviews
4. analyze_marketing
5. analyze_review_sentiment
6. generate_report

Each step receives the current context and returns partial results that are merged into context.

Configuration

LLM Planner

• OPENAI_API_KEY - required to enable LLM planning
• PLANNER_MODEL - optional (default: gpt-4o-mini)

If OPENAI_API_KEY is missing, planning remains deterministic.

Marketing Analytics APIs

AppsFlyer (Free Tier - 12,000 conversions)

• APPSFLYER_API_KEY - AppsFlyer API key
• APPSFLYER_APP_ID - Your app ID

Meta Ads (Free Developer Access)

• META_ACCESS_TOKEN - Facebook Graph API access token
• META_AD_ACCOUNT_ID - Your ad account ID

Unity Ads (Free API Access)

• UNITY_API_KEY - Unity Cloud API key
• UNITY_ORGANIZATION_ID - Your Unity organization ID

Example (PowerShell)

# LLM Planning
$env:OPENAI_API_KEY="your_key_here"
$env:PLANNER_MODEL="gpt-4o-mini"

# Marketing APIs
$env:APPSFLYER_API_KEY="your_appsflyer_key"
$env:APPSFLYER_APP_ID="your_app_id"
$env:META_ACCESS_TOKEN="your_meta_token"
$env:META_AD_ACCOUNT_ID="your_ad_account_id"
$env:UNITY_API_KEY="your_unity_key"
$env:UNITY_ORGANIZATION_ID="your_org_id"

npm run dev -- "Jurassic World Alive sur ios attribution_analysis"

Example Output (Shape)

Steam Analysis Output

The final JSON includes keys like:

• game
• platform
• appId
• details
• steamReviews
• marketing
• reviewSentiment
• report

Mobile Marketing Analysis Output

For mobile platforms, additional keys include:

• appsflyerConversions
• appsflyerCampaigns
• metaCampaigns
• metaAdPerformance
• unityMonetization
• unityRoasAnalysis
• skadnetworkPostbacks
• skadnetworkAnalysis
• platformComparison
• attributionOverlap
• crossPlatformOptimization
• marketingReport

report is the concise, user-facing summary of the analysis, while marketingReport provides comprehensive marketing insights for mobile platforms.

Roadmap

Steam Platform

• Replace hardcoded game -> appId mapping with Steam search lookup
• Add review pagination support for larger sentiment samples
• Provide output filtering to avoid printing very large details blobs

Mobile Platforms

• Add App Store and Google Play Store API integration
• Implement real-time SKAdNetwork postback processing
• Add more ad networks (AdMob, ironSource, etc.)

Cross-Platform Features

• Add unified dashboard for multi-platform monitoring
• Implement predictive analytics for campaign optimization
• Add automated budget allocation recommendations

Infrastructure

• Add tests for planner sanitization and skill outputs
• Add optional structured logger transport (JSON logs)
• Implement caching for API responses
• Add rate limiting and retry logic for external APIs

Contributing

Contributions are welcome.

1. Fork the repo
2. Create a branch (feat/your-feature)
3. Commit your changes
4. Open a pull request with a clear description and test notes

If you add a new skill, please update:

• src/skills/* with registration
• planner allowlist/default plan in src/planner.ts
• DAG dependencies in src/dag.ts
• this README skill list

Adding New Marketing APIs

When adding new marketing platforms:

1. Create API integration skills in src/skills/marketing-analytics.ts
2. Add platform-specific analysis in src/skills/cross-platform.ts
3. Update NLP parsing in src/nlp.ts for platform detection
4. Add environment variables documentation to Configuration section
5. Update DAG with new dependencies

License

This project is licensed under the MIT License. See the LICENSE file for details.