# App Review Pain Miner - AI Product Intelligence from Reviews (`george.the.developer/app-review-pain-miner`) Actor

Mine app store reviews to uncover user pain points, feature requests, and sentiment. AI-powered product intelligence from real customer feedback.

- **URL**: https://apify.com/george.the.developer/app-review-pain-miner.md
- **Developed by:** [George Kioko](https://apify.com/george.the.developer) (community)
- **Categories:** AI, Marketing
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$29.00/month + usage

To use this Actor, you pay a monthly rental fee to the developer. The rent is subtracted from your prepaid usage every month.You also pay for the Apify platform usage, which gets cheaper the higher Apify subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#rental-actors

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 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)

```bash
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:

```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:

```bash
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:

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

Optional LLM narrative polishing (BYOK):

```json
{
  "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:

```bash
python scripts/test.py
```

### Architecture & Workflow Diagrams

#### 1) End-to-End System Flow

```mermaid
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

```mermaid
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

```mermaid
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)

```mermaid
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

```mermaid
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

```mermaid
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

```mermaid
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

```mermaid
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
```

# Actor input Schema

## `analysisMode` (type: `string`):

Controls review cap and clustering thresholds.

## `provider` (type: `string`):

Optional BYOK provider used only for narrative polishing.

## `model` (type: `string`):

Optional model override for the selected provider.

## `providerApiKey` (type: `string`):

Optional BYOK key. Prefer env vars for production.

## `providerApiKeyEnvVar` (type: `string`):

Environment variable name containing the API key.

## `providerBaseUrl` (type: `string`):

Optional endpoint override (advanced).

## `fallbackToHeuristics` (type: `boolean`):

If provider setup or API calls fail, still return heuristic outputs.

## `analysisDate` (type: `string`):

YYYY-MM-DD. Defaults to today (UTC). Set for deterministic backfills/tests.

## `maxReviews` (type: `integer`):

Hard cap after ingestion and dedupe.

## `minClusterSize` (type: `integer`):

Clusters smaller than this go to long tail.

## `similarityThreshold` (type: `number`):

Greedy clustering threshold.

## `outputDir` (type: `string`):

Local output directory for JSON artifacts.

## `includeRawReviews` (type: `boolean`):

Include normalized reviews in result.json (larger output).

## `reviewsFile` (type: `string`):

Local path to JSON / JSONL / CSV reviews file.

## `reviews` (type: `array`):

Inline review records. If not provided, the actor will return an error explaining that review data is required.

## `reviewUrls` (type: `array`):

Scrapling-backed source configs for scraping reviews from HTML pages.

## Actor input object example

```json
{
  "analysisMode": "balanced",
  "provider": "none",
  "providerApiKeyEnvVar": "",
  "fallbackToHeuristics": true,
  "maxReviews": 300,
  "minClusterSize": 2,
  "similarityThreshold": 0.34,
  "outputDir": "output",
  "includeRawReviews": false,
  "reviews": [
    {
      "id": "demo-001",
      "text": "The app keeps crashing when I try to sync my data. Very frustrating!",
      "rating": 1,
      "title": "Sync crashes",
      "source": "demo"
    },
    {
      "id": "demo-002",
      "text": "Login doesn't work after the latest update. Can't access my account.",
      "rating": 2,
      "title": "Login broken",
      "source": "demo"
    }
  ]
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("george.the.developer/app-review-pain-miner").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("george.the.developer/app-review-pain-miner").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call george.the.developer/app-review-pain-miner --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=george.the.developer/app-review-pain-miner",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/Dx5DM2eJkXgBGbx9Z/builds/9aAkaTg4dpjUcLo5E/openapi.json