app-review-pain-miner

Apify Actor for App Review Analysis, Sentiment Clustering, and Monetization Insights.

app-review-pain-miner turns raw app feedback into decision-ready outputs for product, growth, and revenue teams.

It extracts app review pain points, clusters complaints, scores monetization opportunities, and generates:

• summary.json (executive insights)
• roadmap.json (prioritized fixes and initiatives)
• outreach_brief.json (positioning + GTM talk tracks)
• expert_debate.json (go/no-go simulation for monetization)
• result.json (combined machine-readable payload)

Supports optional BYOK narrative polishing via openai, openrouter, gemini, groq, or none (fully heuristic mode).

Why This Actor (Apify Marketplace Value)

• Fast app review mining from JSON/JSONL/CSV, inline reviews, or web sources
• Deterministic scoring for reproducible results (great for automation)
• Revenue-first outputs (not just sentiment labels)
• Low COGS mode with provider=none
• Apify-friendly artifacts for pipelines, dashboards, and scheduled jobs

Marketplace Positioning (Conversion Copy)

One-line pitch: Turn app reviews into ranked money-making opportunities, fix priorities, and GTM messaging in one run.

Best for:

• App founders validating what to fix vs what to monetize
• Growth/PM teams turning feedback into prioritized roadmap bets
• Agencies doing recurring app audit reports for clients

Primary outcomes buyers get:

• Which complaint clusters are biggest and most expensive
• Which opportunities are most monetizable
• Whether to run monetization now (go) or fix first (no_go)
• Ready-to-use roadmap and outreach messaging artifacts

What It Does

1. Ingests reviews from inline input, local JSON/JSONL/CSV, or reviewUrls (Scrapling-based HTML/JSON scraping).
2. Normalizes and tags complaints heuristically (sync, login, notifications, billing, etc.).
3. Clusters related reviews by tag + term overlap.
4. Scores opportunities using frequency, severity, recency, monetization/churn signals, and reply-gap.
5. Runs a deterministic "market expert simulation" debate (PM / Growth / Skeptical Buyer / Operator) against the generated opportunity signals.
6. Produces summary.json, roadmap.json, outreach_brief.json, expert_debate.json, and result.json.

Project Layout

• .actor/actor.json: Apify actor metadata
• .actor/input_schema.json: Apify input schema
• src/app_review_pain_miner/: pipeline, providers, CLI, Apify entrypoint
• sample_inputs/: fast, balanced, deep presets + seed reviews
• tests/: deterministic tests and fixtures
• openspec/: requirements/architecture/contracts/qa docs

Quick Start (Local)

python -m venv .venv
. .venv/Scripts/activate
pip install -e .[dev]
python scripts/test.py
python scripts/run_actor.py --input sample_inputs/fast.json --print-summary

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
python scripts/test.py
python scripts/run_actor.py --input sample_inputs\fast.json --print-summary

Apify Runtime Entry

The Docker image runs:

$python -m app_review_pain_miner.actor_entrypoint

Apify outputs are written to Key-Value Store keys:

• SUMMARY
• ROADMAP
• OUTREACH_BRIEF
• RESULT
• OUTPUT_PATHS

And a summary dataset item is pushed via Actor.push_data().

SEO / Discovery Keywords

Apify actor, app review scraper, app review analysis, app store review mining, sentiment analysis, complaint clustering, user feedback analysis, product research automation, churn risk detection, monetization opportunity scoring, growth research, review intelligence.

Recommended Apify Listing Snippets

Short description (<= 200 chars): Analyze app reviews into pain clusters, opportunity scores, roadmap actions, and monetization go/no-go insights.

Tags to use in Apify listing: app-reviews, sentiment-analysis, product-research, feedback-analysis, growth, monetization, market-intelligence

Input Notes

Minimal local input:

{
  "provider": "none",
  "reviewsFile": "sample_inputs/reviews_seed.json"
}

Optional LLM narrative polishing (BYOK):

{
  "provider": "openrouter",
  "providerApiKeyEnvVar": "OPENROUTER_API_KEY",
  "fallbackToHeuristics": true,
  "reviewsFile": "sample_inputs/reviews_seed.json"
}

reviewUrls scraping expects CSS selectors (container + text selector minimum). It can also ingest JSON endpoints if the response body is JSON and contains a list or reviews/data/items.

Provider Abstraction (BYOK)

Supported providers:

• none (default; no paid AI)
• openai
• openrouter
• gemini
• groq

Environment variables (default lookup):

• OPENAI_API_KEY
• OPENROUTER_API_KEY
• GEMINI_API_KEY
• GROQ_API_KEY

If fallbackToHeuristics=true (default), the actor still completes even when the key is missing or the provider request fails.

Output Files

Generated under outputDir:

• summary.json: executive summary + ranked opportunities + cluster rows
• roadmap.json: now/next/later initiatives with owners and metrics
• outreach_brief.json: positioning, segments, talk tracks, CS playbook
• expert_debate.json: deterministic multi-persona value debate with arguments, risks, confidence, verdict, and next monetization experiments
• result.json: combined payload (+ raw reviews optionally)

result.json also includes meta.artifactPaths.expertDebate so downstream systems can locate the debate artifact.

Interpreting expert_debate.json

• personas: simulated stakeholder viewpoints with stance, confidence, and pro/con arguments.
• confidenceScores.evidenceStrength: how strong the review evidence is (sample size, coverage, cluster confidence).
• finalVerdict.verdict:
  • go = run a controlled monetization experiment (usually with explicit conditions/guardrails)
  • no_go = fix/measure first before pricing or packaging tests
• finalVerdict.conditions: prerequisites that should gate the experiment.
• recommendedNextMonetizationExperiments: deterministic test ideas generated from the top pain clusters/tags.

COGS / Pricing Notes

Heuristic mode (provider=none):

• Primary cost drivers are CPU time and network requests.
• No LLM/token spend.
• Best default for large backfills, competitive scans, and nightly monitoring.

BYOK narrative mode:

• Deterministic clustering/scoring remains local and cheap.
• LLM call is only used to rewrite/refine narrative sections, so token usage is bounded.
• Typical token footprint is proportional to number of top clusters included in AI context (default top 6).

Suggested pricing approach (for a hosted actor):

• Starter: heuristic-only, capped reviews/run
• Growth: heuristic + optional BYOK narrative
• Pro: larger review caps + scheduled runs + raw review exports

Price by review volume + source complexity (HTML scraping vs provided JSON), not only by runtime.

Legal / Compliance Notes

• Respect site Terms of Service and robots.txt before scraping review pages.
• Some app stores prohibit automated scraping or require official APIs/feeds; verify permissions for each source.
• Review text may contain personal data. Avoid storing PII unless necessary; redact before downstream sharing.
• BYOK LLM mode sends summarized cluster context (not full raw review corpora unless you modify the code). Review your provider’s retention and data-processing policies.
• If using this for competitive intelligence, ensure your jurisdiction and contracts allow the collection/use of third-party review data.

Make / Scripts

• make lint -> python scripts/lint.py
• make test -> python scripts/test.py
• make run -> python scripts/run_actor.py --input sample_inputs/fast.json --output-dir output

Deterministic Tests

The test suite uses fixture reviews in tests/fixtures/reviews_fixture.json and validates:

• config parsing and mode caps
• ingestion/sorting/dedup
• provider fallback behavior
• expert debate simulation structure + verdict metadata
• artifact generation and file outputs (including expert_debate.json)

Run:

$python scripts/test.py

Architecture & Workflow Diagrams

1) End-to-End System Flow

flowchart LR
    A[Input Sources\nInline/JSON/JSONL/CSV/reviewUrls] --> B[Ingestion + Cleaning]
    B --> C[Deduplication + Normalization]
    C --> D[Feature Extraction\nSeverity/Tags/Recency]
    D --> E[Clustering + Opportunity Scoring]
    E --> F[Summary + Roadmap + Outreach]
    F --> G[Expert Debate Simulation\nGo/No-Go]
    G --> H[Artifacts\nsummary/roadmap/outreach/expert_debate/result]

2) Revenue Decision Pipeline

flowchart TD
    A[Raw Feedback] --> B[Pain Cluster Detection]
    B --> C[Opportunity Scores]
    C --> D{Go Score >= Threshold?}
    D -- Yes --> E[Run Monetization Experiment]
    D -- No --> F[Fix Reliability + CS Gaps]
    E --> G[Track Conversion + Refund + Retention]
    F --> H[Re-run Actor]
    H --> D

3) Artifact Dependency Graph

graph TD
    A[result.json]
    B[summary.json]
    C[roadmap.json]
    D[outreach_brief.json]
    E[expert_debate.json]

    B --> A
    C --> A
    D --> A
    E --> A

4) Opportunity Score Components (Conceptual)

flowchart LR
    A[Frequency] --> Z[Opportunity Score]
    B[Severity] --> Z
    C[Recency] --> Z
    D[Churn Risk] --> Z
    E[Monetization Signal] --> Z
    F[Reply Gap] --> Z
    G[Confidence] --> Z

5) Live-Source Cleaning Pipeline

flowchart LR
    A[Raw Issue/Review Text] --> B[Template Header Removal]
    B --> C[Checklist/Boilerplate Strip]
    C --> D[Link/Image/URL Cleanup]
    D --> E[Section Pruning\nDevice/Version/Debug Blocks]
    E --> F[Normalized Text]
    F --> G[Content-Aware Dedup]

6) Apify Runtime Outputs

flowchart TD
    A[Actor Run] --> B[KV Store: SUMMARY]
    A --> C[KV Store: ROADMAP]
    A --> D[KV Store: OUTREACH_BRIEF]
    A --> E[KV Store: RESULT]
    A --> F[KV Store: OUTPUT_PATHS]
    A --> G[Dataset Item\nRun Summary + Meta]

7) Buyer Value Map

mindmap
  root((Buyer Value))
    Product Team
      Prioritized Fixes
      Clear Pain Themes
      Faster Backlog Decisions
    Growth Team
      Monetization Timing
      Messaging Angles
      Experiment Ideas
    Founder/Operator
      Revenue-Focused Signal
      Lower Analysis Time
      Repeatable Weekly Intelligence

8) Typical Weekly Operating Loop

sequenceDiagram
    participant U as User/Operator
    participant AP as Apify Scheduler
    participant AC as Actor
    participant DS as Dataset/KV

    U->>AP: Schedule weekly run
    AP->>AC: Execute with latest inputs
    AC->>AC: Ingest + Clean + Cluster + Score
    AC->>DS: Write artifacts + summary
    U->>DS: Review go/no-go + experiments
    U->>U: Execute fixes or monetization tests