Analyze Amazon Reviews

Use the bundled deterministic pipeline for paid API access, normalization, statistics, evidence validation, and HTML rendering. Use model reasoning only for the semantic analysis between preparation and rendering.

Get a Reveyes API key

1. Open Reveyes and sign in or create an account.
2. Open the 对外接口 menu in the Reveyes system.
3. Create or copy the API key shown there.
4. Store it in REVEYES_API_KEY; do not paste it into prompts, reports, or source files.

export REVEYES_API_KEY="your_api_key"

Protect credentials and points

• Read the key from REVEYES_API_KEY, an explicit --env-file, or --prompt-api-key. Never print or embed it in generated files.
• Treat a pasted chat key as exposed. Use it only when authorized and advise rotation afterward.
• Generate a plan before every new paid fetch. Show requested pages, configured points per page, and maximum estimated points.
• Require explicit point-limit confirmation before running fetch. Passing --confirm-max-points is the final execution guard.
• Prefer retrieve when the user supplies a permanent task_id. Inspect task-index.json before repeating an identical paid request.
• Interpret pre_deduct as reservation and actual_deduct as authoritative settlement. Keep points_per_page_at_plan with the run because pricing can change.

Run the workflow

Set the skill directory once:

SKILL_DIR=/absolute/path/to/analyze-amazon-reviews

1. Select the user scenario

Read scenario-routing.md, infer the closest scenario, and honor explicit filters or page counts. Default ambiguous product-health requests to health; never default to deep.

List current plans and configured costs:

python3 "$SKILL_DIR/scripts/review_pipeline.py" scenarios --points-per-page 3

2. Create a non-billable plan

python3 "$SKILL_DIR/scripts/review_pipeline.py" plan \
  --asin B08N5KWB9H \
  --marketplace US \
  --scenario health \
  --points-per-page 3 \
  --output /absolute/output/plan.json

Show the plan summary to the user. Do not submit until the point limit is explicitly accepted, unless the user already supplied the exact mode/pages and explicitly said to execute without another confirmation.

3. Fetch or reuse

Create new paid tasks:

python3 "$SKILL_DIR/scripts/review_pipeline.py" fetch \
  --plan /absolute/output/plan.json \
  --confirm-max-points 30 \
  --output-root /absolute/output/reports

Reuse a permanent task without creating a paid task:

python3 "$SKILL_DIR/scripts/review_pipeline.py" retrieve \
  --task-id TASK_ID \
  --filter-star all_stars \
  --sort-by recent \
  --known-pages 1 \
  --output-root /absolute/output/reports

Read reveyes-api.md before changing client behavior or diagnosing an API response. The client polls terminal status and explicitly paginates data.reviews beyond the API's default result page size.

4. Perform semantic analysis

Open RUN_DIR/analysis/index.json, then analyze every referenced batch. Read both:

• analysis-methodology.md for interpretation and sampling rules.
• analysis-schema.md for the required evidence-grounded JSON structure.

Use a map-reduce workflow for large runs:

1. Analyze each batch independently and save compact partial findings under RUN_DIR/analysis/partials/.
2. Merge aliases and duplicate themes across partials.
3. Write RUN_DIR/analysis/final-analysis.json.
4. Preserve exact quotes and bind every conclusion to valid review_id values.

Validate before rendering:

python3 "$SKILL_DIR/scripts/review_pipeline.py" validate-analysis --run-dir RUN_DIR

Fix all validation errors. Warnings may remain only when clearly disclosed in report limitations.

5. Render the HTML report

python3 "$SKILL_DIR/scripts/review_pipeline.py" render --run-dir RUN_DIR

The default report is one self-contained report.html with inline styles, charts, filters, and review evidence. It omits reviewer names, profile URLs, API keys, and task IDs. Add --include-media-links only when the user wants external image/video links in a shared report.

Return a clickable local file link. Upload only when the user explicitly requests publishing and specifies or authorizes a hosting destination. For private sharing, prefer signed object-storage URLs.

Enforce reporting boundaries

• Call all computed percentages and averages “sample” values.
• Do not combine equally sampled 1-to-5-star strata into a claimed product-wide star distribution.
• Do not call a reviewer fraudulent or fake. Report review-quality signals conservatively.
• Do not translate or paraphrase text inside a quote; put interpretation in a separate field.
• Distinguish recent, helpful, critical, media, and verified-purchase sampling sources.
• Normalize competitor comparisons within equivalent strata and equal page budgets.
• Treat one review as an anecdote, not a recurring issue.

Handle failures

• Stop without retrying API codes 1001 through 1005; explain the mapped error.
• Retry transient network failures and HTTP 5xx only.
• Preserve manifest.json after partial submission so permanent tasks can be resumed.
• If server-side pre_deduct implies a higher price than the plan, stop remaining submissions when the confirmed point limit would be exceeded.
• Never discard a completed task merely because local rendering or semantic analysis failed; rerun preparation or rendering from the saved run.