Henk Nie

Amazon Sales Estimator

Skill

Amazon sales volume estimator for sellers and product researchers. Estimate monthly sales and revenue from BSR (Best Seller Rank), ASIN, or keyword. Three mo...

---
name: amazon-sales-estimator
description: "Amazon sales volume estimator for sellers and product researchers. Estimate monthly sales and revenue from BSR (Best Seller Rank), ASIN, or keyword. Three modes: (A) BSR Calculator — input BSR + marketplace + price + category to get instant sales estimate, (B) ASIN Lookup — input ASIN to auto-fetch data and estimate sales, (C) Keyword Market Analysis — input keyword to analyze total market size and competition. Works on 12 Amazon marketplaces. No API key required. Use when: (1) estimating how many units a product sells per month, (2) sizing a market or niche opportunity, (3) analyzing competitor sales performance, (4) comparing sales across price points, (5) identifying top sellers vs long-tail distribution."
metadata: {"nexscope":{"emoji":"📊","category":"amazon"}}
---

# Amazon Sales Estimator 📊

Estimate monthly sales from BSR, analyze market size, and benchmark competitor performance. No API key — works out of the box.

## Installation

```bash
npx skills add nexscope-ai/Amazon-Skills --skill amazon-sales-estimator -g
```

## Three Modes

| Mode | When to Use | Input | Output |
|------|-------------|-------|--------|
| **A — BSR Calculator** | Quick estimate from known BSR | BSR + Marketplace + Price + Category | Monthly units, monthly revenue |
| **B — ASIN Lookup** | Estimate sales for a specific product | ASIN or product URL | Auto-fetch data + sales estimate |
| **C — Keyword Market Analysis** | Size a niche opportunity | Keyword (+ optional marketplace) | Total market sales, top sellers, price distribution |

## Capabilities

- **BSR-to-sales conversion**: Estimate monthly unit sales from Best Seller Rank using category-specific formulas
- **Revenue calculation**: Monthly sales × price = estimated monthly revenue
- **Market sizing**: Aggregate sales across products in a keyword search
- **Price band analysis**: Distribution of sales across price ranges
- **Competition breakdown**: Top sellers vs long-tail distribution
- **Multi-marketplace**: US, UK, DE, FR, IT, ES, JP, CA, AU, IN, MX, BR

## Handling Incomplete Input

If the user's intent is unclear or information is missing, guide them with all options and required inputs upfront:

**User says:** `"Help me estimate Amazon sales"` or `"I want to check sales"`

**Agent should respond:**

> I can help you estimate Amazon sales in 3 ways. Pick one and provide the required info:
>
> **A. BSR Calculator** — Quick estimate from BSR number
> - BSR (required): e.g., 1500
> - Category (required): e.g., Home & Kitchen
> - Price (required): e.g., $24.99
> - Marketplace (optional, default US)
>
> **B. ASIN Lookup** — Check sales for a specific product
> - ASIN or URL (required): e.g., B09V3KXJPB
> - Marketplace (optional, default US)
>
> **C. Market Analysis** — Size a keyword/niche opportunity
> - Keyword (required): e.g., "yoga mat"
> - Marketplace (optional, default US)
> - Filters (optional): price range, min reviews
>
> Example: "Mode A: BSR 1500, Home & Kitchen, $24.99" or "Mode B: B09V3KXJPB"

---

## Mode A — BSR Calculator

### Input

| Field | Required | Description | Example |
|-------|----------|-------------|---------|
| **BSR** | ✅ | Best Seller Rank number | 1500 |
| **Marketplace** | ✅ | Amazon site | US, UK, DE, JP... |
| **List Price** | ✅ | Product price | $24.99 |
| **Category** | ✅ | Product category | Home & Kitchen |

### Usage Examples

```
Estimate sales for BSR 1500 in Home & Kitchen on Amazon US, price $24.99
```

```
BSR 500, category Electronics, marketplace DE, price €39.99
```

```
What's the monthly sales for a product ranked #10,000 in Sports & Outdoors at $15.99?
```

### Workflow

1. **Receive input**: BSR, Category, Price, Marketplace
2. **Look up base sales**: Use BSR-to-sales reference table for the marketplace
3. **Apply category multiplier**: Adjust based on category (Electronics 1.2x, Clothing 0.8x, etc.)
4. **Calculate monthly units**: Base sales × category multiplier
5. **Calculate revenue**: Monthly units × price
6. **Output results**: Monthly units, daily units, monthly revenue

### Output

```
# 📊 Sales Estimate

**Input:**
- BSR: #1,500 in Home & Kitchen
- Marketplace: Amazon US
- Price: $24.99

**Results:**

| Metric | Estimate |
|--------|----------|
| **Est. Monthly Units** | ~450 units |
| **Est. Monthly Revenue** | ~$11,246 |
| **Est. Daily Units** | ~15 units |

*Estimate based on BSR-to-sales conversion formula for the selected category and marketplace.*
```

---

## Mode B — ASIN Lookup

### Input

| Field | Required | Description | Example |
|-------|----------|-------------|---------|
| **ASIN** | ✅ | Amazon product ID or URL | B09V3KXJPB |
| **Marketplace** | Optional | Defaults to US | UK, DE, JP... |

### Usage Examples

```
Estimate monthly sales for ASIN B09V3KXJPB
```

```
How many units does this sell? https://www.amazon.com/dp/B0D72TSM62
```

```
Get sales estimate for B0CPY1GFVZ on Amazon DE
```

### Workflow

1. **Fetch product data** using `web_fetch` on Amazon product page
2. **Extract**: Title, Price, BSR, Category, Rating, Reviews
3. **Apply BSR-to-sales formula** for the category and marketplace
4. **Calculate revenue**: Monthly units × Price

### Output

```
# 📊 Sales Estimate: B09V3KXJPB

## Product Info
- **Title:** [Product Title]
- **Price:** $24.99
- **BSR:** #1,500 in Home & Kitchen
- **Rating:** 4.5★ (1,234 reviews)

## Sales Estimate

| Metric | Estimate |
|--------|----------|
| **Est. Monthly Units** | ~450 units |
| **Est. Monthly Revenue** | ~$11,246 |
| **Est. Daily Units** | ~15 units |

## Competitive Context
- Ranks in **top 0.5%** of Home & Kitchen category
- Above average for $20-30 price range
```

---

## Mode C — Keyword Market Analysis

### Input

| Field | Required | Description | Example |
|-------|----------|-------------|---------|
| **Keyword** | ✅ | Search term | yoga mat |
| **Marketplace** | Optional | Amazon site (default: US) | UK, DE, JP... |
| **Filters** | Optional | Price range, min reviews | $15-$40, 100+ reviews |

### Usage Examples

```
Analyze the market size for "yoga mat" on Amazon US
```

```
What's the total monthly sales for "portable blender" keyword?
```

```
Size the "dog shirt" market on Amazon US. Show top sellers and price distribution.
```

### Workflow

1. **Search products** using `web_search` for `site:amazon.com "{keyword}"`
2. **Fetch top 10-20 product pages** to get BSR data
3. **Estimate sales for each product** using Mode A formula
4. **Aggregate** total market size
5. **Analyze** price distribution and competition

### Output

```
# 📊 Market Analysis: "yoga mat"

**Marketplace:** Amazon US | **Products Analyzed:** 25

## Market Size

| Metric | Value |
|--------|-------|
| **Est. Total Monthly Units** | ~85,000 units |
| **Est. Total Monthly Revenue** | ~$2.1M |
| **Average Price** | $24.50 |

## Top 5 Sellers

| # | ASIN | Price | BSR | Est. Units/Mo |
|---|------|-------|-----|---------------|
| 1 | B0XX... | $22.99 | #45 | ~8,500 |
| 2 | B0YY... | $29.99 | #78 | ~6,200 |
| 3 | B0ZZ... | $18.99 | #120 | ~4,800 |
| ... | ... | ... | ... | ... |

## Market Concentration

- **Top 3:** 23% of total sales
- **Top 10:** 52% of total sales
- **Long tail:** 48% of total sales

→ **Fragmented market** — opportunity for new entrants

## Price Distribution

| Price Band | % of Sales |
|------------|------------|
| $0 - $20 | 25% |
| $20 - $35 | 55% |
| $35+ | 20% |

**Sweet spot:** $20-$35
```

---

## BSR-to-Sales Reference

### Amazon US — Baseline (Home & Kitchen)

| BSR Range | Est. Monthly Sales |
|-----------|-------------------|
| 1-100 | 3,000 - 10,000+ |
| 100-500 | 1,000 - 3,000 |
| 500-2,000 | 300 - 1,000 |
| 2,000-10,000 | 100 - 300 |
| 10,000-50,000 | 30 - 100 |
| 50,000-100,000 | 10 - 30 |
| 100,000+ | < 10 |

### Category Multipliers

| Category | Multiplier |
|----------|------------|
| Electronics | 1.2x |
| Home & Kitchen | 1.0x |
| Toys | 1.1x |
| Sports & Outdoors | 0.9x |
| Clothing | 0.8x |
| Books | 0.7x |

### Marketplace Adjustments

| Marketplace | Factor |
|-------------|--------|
| US | 1.0x |
| JP | 0.6x |
| DE | 0.5x |
| UK | 0.4x |
| CA | 0.3x |
| Others | 0.2x |

---

## Integration with Other Skills

This skill works well when chained with other skills from the [Nexscope Amazon-Skills](https://github.com/nexscope-ai/Amazon-Skills) and [eCommerce-Skills](https://github.com/nexscope-ai/eCommerce-Skills) repositories.

### With amazon-keyword-research

```bash
npx skills add nexscope-ai/Amazon-Skills --skill amazon-keyword-research -g
```

```
Step 1: "Research keywords for yoga mat"
   → amazon-keyword-research returns keyword list with search volumes

Step 2: "Now analyze the market size for the top keyword"
   → amazon-sales-estimator Mode C sizes the opportunity
```

### With amazon-listing-optimization

```bash
npx skills add nexscope-ai/Amazon-Skills --skill amazon-listing-optimization -g
```

```
Step 1: "Estimate sales for competitors: B0ABC, B0XYZ"
   → amazon-sales-estimator Mode B provides benchmark data

Step 2: "Create a listing to beat those competitors"
   → amazon-listing-optimization generates optimized copy
```

### With amazon-ppc-campaign

```bash
npx skills add nexscope-ai/Amazon-Skills --skill amazon-ppc-campaign -g
```

```
Step 1: "Estimate my product's monthly sales"
   → amazon-sales-estimator provides revenue baseline

Step 2: "Build PPC campaigns with 30% ACoS target"
   → amazon-ppc-campaign calculates bids based on your revenue data
```

### More Skills

Browse all available skills:
- **Amazon Skills:** https://github.com/nexscope-ai/Amazon-Skills
- **eCommerce Skills:** https://github.com/nexscope-ai/eCommerce-Skills

---

## Limitations

This skill uses publicly available data from Amazon product pages. It cannot access historical BSR data, actual seller sales figures, or PPC conversion metrics. For deeper analytics and historical trends, check out **[Nexscope](https://www.nexscope.ai/)** — Your AI Assistant for smarter E-commerce decisions.

---

**Built by [Nexscope](https://www.nexscope.ai/)** — research, validate, and act on e-commerce opportunities with AI.

Amazon Ppc Campaign

Skill

Amazon PPC campaign builder and optimizer for sellers. Two modes: (A) Build — design a complete campaign structure from scratch with keyword groupings, bid c...

---
name: amazon-ppc-campaign
description: "Amazon PPC campaign builder and optimizer for sellers. Two modes: (A) Build — design a complete campaign structure from scratch with keyword groupings, bid calculations, and negative keyword lists, (B) Optimize — audit existing campaigns using search term reports, identify keyword funnel opportunities, calculate bid adjustments, and generate a week-by-week action plan. Integrates with amazon-keyword-research for keyword input. No API key required. Use when: (1) setting up Amazon PPC campaigns for a new product, (2) auditing existing campaign performance and ACoS, (3) optimizing keyword bids and negative keywords, (4) building Auto/Manual/Exact campaign structures, (5) analyzing search term reports for opportunities, (6) calculating break-even ACoS and target ACoS, (7) scaling profitable campaigns to Sponsored Brands or Display."
metadata: {"nexscope":{"emoji":"📢","category":"amazon"}}
---

# Amazon PPC Campaign Optimization 📢

Build profitable PPC campaign structures from scratch, or audit and optimize existing campaigns with data-driven bid adjustments. No API key — works out of the box.

## Installation

```bash
npx skills add nexscope-ai/Amazon-Skills --skill amazon-ppc -g
```

## Two Modes

| Mode | When to Use | Input | Output |
|------|-------------|-------|--------|
| **A — Build** | Launching PPC for a new product | Product info + keywords + margins | Complete campaign blueprint + keyword groupings + initial bids |
| **B — Optimize** | Improving existing campaigns | Campaign data + search term reports + current ACoS | Optimization plan + bid adjustments + negative keyword list |

## Capabilities

- **ACoS financial framework**: Calculate break-even ACoS, target ACoS, and Max CPC from product margins — the foundation for every bid decision
- **Campaign architecture design**: Build a structured Auto → Broad → Exact funnel with proper negative keyword isolation between campaigns
- **Keyword grouping**: Organize keywords into campaign buckets with match types and initial bids based on confidence level
- **Bid optimization**: Apply ACoS-based bid adjustment rules using industry-standard formulas (cut/increase by percentage based on ACoS range)
- **Keyword funnel analysis**: Identify migration opportunities (Auto→Broad→Exact) and wasted spend (high-click zero-sale terms)
- **Negative keyword management**: Generate seed lists (cross-campaign, irrelevant terms, generic waste modifiers) and ongoing additions from search term data
- **Search term report analysis**: Parse user-provided campaign data to find profitable terms, wasteful terms, and optimization gaps
- **Competitor ASIN targeting**: Build product targeting campaigns aimed at competitor product pages
- **Integration chain**: Works with [amazon-keyword-research](https://github.com/nexscope-ai/Amazon-Skills/tree/main/amazon-keyword-research) for keyword input and [amazon-listing-optimization](https://github.com/nexscope-ai/Amazon-Skills/tree/main/amazon-listing-optimization) for pre-launch listing quality checks

## Usage Examples

### Mode A — Build New Campaigns

```
I'm launching a portable blender on Amazon US. Price: $39.99. Product cost: $8, shipping: $3, Amazon fees: $7.50. Here are my keywords: portable blender, personal blender, smoothie maker. Build me a PPC campaign structure.
```

```
Use amazon-keyword-research to find keywords for "bamboo cutting board", then build a PPC campaign structure. Product costs $6, sells for $29.99. Brand new product launch.
```

```
I want to advertise my dog t-shirt (ASIN B0D72TSM62, price $5.99, cost $2). Look at competitors B0CMD17929 and B0B76519ZG, extract their keywords, and build my PPC campaigns.
```

### Mode B — Optimize Existing Campaigns

```
My PPC ACoS is 58% and my target is 30%. I have 3 campaigns: Auto ($800/month, ACoS 67%), Manual Broad ($1,100, ACoS 48%), Manual Exact ($500, ACoS 33%). Product margin is 54%. Help me optimize.
```

```
Here's my search term report [paste CSV data]. Break-even ACoS is 40%. Find wasted spend, tell me what to negate and what to migrate.
```

```
Weekly PPC check: here are this week's search terms with clicks and sales [data]. Add negatives for 10+ clicks with no sales, move 2+ orders to Exact.
```

### Short Prompts Work Too

```
Help me set up PPC for my product B0D72TSM62
```
```
My ACoS is too high, help me fix it
```
```
I want to start advertising on Amazon
```

---

## How This Skill Collects Information

Users rarely provide everything upfront — and they don't need to. This skill follows a **progressive information gathering** approach:

**Step 1: Extract from the prompt.** Parse whatever the user already provided — ASIN, price, ACoS numbers, campaign names, keywords, etc.

**Step 2: Auto-discover.** If an ASIN is given, run the bundled `scripts/fetch-competitor.sh <ASIN>` to get price, category, BSR, and competitor context. This script handles Amazon's anti-bot protections. If the user mentions a product type without an ASIN, use `web_search` to understand the market.

**Step 3: Identify gaps.** Compare what you have against what's needed (see the Required Information tables in Mode A Step A1 and Mode B Step B1 below). Focus on what's **critical** to proceed:
- Mode A critical: **product costs** (to calculate ACoS) + **monthly ad budget** (to size campaigns) + **keywords or competitor ASINs** (to build campaigns)
- Mode B critical: **current ACoS** + **profit margin** (to know the gap and set targets)

**Step 4: One consolidated follow-up.** Ask only for missing critical items — in one conversational message, not a questionnaire:

```
Mode A example:
"I found your product — Paiaite Dog T-Shirt, $5.99 on Amazon. To build your
campaigns, I need three things:
  1. Your product cost per unit (so I can calculate your break-even ACoS)
  2. Your monthly ad budget (so I can size the campaigns right)
  3. Any target keywords or competitor ASINs? (Or I can research for you)"

Mode B example:
"Got it — ACoS is too high. To give you specific actions, can you share:
  1. Your profit margin (or product cost, I'll calculate it)
  2. Which campaigns are running and their rough ACoS?
Search term report data is a bonus but not required to start."
```

**Step 5: Use estimates when stuck.** If the user can't provide something (e.g., doesn't know exact fees), use reasonable category-based estimates and clearly note the assumption. Never block progress waiting for perfect data.

---

## Key Concepts

Three formulas drive every recommendation in this skill. They're introduced here and applied in Step A2 (for Mode A) and Step B2 (for Mode B).

**Break-even ACoS** = Profit margin before ad spend. If your product sells for $40 with $15 in costs after Amazon fees, your margin is $25/$40 = 62.5%. At 62.5% ACoS you spend all profit on ads — break even.

**Target ACoS** = Break-even ACoS − Desired profit margin. Want 25% profit after ads? Target ACoS = 62.5% − 25% = 37.5%.

**Keyword Funnel** = The core PPC optimization loop, applied in Steps A4/A6 (building) and B3 (optimizing):
```
Auto Campaign (discover new terms)
    ↓ terms with 2+ orders
Manual Broad (test at broader match)
    ↓ terms with 2+ sales
Manual Exact (scale winners with precision)

At each step: add the migrated term as NEGATIVE in the source campaign to prevent duplicate spend.
```

---

## Mode A Workflow — Build Campaign Structure

### Step A1: Collect Product Info

The following details are needed. Many can be extracted automatically (see "How This Skill Collects Information" above) — only ask for what's truly missing.

| Detail | How to Get It | Critical? |
|--------|--------------|:---------:|
| ASIN | From user's prompt | Helpful |
| Product name and category | Fetch from ASIN or ask | Helpful |
| Selling price | Fetch from ASIN or ask | ✅ Yes |
| Product cost (landed) | Must ask user | ✅ Yes |
| Monthly ad budget | Must ask user | ✅ Yes |
| Amazon fees (referral + FBA) | Estimate ~15% referral + FBA by size | Can estimate |
| Launch vs mature product | Ask or infer from context | Helpful |

### Step A2: Calculate ACoS Targets

Using the formulas from Key Concepts, compute the financial framework that governs all bid decisions:

```
📊 PPC FINANCIAL FRAMEWORK

Selling Price:           $39.99
Total Costs:             $18.50 (product $8 + shipping $3 + Amazon fees $7.50)
Profit Before Ads:       $21.49
Profit Margin:           53.7%

Break-even ACoS:         53.7% (spending ALL profit on ads)
Target ACoS (Mature):    30.0% (keeps ~24% profit margin)
Target ACoS (Launch):    50.0% (aggressive — acceptable for first 4-8 weeks)

Max CPC at Target ACoS:  $1.20 (at 10% conversion rate)
Formula: Max CPC = Selling Price × Target ACoS × Conversion Rate
```

If user doesn't know their conversion rate, use category benchmarks: 10-15% is average.

### Step A3: Collect Keywords

Keywords can come from three sources (use one or combine):

1. **From [amazon-keyword-research](https://github.com/nexscope-ai/Amazon-Skills/tree/main/amazon-keyword-research) skill** (recommended): Run keyword research first, then feed the ranked keyword list into this skill.
2. **From competitor ASINs**: User provides 1-3 competitor ASINs → run `scripts/fetch-competitor.sh <ASIN>` for each → extract keywords from their titles and bullet points. The script returns title, brand, bullets, price, category, BSR, and review count.
3. **From user's list**: User provides their own keywords (e.g., from Helium 10, search term reports, or manual research).

Additionally, expand keywords using Amazon autocomplete: `curl -s "https://completion.amazon.com/api/2017/suggestions?mid=ATVPDKIKX0DER&alias=aps&prefix=<URL-ENCODED-KEYWORD>" | python3 -c "import sys,json; [print(s['value']) for s in json.load(sys.stdin).get('suggestions',[])]"`

### Step A4: Build Campaign Structure and Group Keywords

**Default: 4 campaigns.** This is the standard structure for a new product launch:

| Priority | Campaign | What It Does | Always Include? |
|:--------:|----------|--------------|:---------------:|
| 1 | **Auto Discovery** | Amazon auto-matches your ad to search terms — collects data on what shoppers actually search | ✅ Yes |
| 2 | **Manual Exact** | Your top 10-15 proven keywords with exact match — highest control, lowest ACoS | ✅ Yes |
| 3 | **Manual Broad** | All research keywords with broad match — discovers variations and long-tail terms | ✅ Yes |
| 4 | **Product Targeting** | Shows your ad on competitor product pages — steals their traffic | ✅ If competitor ASINs available |

**If budget is tight:** Launch Priority 1+2 first (Auto + Exact). Add Priority 3 after one week of data. Add Priority 4 when you have competitor ASINs identified.

Organize keywords into these campaign buckets:

See the **Mode A Output** template below for the exact format of keyword groupings per campaign.

### Step A5: Set Initial Bids

**Max CPC (from Step A2) is your profitability ceiling** — not your actual bid. Actual competitive bids depend on the category and keyword competition.

**How to recommend bids:**
1. Calculate Max CPC as the financial guardrail (what you can afford)
2. For actual starting bids, tell the user to check Amazon's **suggested bid range** when creating the campaign in Seller Central — this reflects real auction data
3. If Amazon's suggested bid > Max CPC, flag the gap and explain: either accept a loss (ranking launch), raise product price, or skip that keyword

**When you don't have suggested bid data**, use these category-relative starting points:
| Campaign Type | Starting Bid | Adjust After |
|--------------|-------------|-------------|
| Manual Exact | Amazon suggested bid or Max CPC (whichever is lower) | 7 days with 20+ clicks |
| Manual Broad | 70-80% of Exact bid | 7 days |
| Auto | 50-70% of Exact bid | 7 days |
| Product Targeting | 50-70% of Exact bid | 7 days |

**Important:** These are starting points. The real optimization happens after 1-2 weeks of data — adjust based on actual ACoS per keyword.

### Step A6: Build Negative Keyword Seed List

Generate an initial negative keyword list before launch. Three types:

1. **Cross-campaign negatives**: Add all Exact campaign keywords as negatives in Broad and Auto campaigns (prevents internal competition — this is the Keyword Funnel isolation from Key Concepts).
2. **Irrelevant term negatives**: Terms that share words with your product but are wrong category/intent. Example for "bamboo cutting board":
   - Wrong material: "plastic cutting board", "glass cutting board"
   - Wrong product: "cutting board oil", "cutting board stand"
   - Wrong intent: "how to clean cutting board", "cutting board DIY"
3. **Generic waste negatives**: Common low-intent modifiers: "free", "cheap", "used", "DIY", "review", "reddit", "how to"

### Step A7: Generate Campaign Blueprint

Compile everything from Steps A1-A6 into the final deliverable. Follow the **Mode A Output** template in the Output Formats section below.

---

## Mode B Workflow — Optimize Existing Campaigns

### Step B1: Collect Campaign Data

The following details are needed. Follow the same progressive gathering approach — extract from the user's prompt first, then ask for missing critical items in one follow-up (see "How This Skill Collects Information" above).

| Detail | Critical? | Notes |
|--------|:---------:|-------|
| Campaign names and types | ✅ Yes | Auto/Manual/Broad/Exact |
| Overall ACoS | ✅ Yes | And per-campaign if available |
| Monthly ad spend and ad sales | ✅ Yes | For budget efficiency analysis |
| Product profit margin | ✅ Yes | To calculate break-even ACoS |
| Top spending keywords + their ACoS | Helpful | Enables specific bid adjustments |
| Search term report (CSV) | Bonus | Enables keyword funnel analysis |
| CTR and conversion rates | Bonus | Deeper performance insights |

### Step B2: Performance Audit

Using the ACoS formulas from Key Concepts, analyze across five dimensions: (1) Financial Health — break-even vs current ACoS, monthly profit/loss; (2) Campaign Efficiency — per-campaign ACoS with 🔴🟡🟢 status; (3) Keyword Performance — group keywords by profitable/marginal/unprofitable/zero-sales; (4) Budget Allocation — is spend proportional to revenue? recommend shifts; (5) Missed Opportunities — converting terms not in Manual, high-spend zero-sale terms without negatives, underfunded winners.

### Step B3: Keyword Funnel Analysis

Apply the Keyword Funnel from Key Concepts to the user's actual data. Three actions:
- **Migrate up** (2+ orders): Auto → Exact or Broad → Exact. Add as negative in source campaign.
- **Add negatives** (10+ clicks, 0 sales): Add as negative exact or phrase in the source campaign.
- **Watch list** (<20 clicks): Not enough data yet — flag for next review cycle.

### Step B4: Bid Adjustments

Apply ACoS-based bid adjustments to keywords with 20+ clicks (minimum for statistical significance):
- ACoS > 200%: cut bid 30-50%
- ACoS 100-199%: cut bid 20%
- ACoS target+10% to 99%: cut bid 10-15%
- ACoS at target (±10%): no change
- ACoS below target: increase bid 10-20%
- 10+ clicks with 0 sales: pause keyword

Output a table: Keyword | Current Bid | Current ACoS | New Bid | Reason

### Step B5: Generate Optimization Action Plan

Compile everything from Steps B1-B4 into a prioritized action plan. Follow the **Mode B Output** template in the Output Formats section below.

---

## Output Formats

The primary deliverable is always an **actionable campaign plan** the seller can implement directly in Seller Central.

### Mode A Output — New Campaign Blueprint

```
# ✅ PPC Campaign Blueprint — Ready to Implement

## Financial Framework
Selling Price: $XX.XX | Profit Before Ads: $XX.XX | Break-even ACoS: XX%
Target ACoS (Launch): XX% | Target ACoS (Mature): XX%
Max CPC: $X.XX (at XX% conversion rate)

## How These Campaigns Work Together

Standard: 4 campaigns. If budget is tight, start P1+P2, add the rest later.

  Auto (P1) → finds new search terms        ↓ terms with 2+ orders
  Broad (P3) → tests keywords at wider match ↓ terms with 2+ sales
  Exact (P2) → best keywords, lowest ACoS
  Product Targeting (P4) → ads on competitor pages

Separate campaigns prevent internal competition (bidding against yourself).

## Campaign Setup — Follow This in Seller Central

For each campaign below, create it in Seller Central with these exact settings.
Bids marked "use suggested" mean: use Amazon's suggested bid shown during setup.
If suggested bid > your Max CPC, that keyword may not be profitable — see the
⚠️ flag in the Financial Framework for guidance.

### Campaign 1: [Product] - Auto Discovery (Priority 1)
CAMPAIGN SETTINGS:
  Campaign Name:    [Product] - Auto
  Daily Budget:     $XX
  Start Date:       [today]
  End Date:         No end date
  Bid Strategy:     Dynamic Bids - Down Only

AD GROUP:
  Ad Group Name:    Auto - Discovery
  Default Bid:      $X.XX (use suggested bid × 0.5-0.7)
  ASIN:             [your ASIN]

KEYWORDS:           None — Amazon auto-selects based on your listing

NEGATIVE KEYWORDS:
  [keyword] | Negative Exact
  [keyword] | Negative Exact
  (add all Exact campaign keywords here — prevents Auto from
   competing with Exact on the same terms)

### Campaign 2: [Product] - Manual Exact (Priority 2)
CAMPAIGN SETTINGS:
  Campaign Name:    [Product] - Exact
  Daily Budget:     $XX
  Start Date:       [today]
  End Date:         No end date
  Bid Strategy:     Fixed Bids

AD GROUP:
  Ad Group Name:    Exact - Primary
  Default Bid:      $X.XX (use suggested bid, or Max CPC if lower)
  ASIN:             [your ASIN]

KEYWORDS:
  [keyword] | Exact | $X.XX (use suggested bid)
  [keyword] | Exact | $X.XX
  [10-15 keywords, each with match type and bid]

NEGATIVE KEYWORDS:  None needed (exact match is already precise)

### Campaign 3: [Product] - Manual Broad (Priority 3)
CAMPAIGN SETTINGS:
  Campaign Name:    [Product] - Broad
  Daily Budget:     $XX
  Start Date:       [today or Week 2]
  End Date:         No end date
  Bid Strategy:     Dynamic Bids - Down Only

AD GROUP:
  Ad Group Name:    Broad - Discovery
  Default Bid:      $X.XX (use suggested bid × 0.7-0.8)
  ASIN:             [your ASIN]

KEYWORDS:
  [keyword] | Broad | $X.XX
  [keyword] | Broad | $X.XX
  [15-20 keywords]

NEGATIVE KEYWORDS:
  [keyword] | Negative Exact
  (add all Exact campaign keywords — prevents Broad from competing)

### Campaign 4: [Product] - Product Targeting (Priority 4)
CAMPAIGN SETTINGS:
  Campaign Name:    [Product] - ASIN Targeting
  Daily Budget:     $XX
  Start Date:       [today or Week 2]
  End Date:         No end date
  Bid Strategy:     Fixed Bids

AD GROUP:
  Ad Group Name:    Competitor ASINs
  Default Bid:      $X.XX (use suggested bid × 0.5-0.7)
  ASIN:             [your ASIN]

TARGETS:
  B0XXXXXXXX | [competitor name, price, reviews] | $X.XX
  B0XXXXXXXX | [competitor name, price, reviews] | $X.XX

NEGATIVE KEYWORDS:
  [your own ASIN] | Negative Exact (prevent ads on your own page)

## Negative Keyword Master List (apply to Auto + Broad + Product Targeting)
  [term] | Negative Exact     (irrelevant terms)
  [term] | Negative Phrase     (waste modifiers: free, cheap, used, DIY, etc.)

## Budget Summary
| Campaign | Priority | Daily | Monthly | Role |
|----------|:--------:|-------|---------|------|
| Auto     | P1 | $XX | $XXX | Discover search terms |
| Exact    | P2 | $XX | $XXX | Scale best keywords |
| Broad    | P3 | $XX | $XXX | Test variations |
| Product  | P4 | $XX | $XXX | Competitor pages |
| TOTAL    |    | $XX | $XXX | |

## Launch Schedule
Day 1:  Create P1 (Auto) + P2 (Exact). Check that ads are active.
Day 3:  Check impressions. If very low, your bids are below competitive
        range — increase toward Amazon's suggested bid.
Day 7:  Add P3 (Broad) + P4 (Product Targeting). Review Auto search
        terms — add obvious negatives.
Day 14: Full analysis — migrate winners (2+ orders) from Auto/Broad → Exact.
Day 21: Bid optimization — adjust bids for keywords with 20+ clicks.

---

# 📊 Campaign Design Rationale

## Keyword Sources
[How keywords were discovered — fetch-competitor.sh, autocomplete, etc.]

## Bid Notes
Max CPC (profitability ceiling): $X.XX
Amazon suggested bids for this category typically range $X.XX - $X.XX.
[Flag any keywords where suggested bid > Max CPC and explain the tradeoff]
```

### Mode B Output — Optimization Report

```
# ✅ PPC Optimization Actions — Ready to Implement

## Priority 1: Immediate Negative Keywords (Do Today)
Add these as Negative Exact in their respective campaigns:
  Campaign "[name]": "term1", "term2", "term3"
  Campaign "[name]": "term4", "term5"
Expected savings: $XXX/month

## Priority 2: Keyword Migrations (This Week)
Move to Manual Exact (and add as negative in source):
  "[keyword]" from Auto → Exact, bid: $X.XX
  "[keyword]" from Broad → Exact, bid: $X.XX

## Priority 3: Bid Adjustments (This Week)
  "[keyword]": $X.XX → $X.XX (ACoS XX% → target XX%)
  "[keyword]": $X.XX → $X.XX (increase — profitable at XX%)
  "[keyword]": PAUSE (XX clicks, 0 sales)

## Priority 4: Budget Reallocation (Next Week)
  Auto: $XX/day → $XX/day (reduce — low efficiency)
  Exact: $XX/day → $XX/day (increase — best ACoS)

---

# 📊 Full Audit Report

## Performance Summary
| Metric | Current | Target | Status |
|--------|---------|--------|--------|
| Overall ACoS | XX% | XX% | 🔴🟡🟢 |
| TACoS | XX% | <XX% | 🔴🟡🟢 |
| Monthly Ad Profit | $XXX | $XXX | 🔴🟡🟢 |
| Budget Utilization | XX% | >90% | 🔴🟡🟢 |

## Keyword Funnel Analysis
[Full table from Step B3]

## Bid Adjustment Details  
[Full table from Step B4]

## Week-by-Week Action Plan
Week 1: [specific tasks with expected outcomes]
Week 2: [specific tasks]
Week 3: [specific tasks]
Week 4: [review and next cycle planning]

## Expected Results After 4 Weeks
ACoS: XX% → XX%
Monthly savings: $XXX
Sales increase: +XX% (from better targeting)
```

---

## Ongoing Management & Integration

After setup, offer weekly reminders (cron/heartbeat): search term analysis + bid adjustments + monthly full audit. Recommended skill chain: [amazon-keyword-research](https://github.com/nexscope-ai/Amazon-Skills/tree/main/amazon-keyword-research) → [amazon-listing-optimization](https://github.com/nexscope-ai/Amazon-Skills/tree/main/amazon-listing-optimization) → amazon-ppc. Always check listing quality before spending on ads. More skills: [Amazon-Skills](https://github.com/nexscope-ai/Amazon-Skills) | [eCommerce-Skills](https://github.com/nexscope-ai/eCommerce-Skills)

## Limitations

This skill uses publicly available data and user-provided campaign reports. It cannot access Seller Central directly, pull real-time bid landscapes, or automate campaign changes via API. For deeper PPC analytics with automated bid management, check out **[Nexscope](https://www.nexscope.ai/)** — Your AI Assistant for smarter E-commerce decisions.

---

**Built by [Nexscope](https://www.nexscope.ai/)** — research, validate, and act on e-commerce opportunities with AI.
FILE:scripts/fetch-competitor.sh
#!/usr/bin/env bash
# Amazon Competitor Fetcher for PPC — extracts keywords from competitor listings
# Usage: fetch-competitor.sh <ASIN> [marketplace]
# Output: title, brand, bullets, price, category, BSR — data needed for keyword extraction

set -uo pipefail

ASIN="?Usage: fetch-competitor.sh <ASIN> [marketplace]"
MP="-us"

declare -A DOMAINS=(
  [us]="www.amazon.com" [uk]="www.amazon.co.uk" [de]="www.amazon.de"
  [fr]="www.amazon.fr" [it]="www.amazon.it" [es]="www.amazon.es"
  [jp]="www.amazon.co.jp" [ca]="www.amazon.ca" [au]="www.amazon.com.au"
  [in]="www.amazon.in" [mx]="www.amazon.com.mx" [br]="www.amazon.com.br"
)

DOMAIN="-www.amazon.com"
URL="https://DOMAIN/dp/ASIN"

PAGE=$(curl -sL \
  -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36" \
  -H "Accept-Language: en-US,en;q=0.9" \
  -H "Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8" \
  -H "Accept-Encoding: gzip, deflate" \
  --compressed \
  --max-time 15 \
  "$URL" 2>/dev/null)

if [ -z "$PAGE" ]; then
  echo "ERROR: Failed to fetch $URL"
  exit 1
fi

echo "=== COMPETITOR: $ASIN ($MP) ==="
echo "URL: $URL"
echo ""

# Title — primary keyword source
echo "=== TITLE ==="
echo "$PAGE" | grep -o 'productTitle"[^>]*>[^<]*' | sed 's/productTitle"[^>]*>//;s/^[[:space:]]*//;s/[[:space:]]*$//' | head -1
echo ""

# Brand
echo "=== BRAND ==="
echo "$PAGE" | grep -o 'bylineInfo"[^>]*>[^<]*' | sed 's/bylineInfo"[^>]*>//;s/^[[:space:]]*Visit the //;s/ Store$//' | head -1
echo ""

# Price
echo "=== PRICE ==="
echo "$PAGE" | grep -o '<span class="a-offscreen">[^<]*</span>' | head -1 | sed 's/<[^>]*>//g'
echo ""

# Bullet points — rich keyword source
echo "=== BULLET POINTS ==="
echo "$PAGE" | grep -o 'a-list-item">[A-Z][^<]\{15,\}' | sed 's/a-list-item">//' | head -10
echo ""

# Category
echo "=== CATEGORY ==="
echo "$PAGE" | grep -o 'a-link-normal a-color-tertiary"[^>]*>[^<]*' | sed 's/.*>//;s/^[[:space:]]*//;s/[[:space:]]*$//' | head -5
echo ""

# BSR — indicates sales volume
echo "=== BEST SELLERS RANK ==="
echo "$PAGE" | grep -o '#[0-9,]* in [^<]*' | head -3
echo ""

# Review count — indicates market strength
echo "=== REVIEW COUNT ==="
echo "$PAGE" | grep -o 'acrCustomerReviewText"[^>]*>[^<]*' | sed 's/acrCustomerReviewText"[^>]*>//' | head -1
echo ""

echo "=== END ==="

ClawHub Data Analysis Research+2

Amazon Fba Calculator

Skill

Amazon FBA Calculator - Complete fee breakdown and profit analysis

---
name: amazon-fba-calculator
version: 1.0.0
description: Amazon FBA Calculator - Complete fee breakdown and profit analysis
platform: amazon
lang: en
---

# Amazon FBA Calculator (Lite)

Precise FBA fee calculation based on product dimensions and weight.

## Features

- **Size Tier Detection** - Automatic classification
- **FBA Fulfillment Fee** - 2024 rates
- **Monthly Storage Fee** - Standard & Peak season
- **Long-term Storage Fee** - 271+ days aging
- **Referral Fee** - By category
- **Profit Analysis** - Gross/Net margin, ROI
- **Optimization Tips** - Size, weight, inventory

## Size Tiers (2024)

| Tier | Max Weight | Max Dimensions |
|------|------------|----------------|
| Small Standard | 1 lb | 15"×12"×0.75" |
| Large Standard | 20 lb | 18"×14"×8" |
| Small Oversize | 70 lb | 60"×30" |
| Medium Oversize | 150 lb | L+Girth ≤108" |
| Large Oversize | 150 lb | L+Girth ≤165" |
| Special Oversize | >150 lb | >165" |

## Input

```json
{
  "length": 10.0,
  "width": 6.0,
  "height": 3.0,
  "weight": 1.2,
  "selling_price": 29.99,
  "product_cost": 8.00,
  "inbound_shipping_cost": 1.50,
  "category": "kitchen"
}
```

## Output

- Size tier classification
- Fee breakdown table
- Profit metrics (margin, ROI)
- Optimization suggestions

## Usage

```bash
python3 scripts/calculator.py
python3 scripts/calculator.py '{"length": 10, "width": 6, ...}' --zh
```

---

_Version 1.0.0 | Platform: Amazon | Variant: Lite_

---

**Part of [Nexscope AI](https://www.nexscope.ai/) — AI tools for e-commerce sellers.**

FILE:scripts/calculator.py
#!/usr/bin/env python3
"""
Amazon FBA Calculator - Core Engine
Amazon FBA FeeCalculate - Core Engine

Features:
- SizedivideLevelJudgment (Size Tier)
- FBA Fulfillment Fee Precise calculation
- Monthly Storage Fee
- Referral Fee
- Long-term Storage Fee
- Profit Analysis
- FeeOptimization Suggestions

Based on 2024 years Amazon FBA Rate

Version: 1.0.0
"""

import json
from dataclasses import dataclass, field
from typing import List, Dict, Optional, Tuple
from enum import Enum
from datetime import datetime
import sys


class SizeTier(Enum):
    """FBA SizedivideLevel"""
    SMALL_STANDARD = "Small Standard"
    LARGE_STANDARD = "Large Standard"
    SMALL_OVERSIZE = "Small Oversize"
    MEDIUM_OVERSIZE = "Medium Oversize"
    LARGE_OVERSIZE = "Large Oversize"
    SPECIAL_OVERSIZE = "Special Oversize"


class StorageSeason(Enum):
    """StorageSeason"""
    STANDARD = "standard"      # Jan-Sep
    PEAK = "peak"              # Oct-Dec


# ============================================================
# 2024 FBA RateTable
# ============================================================

# FBA Fulfillment Fee (Fulfillmentfee) - 2024
FBA_FULFILLMENT_FEES = {
    SizeTier.SMALL_STANDARD: {
        #  heavy quantity (oz): Fee
        "base": 3.22,
        "per_oz_above_4": 0.08,
        "max_weight_oz": 16,
    },
    SizeTier.LARGE_STANDARD: {
        # By weight tier
        "tiers": [
            (4, 3.86),      # 0-4 oz
            (8, 4.08),      # 4+ to 8 oz
            (12, 4.24),     # 8+ to 12 oz
            (16, 4.75),     # 12+ to 16 oz (1 lb)
            (32, 5.40),     # 1+ to 2 lb
            (48, 6.10),     # 2+ to 3 lb
            (320, 6.10),    # 3+ to 20 lb (base + per lb)
        ],
        "per_lb_above_3": 0.38,
    },
    SizeTier.SMALL_OVERSIZE: {
        "base": 9.73,
        "per_lb_above_1": 0.42,
    },
    SizeTier.MEDIUM_OVERSIZE: {
        "base": 19.05,
        "per_lb_above_1": 0.42,
    },
    SizeTier.LARGE_OVERSIZE: {
        "base": 89.98,
        "per_lb_above_90": 0.83,
    },
    SizeTier.SPECIAL_OVERSIZE: {
        "base": 158.49,
        "per_lb_above_90": 0.83,
    },
}

# Monthly Storage Fee (monthsStoragefee) - 2024
STORAGE_FEE_PER_CUBIC_FOOT = {
    SizeTier.SMALL_STANDARD: {"standard": 0.78, "peak": 2.40},
    SizeTier.LARGE_STANDARD: {"standard": 0.78, "peak": 2.40},
    SizeTier.SMALL_OVERSIZE: {"standard": 0.56, "peak": 1.40},
    SizeTier.MEDIUM_OVERSIZE: {"standard": 0.56, "peak": 1.40},
    SizeTier.LARGE_OVERSIZE: {"standard": 0.56, "peak": 1.40},
    SizeTier.SPECIAL_OVERSIZE: {"standard": 0.56, "peak": 1.40},
}

# Long-term Storage Fee (PeriodStoragefee) - 2024
LONG_TERM_STORAGE_FEE = {
    "271_365_days": 1.50,    # Per cubic foot
    "over_365_days": 6.90,   # Per cubic foot
}

# Referral Fee (CommissionRate)
REFERRAL_FEE_RATES = {
    "default": 0.15,
    "electronics": 0.08,
    "computers": 0.08,
    "camera": 0.08,
    "video_games": 0.15,
    "books": 0.15,
    "clothing": 0.17,
    "shoes": 0.15,
    "jewelry": 0.20,
    "watches": 0.15,
    "furniture": 0.15,
    "home": 0.15,
    "kitchen": 0.15,
    "beauty": 0.15,
    "health": 0.15,
    "grocery": 0.15,
    "pet": 0.15,
    "toys": 0.15,
    "baby": 0.15,
    "sports": 0.15,
    "automotive": 0.12,
}

# Removal/Disposal Fee
REMOVAL_FEE = {
    SizeTier.SMALL_STANDARD: 0.97,
    SizeTier.LARGE_STANDARD: 0.97,
    SizeTier.SMALL_OVERSIZE: 4.15,
    SizeTier.MEDIUM_OVERSIZE: 4.15,
    SizeTier.LARGE_OVERSIZE: 6.87,
    SizeTier.SPECIAL_OVERSIZE: 6.87,
}


# ============================================================
# Data Structures
# ============================================================

@dataclass
class ProductDimensions:
    """ProductSize"""
    length: float  # inches
    width: float   # inches
    height: float  # inches
    weight: float  # lbs
    
    @property
    def dimensional_weight(self) -> float:
        """Volume heavy  (DIM weight)"""
        return (self.length * self.width * self.height) / 139
    
    @property
    def billable_weight(self) -> float:
        """Billable weight (Take the greater of actual and dimensional weight)"""
        return max(self.weight, self.dimensional_weight)
    
    @property
    def cubic_feet(self) -> float:
        """Cubic feet"""
        return (self.length * self.width * self.height) / 1728
    
    @property
    def girth(self) -> float:
        """range (2*(width+height))"""
        return 2 * (self.width + self.height)
    
    @property
    def length_plus_girth(self) -> float:
        """Degree + range"""
        return self.length + self.girth


@dataclass
class ProductInput:
    """ProductInput"""
    # BasicInformation
    sku: str = "SKU001"
    name: str = "Product"
    
    # Size (inches)
    length: float = 0.0
    width: float = 0.0
    height: float = 0.0
    
    #  heavy quantity (lbs)
    weight: float = 0.0
    
    # Price
    selling_price: float = 0.0
    product_cost: float = 0.0
    
    # Logistics
    inbound_shipping_cost: float = 0.0  # InboundCost/piece
    
    # Other
    category: str = "default"
    monthly_units_sold: int = 100
    inventory_days: int = 30
    inventory_age_days: int = 0  # Libraryage (use at PeriodStoragefee)
    
    @property
    def dimensions(self) -> ProductDimensions:
        return ProductDimensions(
            length=self.length,
            width=self.width,
            height=self.height,
            weight=self.weight
        )


@dataclass
class FeeBreakdown:
    """FeeBreakdown"""
    # FBA Fee
    fba_fulfillment_fee: float = 0.0
    monthly_storage_fee: float = 0.0
    long_term_storage_fee: float = 0.0
    referral_fee: float = 0.0
    
    # OtherFee
    inbound_shipping: float = 0.0
    removal_fee: float = 0.0
    
    # Summary
    total_amazon_fees: float = 0.0
    total_all_fees: float = 0.0
    
    # Profit
    gross_profit: float = 0.0
    net_profit: float = 0.0
    gross_margin: float = 0.0
    net_margin: float = 0.0
    roi: float = 0.0


@dataclass
class SizeTierInfo:
    """SizedivideLevelInformation"""
    tier: SizeTier
    reason: str
    billable_weight: float
    dimensional_weight: float
    actual_weight: float


@dataclass
class OptimizationTip:
    """Optimization Suggestions"""
    category: str
    tip: str
    tip_zh: str
    potential_savings: float


@dataclass
class CalculationResult:
    """CalculateResult"""
    product: ProductInput
    size_tier: SizeTierInfo
    fees: FeeBreakdown
    optimization_tips: List[OptimizationTip]
    summary: str
    summary_zh: str


# ============================================================
# CoreCalculateFunction
# ============================================================

def determine_size_tier(dims: ProductDimensions) -> SizeTierInfo:
    """JudgmentSizedivideLevel"""
    L, W, H = sorted([dims.length, dims.width, dims.height], reverse=True)
    weight_oz = dims.weight * 16
    
    # Small Standard: ≤15oz, ≤15"×12"×0.75"
    if weight_oz <= 16 and L <= 15 and W <= 12 and H <= 0.75:
        tier = SizeTier.SMALL_STANDARD
        reason = f"Weight ≤1lb, dims ≤15×12×0.75"
    
    # Large Standard: ≤20lb, ≤18"×14"×8"
    elif dims.weight <= 20 and L <= 18 and W <= 14 and H <= 8:
        tier = SizeTier.LARGE_STANDARD
        reason = f"Weight ≤20lb, dims ≤18×14×8"
    
    # Small Oversize: ≤70lb, ≤60"×30" (longest side ≤60, median ≤30)
    elif dims.weight <= 70 and L <= 60 and W <= 30:
        tier = SizeTier.SMALL_OVERSIZE
        reason = f"Weight ≤70lb, longest ≤60, median ≤30"
    
    # Medium Oversize: ≤150lb, length+girth ≤108"
    elif dims.weight <= 150 and dims.length_plus_girth <= 108:
        tier = SizeTier.MEDIUM_OVERSIZE
        reason = f"Weight ≤150lb, L+girth ≤108"
    
    # Large Oversize: ≤150lb, length+girth ≤165"
    elif dims.weight <= 150 and dims.length_plus_girth <= 165:
        tier = SizeTier.LARGE_OVERSIZE
        reason = f"Weight ≤150lb, L+girth ≤165"
    
    # Special Oversize
    else:
        tier = SizeTier.SPECIAL_OVERSIZE
        reason = f"Exceeds Large Oversize limits"
    
    return SizeTierInfo(
        tier=tier,
        reason=reason,
        billable_weight=dims.billable_weight,
        dimensional_weight=dims.dimensional_weight,
        actual_weight=dims.weight
    )


def calculate_fba_fulfillment_fee(size_tier: SizeTier, weight_lbs: float) -> float:
    """Calculate FBA Fulfillment"""
    weight_oz = weight_lbs * 16
    
    if size_tier == SizeTier.SMALL_STANDARD:
        fee_info = FBA_FULFILLMENT_FEES[size_tier]
        if weight_oz <= 4:
            return fee_info["base"]
        else:
            extra_oz = min(weight_oz - 4, 12)  # max 16oz total
            return fee_info["base"] + extra_oz * fee_info["per_oz_above_4"]
    
    elif size_tier == SizeTier.LARGE_STANDARD:
        fee_info = FBA_FULFILLMENT_FEES[size_tier]
        for max_oz, fee in fee_info["tiers"]:
            if weight_oz <= max_oz:
                return fee
        # Above 3 lb
        extra_lbs = weight_lbs - 3
        base = 6.10
        return base + extra_lbs * fee_info["per_lb_above_3"]
    
    elif size_tier == SizeTier.SMALL_OVERSIZE:
        fee_info = FBA_FULFILLMENT_FEES[size_tier]
        if weight_lbs <= 1:
            return fee_info["base"]
        return fee_info["base"] + (weight_lbs - 1) * fee_info["per_lb_above_1"]
    
    elif size_tier == SizeTier.MEDIUM_OVERSIZE:
        fee_info = FBA_FULFILLMENT_FEES[size_tier]
        if weight_lbs <= 1:
            return fee_info["base"]
        return fee_info["base"] + (weight_lbs - 1) * fee_info["per_lb_above_1"]
    
    elif size_tier == SizeTier.LARGE_OVERSIZE:
        fee_info = FBA_FULFILLMENT_FEES[size_tier]
        if weight_lbs <= 90:
            return fee_info["base"]
        return fee_info["base"] + (weight_lbs - 90) * fee_info["per_lb_above_90"]
    
    else:  # Special Oversize
        fee_info = FBA_FULFILLMENT_FEES[SizeTier.SPECIAL_OVERSIZE]
        if weight_lbs <= 90:
            return fee_info["base"]
        return fee_info["base"] + (weight_lbs - 90) * fee_info["per_lb_above_90"]


def calculate_storage_fee(size_tier: SizeTier, cubic_feet: float, month: int = None) -> float:
    """CalculatemonthsStoragefee"""
    if month is None:
        month = datetime.now().month
    
    season = "peak" if month >= 10 else "standard"
    rate = STORAGE_FEE_PER_CUBIC_FOOT[size_tier][season]
    
    return cubic_feet * rate


def calculate_long_term_storage_fee(cubic_feet: float, age_days: int) -> float:
    """CalculatePeriodStoragefee"""
    if age_days > 365:
        return cubic_feet * LONG_TERM_STORAGE_FEE["over_365_days"]
    elif age_days > 270:
        return cubic_feet * LONG_TERM_STORAGE_FEE["271_365_days"]
    return 0.0


def calculate_referral_fee(selling_price: float, category: str) -> float:
    """CalculateCommission"""
    rate = REFERRAL_FEE_RATES.get(category.lower(), REFERRAL_FEE_RATES["default"])
    return selling_price * rate


def calculate_all_fees(product: ProductInput) -> Tuple[FeeBreakdown, SizeTierInfo]:
    """Calculateplace has Fee"""
    dims = product.dimensions
    size_info = determine_size_tier(dims)
    
    # FBA Fulfillment
    fba_fee = calculate_fba_fulfillment_fee(size_info.tier, size_info.billable_weight)
    
    # monthsStoragefee ( by InventorydaysAllocate)
    storage_monthly = calculate_storage_fee(size_info.tier, dims.cubic_feet)
    storage_per_unit = storage_monthly * (product.inventory_days / 30)
    
    # PeriodStoragefee
    ltsf = calculate_long_term_storage_fee(dims.cubic_feet, product.inventory_age_days)
    
    # Commission
    referral = calculate_referral_fee(product.selling_price, product.category)
    
    # Removal fee
    removal = REMOVAL_FEE.get(size_info.tier, 0)
    
    # Summary
    total_amazon = fba_fee + storage_per_unit + ltsf + referral
    total_all = total_amazon + product.inbound_shipping_cost
    
    # ProfitCalculate
    gross_profit = product.selling_price - product.product_cost - referral - fba_fee
    net_profit = product.selling_price - product.product_cost - total_all
    
    gross_margin = gross_profit / product.selling_price if product.selling_price > 0 else 0
    net_margin = net_profit / product.selling_price if product.selling_price > 0 else 0
    
    # ROI
    total_investment = product.product_cost + product.inbound_shipping_cost
    roi = net_profit / total_investment if total_investment > 0 else 0
    
    fees = FeeBreakdown(
        fba_fulfillment_fee=round(fba_fee, 2),
        monthly_storage_fee=round(storage_per_unit, 2),
        long_term_storage_fee=round(ltsf, 2),
        referral_fee=round(referral, 2),
        inbound_shipping=round(product.inbound_shipping_cost, 2),
        removal_fee=round(removal, 2),
        total_amazon_fees=round(total_amazon, 2),
        total_all_fees=round(total_all, 2),
        gross_profit=round(gross_profit, 2),
        net_profit=round(net_profit, 2),
        gross_margin=round(gross_margin, 4),
        net_margin=round(net_margin, 4),
        roi=round(roi, 4),
    )
    
    return fees, size_info


def generate_optimization_tips(product: ProductInput, fees: FeeBreakdown, size_info: SizeTierInfo) -> List[OptimizationTip]:
    """GenerateOptimization Suggestions"""
    tips = []
    
    # SizeOptimization
    if size_info.tier == SizeTier.LARGE_STANDARD:
        if product.length > 15 or product.width > 12:
            tips.append(OptimizationTip(
                category="Size",
                tip="Consider smaller packaging to qualify for Small Standard tier",
                tip_zh="Consider reducing package size to reach small standardLevelother",
                potential_savings=fees.fba_fulfillment_fee - 3.22
            ))
    
    #  heavy quantityOptimization
    if size_info.dimensional_weight > size_info.actual_weight * 1.5:
        tips.append(OptimizationTip(
            category="Weight",
            tip="Product is being charged by dimensional weight. Reduce package size.",
            tip_zh="ProductCharge by dimensional weight。ReducePackagingSizeCan reduceFee。",
            potential_savings=0
        ))
    
    # Inventoryweeksconvert
    if product.inventory_days > 45:
        tips.append(OptimizationTip(
            category="Inventory",
            tip=f"Inventory days ({product.inventory_days}) is high. Faster turnover reduces storage fees.",
            tip_zh=f"Inventorydays ({product.inventory_days}) biasHigh。add fast weeksconvertCanReduceStoragefee。",
            potential_savings=fees.monthly_storage_fee * 0.3
        ))
    
    # PeriodStorage
    if product.inventory_age_days > 180:
        tips.append(OptimizationTip(
            category="Long-term Storage",
            tip="Watch out for long-term storage fees after 271 days",
            tip_zh="Note 271 daysWill generate afterPeriodStoragefee",
            potential_savings=0
        ))
    
    # Profit Margin
    if fees.net_margin < 0.15:
        tips.append(OptimizationTip(
            category="Pricing",
            tip="Net margin below 15%. Consider raising price or reducing costs.",
            tip_zh="Net Margin low  at  15%。Consider raising price or reducingCost。",
            potential_savings=0
        ))
    
    return tips


def calculate(product: ProductInput) -> CalculationResult:
    """MainCalculateFunction"""
    fees, size_info = calculate_all_fees(product)
    tips = generate_optimization_tips(product, fees, size_info)
    
    # GenerateSummary
    if fees.net_margin >= 0.20:
        status = "✅ Healthy"
        status_zh = "✅ Healthy"
    elif fees.net_margin >= 0.10:
        status = "⚠️ Marginal"
        status_zh = "⚠️  side edge"
    elif fees.net_margin >= 0:
        status = "🔴 Low"
        status_zh = "🔴  low "
    else:
        status = "💀 Loss"
        status_zh = "💀 Loss"
    
    summary = f"{status} | Net margin: {fees.net_margin*100:.1f}% | FBA fee: fees.fba_fulfillment_fee"
    summary_zh = f"{status_zh} | Net Margin: {fees.net_margin*100:.1f}% | FBAfee: fees.fba_fulfillment_fee"
    
    return CalculationResult(
        product=product,
        size_tier=size_info,
        fees=fees,
        optimization_tips=tips,
        summary=summary,
        summary_zh=summary_zh
    )


# ============================================================
# OutputFormat
# ============================================================

def format_report(result: CalculationResult, lang: str = "en") -> str:
    """FormatReport"""
    p = result.product
    f = result.fees
    s = result.size_tier
    
    if lang == "zh":
        lines = [
            "💰 **FBA FeeCalculateReport**",
            "",
            f"**Product**: {p.name} ({p.sku})",
            f"**Size**: {p.length}\" × {p.width}\" × {p.height}\"",
            f"** heavy quantity**: {p.weight} lbs ({p.weight*16:.0f} oz)",
            f"**Selling Price**: .2f",
            "",
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            f"## 📏 SizedivideLevel: {s.tier.value}",
            f"   {s.reason}",
            f"   Billable weight: {s.billable_weight:.2f} lbs",
            "",
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            "## 💵 FeeBreakdown",
            "",
            f"```",
            f"Selling Price                    .2f",
            f"────────────────────────────────",
            f"ProductCost                -.2f",
            f"FBA Fulfillment              -.2f",
            f"monthsStoragefee (Allocate)         -.2f",
            f"PlatformCommission                -.2f",
            f"InboundShipping                -.2f",
        ]
        
        if f.long_term_storage_fee > 0:
            lines.append(f"PeriodStoragefee              -.2f")
        
        lines.extend([
            f"────────────────────────────────",
            f"Amazon FeeTotal         .2f",
            f"totalFee                  .2f",
            f"────────────────────────────────",
            f"Gross Profit                  .2f ({f.gross_margin*100:.1f}%)",
            f"Net Profit                  .2f ({f.net_margin*100:.1f}%)",
            f"ROI                     {f.roi*100:.1f}%",
            f"```",
            "",
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            result.summary_zh,
        ])
        
        if result.optimization_tips:
            lines.extend([
                "",
                "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
                "",
                "## 💡 Optimization Suggestions",
                "",
            ])
            for i, tip in enumerate(result.optimization_tips, 1):
                lines.append(f"**{i}. [{tip.category}]** {tip.tip_zh}")
                if tip.potential_savings > 0:
                    lines.append(f"   potential in Save: .2f")
                lines.append("")
    else:
        lines = [
            "💰 **FBA Fee Calculation Report**",
            "",
            f"**Product**: {p.name} ({p.sku})",
            f"**Dimensions**: {p.length}\" × {p.width}\" × {p.height}\"",
            f"**Weight**: {p.weight} lbs ({p.weight*16:.0f} oz)",
            f"**Selling Price**: .2f",
            "",
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            f"## 📏 Size Tier: {s.tier.value}",
            f"   {s.reason}",
            f"   Billable Weight: {s.billable_weight:.2f} lbs",
            "",
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            "## 💵 Fee Breakdown",
            "",
            f"```",
            f"Selling Price           .2f",
            f"────────────────────────────────",
            f"Product Cost            -.2f",
            f"FBA Fulfillment Fee     -.2f",
            f"Monthly Storage (pro-rated) -.2f",
            f"Referral Fee            -.2f",
            f"Inbound Shipping        -.2f",
        ]
        
        if f.long_term_storage_fee > 0:
            lines.append(f"Long-term Storage       -.2f")
        
        lines.extend([
            f"────────────────────────────────",
            f"Total Amazon Fees       .2f",
            f"Total All Fees          .2f",
            f"────────────────────────────────",
            f"Gross Profit            .2f ({f.gross_margin*100:.1f}%)",
            f"Net Profit              .2f ({f.net_margin*100:.1f}%)",
            f"ROI                     {f.roi*100:.1f}%",
            f"```",
            "",
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            result.summary,
        ])
        
        if result.optimization_tips:
            lines.extend([
                "",
                "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
                "",
                "## 💡 Optimization Tips",
                "",
            ])
            for i, tip in enumerate(result.optimization_tips, 1):
                lines.append(f"**{i}. [{tip.category}]** {tip.tip}")
                if tip.potential_savings > 0:
                    lines.append(f"   Potential Savings: .2f")
                lines.append("")
    
    return "\n".join(lines)


# ============================================================
# CLI
# ============================================================

def main():
    # TestData
    test_product = ProductInput(
        sku="TEST001",
        name="Kitchen Gadget",
        length=10.0,
        width=6.0,
        height=3.0,
        weight=1.2,
        selling_price=29.99,
        product_cost=8.00,
        inbound_shipping_cost=1.50,
        category="kitchen",
        monthly_units_sold=100,
        inventory_days=45,
        inventory_age_days=60,
    )
    
    # ParseCommand line parameter
    if len(sys.argv) > 1:
        try:
            data = json.loads(sys.argv[1])
            test_product = ProductInput(**data)
        except:
            pass
    
    result = calculate(test_product)
    
    lang = "zh" if "--zh" in sys.argv else "en"
    print(format_report(result, lang))


if __name__ == "__main__":
    main()

Warehouse Optimization

Skill

E-commerce warehouse and inventory optimization advisor. Analyzes inventory health, calculates safety stock and reorder points, performs ABC analysis, evalua...

---
name: warehouse-optimization
description: "E-commerce warehouse and inventory optimization advisor. Analyzes inventory health, calculates safety stock and reorder points, performs ABC analysis, evaluates fulfillment costs, and provides actionable recommendations for improving efficiency. Supports all major fulfillment models: Self-fulfillment, Amazon FBA/FBM, Walmart WFS, 3PL, Shopify Fulfillment, TikTok Shop, Dropshipping, and Hybrid setups. No API key required. Use when: (1) reducing stockouts or overstock, (2) calculating safety stock levels, (3) optimizing warehouse costs, (4) improving Amazon IPI score, (5) analyzing inventory KPIs."
metadata: {"nexscope":{"emoji":"🏭","category":"ecommerce"}}
---

# Warehouse & Inventory Optimization 🏭

Diagnose and optimize your warehouse operations: analyze inventory health, calculate safety stock, reduce costs, and improve efficiency. No API key required.

## Installation

```bash
npx skills add nexscope-ai/eCommerce-Skills --skill warehouse-optimization -g
```

## Supported Fulfillment Models

| Model | Platform | Optimization Focus |
|-------|----------|-------------------|
| **Self-Fulfillment** | Any | Warehouse layout, staffing, pick/pack efficiency, storage costs |
| **Amazon FBA** | Amazon | IPI score, storage fees, aged inventory, restock limits |
| **Amazon FBM** | Amazon | Shipping speed, Prime eligibility, cost vs FBA |
| **Walmart WFS** | Walmart | Fulfillment fees, storage limits, Pro Seller status |
| **3PL** | Multi-channel | Provider costs, SLAs, contract optimization, hidden fees |
| **Shopify Fulfillment Network** | Shopify | Distributed inventory, delivery speed, cost analysis |
| **TikTok Shop Fulfillment** | TikTok | TikTok-specific requirements, shipping SLAs |
| **Dropshipping** | Any | Supplier reliability, lead times, stockout prevention |
| **Hybrid** | Multi-channel | Inventory allocation, channel balancing, split strategy |

## Usage Examples

```
Audit my warehouse operations. I'm self-fulfilling from a 2,000 sq ft warehouse.
500 SKUs, 3,000 orders/month. Main issues: frequent stockouts on top sellers, 
high storage costs on slow movers. Help me optimize.
```

```
I use FBA for my Amazon store. IPI score dropped to 350. I have excess inventory 
warnings on 40 SKUs. How do I fix this before I get storage limits?
```

```
Running FBM for my oversized products and FBA for standard. 200 orders/day total.
Which SKUs should I move to FBA vs keep FBM? Help me optimize the split.
```

```
Using ShipBob as my 3PL. Monthly bill is $8,500 for 2,000 orders. Is this competitive?
What should I negotiate or consider switching?
```

---

## First Interaction

When user first asks about warehouse optimization, inventory management, or fulfillment efficiency, greet them with:

```
🏭 Warehouse Optimization ready!

I'll help you diagnose issues and optimize your inventory operations.

**Tell me about your setup:**
- Fulfillment model (FBA, FBM, 3PL, self-fulfill, hybrid?)
- Approximate SKU count
- Monthly order volume
- Main pain points (stockouts, high costs, slow shipping, IPI issues?)

Or just describe your situation and I'll guide you from there.
```

---

## Handling Incomplete Input

```
To optimize your warehouse operations, I need:

**Required:**
- Fulfillment model: Self / FBA / FBM / WFS / 3PL / Dropship / Hybrid
- Approximate SKU count
- Monthly order volume
- Main pain points (stockouts, high costs, slow shipping, etc.)

**Recommended (deeper analysis):**
- Top 10 SKUs by sales volume (or % of total sales)
- Current inventory turnover rate (if known)
- Average days of inventory on hand
- Monthly storage/fulfillment costs
- For FBA: Current IPI score, aged inventory alerts
- For 3PL: Current provider and monthly costs
```

---

## Audit Workflow

### Step 1: Collect Current State Data

| Data Point | Why It Matters |
|------------|----------------|
| Fulfillment model | Determines optimization approach |
| SKU count | Complexity indicator |
| Monthly orders | Scale of operations |
| Top SKUs (% of sales) | For ABC analysis |
| Current turnover rate | Inventory health indicator |
| Days of inventory | Over/understock signal |
| Stockout frequency | Lost sales indicator |
| Storage costs | Cost optimization potential |
| Pick/pack accuracy | Quality indicator |

### Step 2: Calculate Key Metrics

**Inventory Turnover Rate:**
```
Inventory Turnover = Cost of Goods Sold (COGS) / Average Inventory Value
```
- **Benchmark:** 4-6x/year for most e-commerce (higher = better)
- **Low turnover (<4):** Excess inventory, capital tied up
- **High turnover (>8):** Risk of stockouts, tight supply chain

**Days of Inventory (DOI):**
```
DOI = (Average Inventory / COGS) × 365
```
- **Target:** 30-60 days for most products
- **Too high (>90 days):** Overstock, storage cost drain
- **Too low (<14 days):** Stockout risk

**Stockout Rate:**
```
Stockout Rate = (Days Out of Stock / Total Days) × 100
```
- **Target:** <2%
- **Impact:** Each 1% stockout ≈ 1% lost revenue

**Perfect Order Rate:**
```
Perfect Order Rate = (Orders Shipped Complete, On-Time, Undamaged / Total Orders) × 100
```
- **Target:** >95%

### Step 3: Perform ABC Analysis

Classify SKUs by revenue contribution:

| Class | % of SKUs | % of Revenue | Inventory Strategy |
|-------|-----------|--------------|-------------------|
| **A** | ~20% | ~80% | High priority, never stockout, frequent replenishment |
| **B** | ~30% | ~15% | Moderate priority, standard replenishment |
| **C** | ~50% | ~5% | Low priority, review for discontinuation |

**Recommendations by class:**
- **A items:** Safety stock = 2-4 weeks, reorder frequently, prime warehouse locations
- **B items:** Safety stock = 2-3 weeks, standard locations
- **C items:** Minimal safety stock, consider dropship or discontinue slow movers

### Step 4: Calculate Safety Stock & Reorder Points

**Safety Stock Formula:**
```
Safety Stock = Z × σd × √L

Where:
- Z = Service level factor (1.65 for 95%, 2.33 for 99%)
- σd = Standard deviation of daily demand
- L = Lead time in days
```

**Simplified Safety Stock (if limited data):**
```
Safety Stock = (Max Daily Sales - Avg Daily Sales) × Lead Time
```

**Reorder Point Formula:**
```
Reorder Point = (Avg Daily Sales × Lead Time) + Safety Stock
```

**Example calculation:**
```
Product: Widget A
- Average daily sales: 10 units
- Max daily sales: 18 units
- Lead time: 14 days

Safety Stock = (18 - 10) × 14 = 112 units
Reorder Point = (10 × 14) + 112 = 252 units

→ Reorder when inventory hits 252 units
→ Keep 112 units as buffer
```

### Step 5: Analyze Costs

**Fulfillment Cost Benchmarks:**

| Cost Component | Self-Fulfill | 3PL | FBA |
|----------------|--------------|-----|-----|
| Storage | $0.30-0.50/cu ft | $0.45-0.75/cu ft | $0.87-2.40/cu ft |
| Pick & Pack | Labor-based | $1.50-3.00/order | Included in fee |
| Shipping | Carrier rates | Discounted rates | Prime rates |
| Returns | Labor + space | $3-8/return | Free for buyers |

**Cost Per Order (CPO):**
```
CPO = (Storage + Labor + Packaging + Shipping) / Total Orders
```

**Inventory Carrying Cost:**
```
Carrying Cost = Average Inventory Value × Carrying Rate (typically 20-30%/year)

Includes: Storage, insurance, obsolescence, opportunity cost
```

### Step 6: Platform-Specific Analysis

**Amazon FBA:**
- **IPI Score factors:** Excess inventory %, sell-through rate, stranded inventory, in-stock rate
- **Storage fee triggers:** Aged inventory (181+ days), low IPI (<400)
- **Restock limits:** Based on IPI and sales velocity

**Amazon FBM:**
- **Prime eligibility:** Seller Fulfilled Prime requirements
- **Shipping performance:** On-time delivery, valid tracking rate
- **Cost comparison:** When FBM beats FBA (oversized, slow movers)

**Walmart WFS:**
- **Pro Seller badge:** Fulfillment performance requirements
- **Storage fees:** Generally lower than FBA
- **Limitations:** Product restrictions, geographic coverage

**3PL Providers:**
- **Contract terms:** Minimum commitments, peak surcharges
- **Hidden costs:** Receiving fees, special handling, return processing
- **Performance SLAs:** Shipping accuracy, turnaround time

### Step 7: Generate Recommendations

Prioritize by impact and effort:

```
## Recommendations

### 🔴 Critical (Do Now)
| Issue | Impact | Action | Expected Result |
|-------|--------|--------|-----------------|

### 🟡 Important (This Month)
| Issue | Impact | Action | Expected Result |
|-------|--------|--------|-----------------|

### 🟢 Optimization (This Quarter)
| Issue | Impact | Action | Expected Result |
|-------|--------|--------|-----------------|
```

---

## FBA-Specific Optimization

### IPI Score Improvement

| Factor | Target | Actions |
|--------|--------|---------|
| **Excess inventory** | <5% | Create removal orders, run promotions, liquidate |
| **Sell-through rate** | >4.5 | Improve listing, PPC, reduce price |
| **Stranded inventory** | 0% | Fix listing errors, match ASINs |
| **In-stock rate** | >90% | Increase replenishment frequency |

**Aged Inventory Prevention:**
- Monitor inventory age weekly
- Take action before 181 days (aged fee trigger)
- Options: Removal order, outlet deals, liquidation, donate

**Storage Fee Calendar:**
- **Jan-Sep:** Standard rates
- **Oct-Dec:** Peak rates (3x higher)
- **Aged inventory surcharge:** 181+ days

### FBA Restock Calculation

```
Target FBA Inventory = (Avg Daily Units × Days of Cover) + Safety Buffer

Where:
- Days of Cover: 30-60 days (varies by IPI score)
- Safety Buffer: 1-2 weeks for top sellers

Example:
- Selling 10 units/day
- Target 45 days cover
- Safety: 10 days

Target = (10 × 45) + (10 × 10) = 550 units
```

---

## 3PL Cost Optimization

### Evaluate Your 3PL Costs

| Cost Type | What to Check |
|-----------|---------------|
| **Storage** | Per pallet vs per cu ft, minimum charges |
| **Pick & Pack** | Per order vs per item, kit fees |
| **Receiving** | Per unit, per carton, or per shipment |
| **Special handling** | Fragile, hazmat, temperature-controlled |
| **Peak surcharges** | Q4 rate increases |
| **Minimum commitments** | Monthly minimums, long-term contracts |

### 3PL Benchmark Costs (2025)

| Service | Low | Average | High |
|---------|-----|---------|------|
| Storage (per pallet/mo) | $8 | $15 | $25 |
| Pick & Pack (per order) | $2.50 | $4.00 | $6.00 |
| Additional item | $0.30 | $0.75 | $1.50 |
| Receiving (per unit) | $0.20 | $0.40 | $0.75 |

### When to Switch 3PLs

- Cost per order >20% above benchmark
- SLA failures >5% of orders
- Poor communication / slow issue resolution
- No volume-based discounts after 6+ months
- Geographic mismatch (shipping zones too far)

---

## Output Format

```
# 🏭 Warehouse Optimization Report

**Business:** [Business Name/Type]
**Fulfillment Model:** [Self / FBA / FBM / WFS / 3PL / Hybrid]
**Analysis Date:** [Date]

---

## 1. Current State Summary

| Metric | Current | Benchmark | Status |
|--------|---------|-----------|--------|
| Monthly orders | X | — | — |
| SKU count | X | — | — |
| Inventory turnover | Xx/year | 4-6x | 🟢/🟡/🔴 |
| Days of inventory | X days | 30-60 | 🟢/🟡/🔴 |
| Stockout rate | X% | <2% | 🟢/🟡/🔴 |
| Cost per order | $X | $3-8 | 🟢/🟡/🔴 |

---

## 2. ABC Analysis

[SKU classification table]

---

## 3. Inventory Optimization

### Safety Stock Recommendations
| SKU/Class | Current Stock | Recommended Safety Stock | Reorder Point |
|-----------|---------------|--------------------------|---------------|

### Overstock Alert
[SKUs with excess inventory]

### Stockout Risk
[SKUs at risk of stockout]

---

## 4. Cost Analysis

[Cost breakdown and optimization opportunities]

---

## 5. Recommendations

### 🔴 Critical
[High-impact, do now]

### 🟡 Important  
[Medium-impact, this month]

### 🟢 Optimization
[Lower priority improvements]

---

## 6. Expected Results

| Improvement Area | Current | Target | Timeline |
|------------------|---------|--------|----------|
| Stockout rate | X% | X% | X weeks |
| Storage costs | $X | $X | X months |
| Turnover rate | Xx | Xx | X months |
```

---

## Calculations Reference

### Core Formulas

| Metric | Formula |
|--------|---------|
| **Inventory Turnover** | COGS / Average Inventory |
| **Days of Inventory** | (Avg Inventory / COGS) × 365 |
| **Safety Stock** | Z × σd × √Lead Time |
| **Reorder Point** | (Avg Daily Sales × Lead Time) + Safety Stock |
| **Carrying Cost** | Avg Inventory × 25% (typical rate) |
| **Cost Per Order** | Total Fulfillment Costs / Total Orders |

### Service Level Factors (Z)

| Service Level | Z Factor |
|---------------|----------|
| 90% | 1.28 |
| 95% | 1.65 |
| 97.5% | 1.96 |
| 99% | 2.33 |

---

## Limitations

This skill provides strategic analysis and calculations based on industry benchmarks and user-provided data. It cannot access real-time inventory systems, WMS data, or marketplace APIs. For integrated inventory management, check out **[Nexscope](https://www.nexscope.ai/)** — Your AI Assistant for smarter E-commerce decisions.

---

## Related Skills

- **[Amazon Skills](https://github.com/nexscope-ai/Amazon-Skills)** — Keyword research, listing optimization, PPC campaigns, sales estimation
- **[eCommerce Skills](https://github.com/nexscope-ai/eCommerce-Skills)** — Cross-platform tools for all e-commerce businesses

---

**Built by [Nexscope](https://www.nexscope.ai/)** — research, validate, and act on e-commerce opportunities with AI.

FILE:evals/evals.json
{
  "skill_name": "warehouse-optimization",
  "evals": [
    {
      "id": 1,
      "prompt": "I have an Amazon FBA business. My IPI score dropped to 450 and I'm getting storage limits. I have 500 units of slow-moving inventory that's been sitting for 4 months. What should I do?",
      "expected_output": "Analysis of IPI score issues, aged inventory removal strategies, storage fee calculations, and actionable recommendations to improve IPI above 500",
      "files": []
    },
    {
      "id": 2,
      "prompt": "Calculate safety stock for my product. Average daily sales: 50 units. Lead time: 14 days. I want 95% service level. My supplier is sometimes late by up to 5 days.",
      "expected_output": "Safety stock calculation using statistical formula, reorder point recommendation, consideration of lead time variability",
      "files": []
    },
    {
      "id": 3,
      "prompt": "I sell on both Amazon FBA and Shopify with a 3PL. Should I consolidate to one fulfillment method or keep the hybrid setup? Monthly orders: 2000 Amazon, 800 Shopify.",
      "expected_output": "Cost comparison between hybrid vs consolidated, pros/cons analysis, channel-specific considerations, recommendation based on order volume",
      "files": []
    },
    {
      "id": 4,
      "prompt": "Do an ABC analysis for my inventory. I have 150 SKUs. Top 20 SKUs make 65% of revenue, next 40 make 25%, the rest make 10%. How should I prioritize?",
      "expected_output": "ABC classification breakdown, inventory management strategies per category, reorder frequency recommendations, storage location optimization",
      "files": []
    },
    {
      "id": 5,
      "prompt": "My TikTok Shop is growing fast. Getting 100+ orders daily now. Currently dropshipping but fulfillment is slow (7-10 days). Should I switch to TikTok Shop Fulfillment or use a 3PL?",
      "expected_output": "Comparison of dropshipping vs TikTok Fulfillment vs 3PL, shipping speed requirements, cost analysis, scalability considerations",
      "files": []
    }
  ]
}

Supply Chain Optimization Walmart

Skill

Supply Chain Bottleneck Analyzer for Walmart Marketplace sellers. Diagnose cash flow, inventory, WFS costs, and referral fees. Includes comparison with Amazo...

---
name: supply-chain-optimization-walmart
version: 1.0.0
description: "Supply Chain Bottleneck Analyzer for Walmart Marketplace sellers. Diagnose cash flow, inventory, WFS costs, and referral fees. Includes comparison with Amazon FBA, lower storage fee optimization, and Walmart Connect ad spend analysis. No API key required for basic analysis."
metadata: {"nexscope":{"emoji":"📦","category":"ecommerce"}}
---

# Supply Chain Optimization — Walmart 📦

Supply chain bottleneck analyzer for Walmart Marketplace sellers. Diagnose cash flow, inventory, WFS costs, and referral fees.

## Installation

```bash
npx skills add nexscope-ai/eCommerce-Skills --skill supply-chain-optimization-walmart -g
```

## Platform Characteristics

| Feature | Walmart | vs Amazon |
|---------|---------|-----------|
| Fulfillment | WFS (Walmart Fulfillment Services) | FBA |
| Commission | 6-15% (by category) | 8-15% |
| Payment cycle | 14-21 days | 14 days |
| Storage fees | Lower | Higher |
| Long-term storage | No extra fee | Yes |

## Cost Structure (Walmart)

```
Selling Price $XX
├── Product Cost
├── Inbound Shipping
├── WFS Fulfillment Fee (similar to FBA)
├── WFS Storage Fee (lower than FBA)
├── Referral Fee (6-15%)
├── Advertising (Walmart Connect)
└── Net Profit
```

## Benchmark Configuration

```python
BENCHMARKS = {
    "walmart": {
        "gross_margin": {
            "healthy": 0.35,    # Walmart commission lower, benchmark can be lower
            "warning": 0.25,
            "danger": 0.15
        },
        "shipping_ratio": {
            "healthy": 0.06,    # WFS shipping slightly higher
            "warning": 0.10,
            "danger": 0.15
        },
        "inventory_days": {
            "healthy": 45,
            "warning": 60,
            "danger": 90
        },
        "cash_cycle": {
            "healthy": 100,     # Payment cycle slightly longer
            "warning": 130,
            "danger": 160
        },
        "net_margin": {
            "healthy": 0.18,
            "warning": 0.10,
            "danger": 0.05
        }
    }
}
```

## API Integration

### Walmart Marketplace API

```bash
export WALMART_CLIENT_ID="xxx"
export WALMART_CLIENT_SECRET="xxx"
```

### Available Data

| Data | API |
|------|-----|
| Orders | Orders API |
| Inventory | Inventory API |
| Fee Reports | Reports API |

## Usage Flow

Same 4-step process as Amazon version:

1. Business profile collection
2. Supply chain data collection
3. Bottleneck diagnosis
4. Cost reduction plan output

## Input Data

```
**Sales (Walmart-specific)**
• Average Selling Price: $___
• WFS Fulfillment Fee: $___/unit
• Referral Fee Rate: ___%
• Walmart Connect Ad Spend Ratio: ___%

**Inventory**
• Current Inventory Days: ___ days
• (Walmart has no long-term storage fees)
```

## vs Amazon Comparison

| Item | Amazon | Walmart |
|------|--------|---------|
| Fulfillment | FBA | WFS |
| Storage fees | High | Low |
| Long-term storage | Yes | No |
| Commission | 8-15% | 6-15% |
| Payment cycle | 14 days | 14-21 days |
| Traffic | High | Medium |

## Key Advantages

- **No long-term storage fees** — Better for slow-moving inventory
- **Lower referral fees** — 6-15% vs Amazon's 8-15%
- **Lower storage costs** — WFS storage cheaper than FBA
- **Growing marketplace** — Less competition than Amazon

---

**Part of [Nexscope AI](https://www.nexscope.ai/) — AI tools for e-commerce sellers.**


FILE:scripts/calculator.py
#!/usr/bin/env python3
"""
Supply Chain Analyzer - Core Calculator
Supply Chain Analyzer - Core Calculator

Purpose: Calculate key metrics and diagnose bottlenecks
Version: 1.0.0
"""

import json
from dataclasses import dataclass
from typing import Optional, List, Dict
from enum import Enum


class HealthStatus(Enum):
    HEALTHY = "healthy"
    WARNING = "warning"
    DANGER = "danger"


# ============================================================
# Benchmark Configuration (customizable)
# ============================================================

BENCHMARKS = {
    "amazon": {
        "gross_margin": {
            "healthy": 0.40,    # >40% Healthy
            "warning": 0.30,    # 30-40% Warning
            "danger": 0.20      # <20% Danger
        },
        "shipping_ratio": {
            "healthy": 0.05,    # <5% Healthy
            "warning": 0.10,    # 5-10% Warning
            "danger": 0.15      # >15% Danger
        },
        "inventory_days": {
            "healthy": 45,      # <45days Healthy
            "warning": 60,      # 45-60days Warning
            "danger": 90        # >90days Danger
        },
        "cash_cycle": {
            "healthy": 90,      # <90days Healthy
            "warning": 120,     # 90-120days Warning
            "danger": 150       # >150days Danger
        },
        "net_margin": {
            "healthy": 0.20,    # >20% Healthy
            "warning": 0.10,    # 10-20% Warning
            "danger": 0.05      # <5% Danger
        }
    },
    "walmart": {
        "gross_margin": {
            "healthy": 0.35,    # Walmart Commission more  low 
            "warning": 0.25,
            "danger": 0.15
        },
        "shipping_ratio": {
            "healthy": 0.06,    # WFS ShippingSlightly higher
            "warning": 0.10,
            "danger": 0.15
        },
        "inventory_days": {
            "healthy": 45,
            "warning": 60,
            "danger": 90
        },
        "cash_cycle": {
            "healthy": 100,     # Payment CycleSlightly longer
            "warning": 130,
            "danger": 160
        },
        "net_margin": {
            "healthy": 0.18,
            "warning": 0.10,
            "danger": 0.05
        }
    },
    "tiktok": {
        "gross_margin": {
            "healthy": 0.45,    # NeedCoverInfluencerCommission
            "warning": 0.35,
            "danger": 0.25
        },
        "shipping_ratio": {
            "healthy": 0.05,
            "warning": 0.08,
            "danger": 0.12
        },
        "inventory_days": {
            "healthy": 30,      # TikTok Best sellerweeksPeriod short 
            "warning": 45,
            "danger": 60
        },
        "cash_cycle": {
            "healthy": 60,      # Fast payment
            "warning": 90,
            "danger": 120
        },
        "net_margin": {
            "healthy": 0.15,    # InfluencerShare after 
            "warning": 0.08,
            "danger": 0.03
        }
    },
    "shopify": {
        "gross_margin": {
            "healthy": 0.60,    # DTC Requires high gross marginAdvertising
            "warning": 0.50,
            "danger": 0.40
        },
        "shipping_ratio": {
            "healthy": 0.08,    # 3PL Fee
            "warning": 0.12,
            "danger": 0.18
        },
        "inventory_days": {
            "healthy": 45,
            "warning": 60,
            "danger": 90
        },
        "cash_cycle": {
            "healthy": 45,      # Fast payment (2-3days)
            "warning": 70,
            "danger": 100
        },
        "net_margin": {
            "healthy": 0.20,
            "warning": 0.12,
            "danger": 0.05
        }
    }
}


# ============================================================
# Data Structures
# ============================================================

@dataclass
class SupplyChainInput:
    """Supply ChainInput Data"""
    # Procurementend
    product_cost: float          # ProductCost (FOB)
    supplier_payment_days: int   # SupplierPayment terms (days)
    production_days: int         # ProductionweeksPeriod (days)
    
    # Logisticsend
    shipping_cost_per_unit: float  # Single pieceInboundCost
    shipping_days: int             # TransportTimeeffect (days)
    
    # Saleend
    selling_price: float         # Selling Price
    fba_fee: float              # FBA Fulfillment
    storage_fee: float          # monthsaverageStoragefee ( each piece)
    ad_spend_ratio: float       # AdvertisingfeeProportion (0-1)
    
    # Inventoryend
    inventory_days: int         # CurrentInventorydays
    has_long_term_storage: bool #  is no has PeriodStoragefee
    
    # Optional:  from  API Get
    daily_sales: Optional[float] = None      # DayAverage sales
    current_inventory: Optional[int] = None  # CurrentInventoryquantity
    
    # Platform
    platform: str = "amazon"


@dataclass
class MetricResult:
    """singleItemMetricsResult"""
    name: str
    value: float
    unit: str
    status: HealthStatus
    benchmark: float
    description: str


@dataclass 
class BottleneckItem:
    """BottleneckItem"""
    priority: int           # excellent first Level 1-3
    severity: str          # High/ in / low 
    title: str
    problem: str
    impact: str
    suggestion: str


@dataclass
class AnalysisResult:
    """AnalyzeResult"""
    metrics: List[MetricResult]
    cost_breakdown: Dict[str, float]
    bottlenecks: List[BottleneckItem]
    summary: str


# ============================================================
# CoreCalculateFunction
# ============================================================

def evaluate_status(value: float, thresholds: dict, higher_is_better: bool = True) -> HealthStatus:
    """
    EvaluateMetricsHealthyStatus
    
    Args:
        value: MetricsValue
        thresholds: ThresholdDictionary {"healthy": x, "warning": y, "danger": z}
        higher_is_better: True=ValueexceedHighexceed good , False=Valueexceed low exceed good 
    """
    if higher_is_better:
        if value >= thresholds["healthy"]:
            return HealthStatus.HEALTHY
        elif value >= thresholds["warning"]:
            return HealthStatus.WARNING
        else:
            return HealthStatus.DANGER
    else:
        if value <= thresholds["healthy"]:
            return HealthStatus.HEALTHY
        elif value <= thresholds["warning"]:
            return HealthStatus.WARNING
        else:
            return HealthStatus.DANGER


def calculate_metrics(data: SupplyChainInput) -> List[MetricResult]:
    """
    Calculateplace has Key Metrics
    """
    benchmarks = BENCHMARKS.get(data.platform, BENCHMARKS["amazon"])
    metrics = []
    
    # 1. Gross Margin
    gross_profit = data.selling_price - data.product_cost - data.shipping_cost_per_unit - data.fba_fee
    gross_margin = gross_profit / data.selling_price
    metrics.append(MetricResult(
        name="Gross Margin",
        value=round(gross_margin * 100, 1),
        unit="%",
        status=evaluate_status(gross_margin, benchmarks["gross_margin"], higher_is_better=True),
        benchmark=benchmarks["gross_margin"]["healthy"] * 100,
        description=f"(Selling Price - ProductCost - Inbound - FBAfee) / Selling Price"
    ))
    
    # 2. InboundProportion
    shipping_ratio = data.shipping_cost_per_unit / data.selling_price
    metrics.append(MetricResult(
        name="InboundProportion",
        value=round(shipping_ratio * 100, 1),
        unit="%",
        status=evaluate_status(shipping_ratio, benchmarks["shipping_ratio"], higher_is_better=False),
        benchmark=benchmarks["shipping_ratio"]["healthy"] * 100,
        description="InboundCost / Selling Price"
    ))
    
    # 3. Net Margin
    ad_cost = data.selling_price * data.ad_spend_ratio
    other_cost = data.selling_price * 0.05  # Other FeesEstimate 5%
    net_profit = gross_profit - data.storage_fee - ad_cost - other_cost
    net_margin = net_profit / data.selling_price
    metrics.append(MetricResult(
        name="Net Margin",
        value=round(net_margin * 100, 1),
        unit="%",
        status=evaluate_status(net_margin, benchmarks["net_margin"], higher_is_better=True),
        benchmark=benchmarks["net_margin"]["healthy"] * 100,
        description="Deduct allCost after Profit Margin"
    ))
    
    # 4. Inventory Days
    metrics.append(MetricResult(
        name="Inventoryweeksconvert",
        value=data.inventory_days,
        unit="days",
        status=evaluate_status(data.inventory_days, benchmarks["inventory_days"], higher_is_better=False),
        benchmark=benchmarks["inventory_days"]["healthy"],
        description="CurrentInventoryCanselldays"
    ))
    
    # 5. CashweeksconvertweeksPeriod
    cash_cycle = (
        data.production_days + 
        data.shipping_days + 
        data.inventory_days + 
        14  # AmazonPayment Cycle
        - data.supplier_payment_days
    )
    metrics.append(MetricResult(
        name="Cash Cycle",
        value=cash_cycle,
        unit="days",
        status=evaluate_status(cash_cycle, benchmarks["cash_cycle"], higher_is_better=False),
        benchmark=benchmarks["cash_cycle"]["healthy"],
        description=" from PaymentComplete payment cycleweeksPeriod"
    ))
    
    return metrics


def calculate_cost_breakdown(data: SupplyChainInput) -> Dict[str, float]:
    """
    CalculateCostStructure breakdown
    """
    ad_cost = data.selling_price * data.ad_spend_ratio
    other_cost = data.selling_price * 0.05
    
    net_profit = (
        data.selling_price 
        - data.product_cost 
        - data.shipping_cost_per_unit 
        - data.fba_fee 
        - data.storage_fee 
        - ad_cost 
        - other_cost
    )
    
    return {
        "selling_price": data.selling_price,
        "product_cost": data.product_cost,
        "shipping_cost": data.shipping_cost_per_unit,
        "fba_fee": data.fba_fee,
        "storage_fee": data.storage_fee,
        "ad_cost": round(ad_cost, 2),
        "other_cost": round(other_cost, 2),
        "net_profit": round(net_profit, 2),
        # Proportion
        "product_cost_ratio": round(data.product_cost / data.selling_price * 100, 1),
        "shipping_ratio": round(data.shipping_cost_per_unit / data.selling_price * 100, 1),
        "fba_ratio": round(data.fba_fee / data.selling_price * 100, 1),
        "storage_ratio": round(data.storage_fee / data.selling_price * 100, 1),
        "ad_ratio": round(ad_cost / data.selling_price * 100, 1),
        "net_margin": round(net_profit / data.selling_price * 100, 1)
    }


def diagnose_bottlenecks(data: SupplyChainInput, metrics: List[MetricResult]) -> List[BottleneckItem]:
    """
    DiagnoseBottleneckandSort
    """
    bottlenecks = []
    benchmarks = BENCHMARKS.get(data.platform, BENCHMARKS["amazon"])
    
    # Check each Metrics
    for metric in metrics:
        if metric.status == HealthStatus.DANGER:
            severity = "High"
            priority = 1
        elif metric.status == HealthStatus.WARNING:
            severity = " in "
            priority = 2
        else:
            continue  # HealthyNot addBottleneck
            
        # Based onMetricsCategoryTypeGenerateRecommendation
        if metric.name == "Inventoryweeksconvert":
            bottlenecks.append(BottleneckItem(
                priority=priority,
                severity=severity,
                title="Inventoryweeksconvert slow ",
                problem=f"Current {metric.value} days vs Recommendation <{benchmarks['inventory_days']['healthy']} days",
                impact="CapitalOccupyIncrease，MayGeneratePeriodStoragefee",
                suggestion="1. Clear slow-movingSKU 2. Set safetyInventoryFormula 3.  small BatchHigh frequencyRestock"
            ))
        elif metric.name == "Cash Cycle":
            bottlenecks.append(BottleneckItem(
                priority=priority,
                severity=severity,
                title="Cash Cycle ",
                problem=f"Current {metric.value} days vs Recommendation <{benchmarks['cash_cycle']['healthy']} days",
                impact="CapitalUtilizeeffectRate low ，ImpactExpansionCapability",
                suggestion="1. StriveSupplierPayment terms 2. shrink short Inventorydays 3. ConsiderSupply ChainFinance"
            ))
        elif metric.name == "InboundProportion":
            bottlenecks.append(BottleneckItem(
                priority=priority,
                severity=severity,
                title="LogisticsCost High",
                problem=f"Current {metric.value}% vs Recommendation <{benchmarks['shipping_ratio']['healthy']*100}%",
                impact="ErodeProfitempty",
                suggestion="1. Sea freightReplaceAir freight 2. LCL/Full containerOptimization 3. Compare multiple freight forwarders"
            ))
        elif metric.name == "Gross Margin":
            bottlenecks.append(BottleneckItem(
                priority=priority,
                severity=severity,
                title="Gross Marginbias low ",
                problem=f"Current {metric.value}% vs Recommendation >{benchmarks['gross_margin']['healthy']*100}%",
                impact="Risk resistanceCapabilityWeak，difficult to SupportAdvertisingInput",
                suggestion="1. Raise price or Optimizationlistingconvert 2. reduce low ProcurementCost 3. OptimizationProductCombo"
            ))
        elif metric.name == "Net Margin":
            bottlenecks.append(BottleneckItem(
                priority=priority,
                severity=severity,
                title="Net Margin  low ",
                problem=f"Current {metric.value}% vs Recommendation >{benchmarks['net_margin']['healthy']*100}%",
                impact="ProfitCapabilityWeak，BusinessCannotSustain",
                suggestion="1. OptimizationAdvertisingACOS 2. ControlStoragefee 3. Increase average order value"
            ))
    
    # CheckPeriodStoragefee
    if data.has_long_term_storage:
        bottlenecks.append(BottleneckItem(
            priority=2,
            severity=" in ",
            title="ExistPeriodStoragefee",
            problem="PartInventorysuper 365days",
            impact="amount outside CostExpenditure，CapitalWaste",
            suggestion="1. ExportLibraryageReport 2. On-site promotion clearanceInventory 3. Remove or destroy"
        ))
    
    #  by excellent first LevelSort
    bottlenecks.sort(key=lambda x: x.priority)
    
    return bottlenecks[:3]  #  only Return Top 3


def analyze(data: SupplyChainInput) -> AnalysisResult:
    """
    ExecuteCompleteAnalyze
    """
    metrics = calculate_metrics(data)
    cost_breakdown = calculate_cost_breakdown(data)
    bottlenecks = diagnose_bottlenecks(data, metrics)
    
    # GenerateSummary
    danger_count = sum(1 for m in metrics if m.status == HealthStatus.DANGER)
    warning_count = sum(1 for m in metrics if m.status == HealthStatus.WARNING)
    
    if danger_count > 0:
        summary = f"Found {danger_count} CriticalIssueNeedImmediatelyProcess"
    elif warning_count > 0:
        summary = f"Found {warning_count} potential in IssueRecommendationOptimization"
    else:
        summary = "Supply ChainOverallHealthy，CanAttentionSustainOptimization"
    
    return AnalysisResult(
        metrics=metrics,
        cost_breakdown=cost_breakdown,
        bottlenecks=bottlenecks,
        summary=summary
    )


# ============================================================
# OutputFormat
# ============================================================

def format_metrics_table(metrics: List[MetricResult]) -> str:
    """FormatMetricsTable"""
    status_icons = {
        HealthStatus.HEALTHY: "✅",
        HealthStatus.WARNING: "⚠️",
        HealthStatus.DANGER: "🔴"
    }
    
    lines = ["| Metrics | Value | Benchmark | Status |", "|------|------|------|------|"]
    for m in metrics:
        icon = status_icons[m.status]
        lines.append(f"| {m.name} | {m.value}{m.unit} | {m.benchmark}{m.unit} | {icon} |")
    
    return "\n".join(lines)


def format_cost_breakdown(breakdown: Dict[str, float]) -> str:
    """FormatCostBreakdown"""
    lines = [
        f"Selling Price            .2f   100%",
        "─────────────────────────────",
        f"ProductCost        -.2f    {breakdown['product_cost_ratio']}%",
        f"InboundLogistics        -.2f     {breakdown['shipping_ratio']}%",
        f"FBA Fulfillment      -.2f    {breakdown['fba_ratio']}%",
        f"FBA Storagefee      -.2f     {breakdown['storage_ratio']}%",
        f"Advertisingfee          -.2f    {breakdown['ad_ratio']}%",
        f"OtherFee        -.2f     5.0%",
        "─────────────────────────────",
        f"Net Profit          .2f     {breakdown['net_margin']}%"
    ]
    return "\n".join(lines)


def format_bottlenecks(bottlenecks: List[BottleneckItem]) -> str:
    """FormatBottleneckcolumnTable"""
    if not bottlenecks:
        return "✅ No obvious bottleneck found"
    
    lines = []
    priority_icons = {1: "🥇", 2: "🥈", 3: "🥉"}
    
    for i, b in enumerate(bottlenecks, 1):
        icon = priority_icons.get(i, "•")
        lines.append(f"\n{icon} **【{b.severity}】{b.title}**")
        lines.append(f"   Issue: {b.problem}")
        lines.append(f"   Impact: {b.impact}")
        lines.append(f"   Recommendation: {b.suggestion}")
    
    return "\n".join(lines)


def format_full_report(result: AnalysisResult) -> str:
    """GenerateCompleteReport"""
    report = f"""
🔍 **Supply ChainBottleneck DiagnosisReport**

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 **Key Metrics**

{format_metrics_table(result.metrics)}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💰 **CostStructure breakdown** ( each piece)

```
{format_cost_breakdown(result.cost_breakdown)}
```

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🎯 **Top 3 Bottleneck Diagnosis**

{format_bottlenecks(result.bottlenecks)}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 **Summary**: {result.summary}
"""
    return report


# ============================================================
# CLI Entry Point
# ============================================================

def main():
    """CLI Entry Point - use at Test"""
    import sys
    
    # ExampleData
    test_data = SupplyChainInput(
        product_cost=8.00,
        supplier_payment_days=0,
        production_days=25,
        shipping_cost_per_unit=0.75,
        shipping_days=35,
        selling_price=25.00,
        fba_fee=5.00,
        storage_fee=0.50,
        ad_spend_ratio=0.10,
        inventory_days=60,
        has_long_term_storage=True,
        platform="amazon"
    )
    
    # If JSON input provided
    if len(sys.argv) > 1:
        try:
            input_json = json.loads(sys.argv[1])
            test_data = SupplyChainInput(**input_json)
        except Exception as e:
            print(f"Error parsing input: {e}")
            sys.exit(1)
    
    # ExecuteAnalyze
    result = analyze(test_data)
    
    # OutputReport
    print(format_full_report(result))
    
    # Output JSON (For program call)
    # print(json.dumps({
    #     "metrics": [{"name": m.name, "value": m.value, "status": m.status.value} for m in result.metrics],
    #     "bottlenecks": [{"title": b.title, "severity": b.severity} for b in result.bottlenecks],
    #     "summary": result.summary
    # }, ensure_ascii=False, indent=2))


if __name__ == "__main__":
    main()

Supply Chain Optimization Tiktok

Skill

Supply Chain Bottleneck Analyzer for TikTok Shop sellers. Diagnose cash flow, inventory turnover, affiliate commissions, and return rates. Includes FBT cost...

---
name: supply-chain-optimization-tiktok
version: 1.0.0
description: "Supply Chain Bottleneck Analyzer for TikTok Shop sellers. Diagnose cash flow, inventory turnover, affiliate commissions, and return rates. Includes FBT cost analysis, influencer payout optimization, and viral product lifecycle management. No API key required for basic analysis."
metadata: {"nexscope":{"emoji":"📦","category":"ecommerce"}}
---

# Supply Chain Optimization — TikTok Shop 📦

Supply chain bottleneck analyzer for TikTok Shop sellers. Diagnose cash flow, inventory, affiliate costs, and return rates.

## Installation

```bash
npx skills add nexscope-ai/eCommerce-Skills --skill supply-chain-optimization-tiktok -g
```

## Platform Characteristics

| Feature | TikTok Shop | vs Amazon |
|---------|-------------|-----------|
| Fulfillment | FBT / Self-ship | FBA |
| Commission | 2-8% (category) + 2% transaction | 8-15% |
| Payment cycle | 7-15 days | 14 days |
| Traffic source | Content-driven | Search-driven |
| Return rate | Higher (impulse buying) | Medium |

## Cost Structure (TikTok Shop)

```
Selling Price $XX
├── Product Cost
├── Inbound Shipping
├── FBT Fulfillment / Self-ship
├── Platform Fee (2%)
├── Referral Fee (2-8%)
├── Affiliate Commission (10-30%)  ← TikTok-specific
├── Advertising (Spark Ads)
└── Net Profit
```

## Benchmark Configuration

```python
BENCHMARKS = {
    "tiktok": {
        "gross_margin": {
            "healthy": 0.45,    # Need to cover affiliate commission
            "warning": 0.35,
            "danger": 0.25
        },
        "shipping_ratio": {
            "healthy": 0.05,
            "warning": 0.08,
            "danger": 0.12
        },
        "inventory_days": {
            "healthy": 30,      # TikTok viral cycle is short
            "warning": 45,
            "danger": 60
        },
        "cash_cycle": {
            "healthy": 60,      # Fast payment
            "warning": 90,
            "danger": 120
        },
        "net_margin": {
            "healthy": 0.15,    # After affiliate split
            "warning": 0.08,
            "danger": 0.03
        },
        # TikTok-specific metrics
        "return_rate": {
            "healthy": 0.10,    # <10% healthy
            "warning": 0.20,
            "danger": 0.30
        },
        "affiliate_ratio": {
            "healthy": 0.20,    # Affiliate commission ratio
            "warning": 0.30,
            "danger": 0.40
        }
    }
}
```

## TikTok-Specific Costs

### Affiliate Commission

```
Livestream selling: 10-30% commission
Short video promotion: 10-25% commission
Top influencers: May require upfront fees
```

### Return Costs

```
TikTok return rates typically higher than traditional e-commerce (impulse buying)
Must account for:
├── Return shipping cost
├── Product damage/loss
└── Restocking fees
```

## Input Data

```
**Sales (TikTok-specific)**
• Average Selling Price: $___
• FBT Fulfillment Fee: $___/unit
• Platform Fee: 2% (fixed)
• Referral Fee: ___%
• Affiliate Commission Rate: ___% (if applicable)
• Spark Ads Spend Ratio: ___%

**Risk (TikTok-specific)**
• Return Rate: ___%
• Return Processing Cost: $___/unit
```

## API Integration

### TikTok Shop API

```bash
export TIKTOK_APP_KEY="xxx"
export TIKTOK_APP_SECRET="xxx"
export TIKTOK_ACCESS_TOKEN="xxx"
```

### Available Data

| Data | API |
|------|-----|
| Orders | Order API |
| Products | Product API |
| Logistics | Logistics API |
| Affiliates | Affiliate API |

## Bottleneck Diagnosis Focus

TikTok Shop-specific bottlenecks:

1. **High affiliate commission** → Profit erosion
2. **High return rate** → Hidden costs
3. **Slow inventory turnover** → Short viral cycle, high stagnation risk
4. **Content dependency** → Unstable traffic

## vs Amazon Comparison

| Item | Amazon | TikTok |
|------|--------|--------|
| Commission | 8-15% | 4-10% |
| Affiliate split | None | 10-30% |
| Payment cycle | 14 days | 7-15 days |
| Return rate | 5-15% | 10-30% |
| Traffic | Stable | Volatile |
| Viral cycle | Long | Short |

---

**Part of [Nexscope AI](https://www.nexscope.ai/) — AI tools for e-commerce sellers.**



FILE:scripts/calculator.py
#!/usr/bin/env python3
"""
Supply Chain Analyzer - Core Calculator
Supply Chain Analyzer - Core Calculator

Purpose: Calculate key metrics and diagnose bottlenecks
Version: 1.0.0
"""

import json
from dataclasses import dataclass
from typing import Optional, List, Dict
from enum import Enum


class HealthStatus(Enum):
    HEALTHY = "healthy"
    WARNING = "warning"
    DANGER = "danger"


# ============================================================
# Benchmark Configuration (customizable)
# ============================================================

BENCHMARKS = {
    "amazon": {
        "gross_margin": {
            "healthy": 0.40,    # >40% Healthy
            "warning": 0.30,    # 30-40% Warning
            "danger": 0.20      # <20% Danger
        },
        "shipping_ratio": {
            "healthy": 0.05,    # <5% Healthy
            "warning": 0.10,    # 5-10% Warning
            "danger": 0.15      # >15% Danger
        },
        "inventory_days": {
            "healthy": 45,      # <45days Healthy
            "warning": 60,      # 45-60days Warning
            "danger": 90        # >90days Danger
        },
        "cash_cycle": {
            "healthy": 90,      # <90days Healthy
            "warning": 120,     # 90-120days Warning
            "danger": 150       # >150days Danger
        },
        "net_margin": {
            "healthy": 0.20,    # >20% Healthy
            "warning": 0.10,    # 10-20% Warning
            "danger": 0.05      # <5% Danger
        }
    },
    "walmart": {
        "gross_margin": {
            "healthy": 0.35,    # Walmart Commission more  low 
            "warning": 0.25,
            "danger": 0.15
        },
        "shipping_ratio": {
            "healthy": 0.06,    # WFS ShippingSlightly higher
            "warning": 0.10,
            "danger": 0.15
        },
        "inventory_days": {
            "healthy": 45,
            "warning": 60,
            "danger": 90
        },
        "cash_cycle": {
            "healthy": 100,     # Payment CycleSlightly longer
            "warning": 130,
            "danger": 160
        },
        "net_margin": {
            "healthy": 0.18,
            "warning": 0.10,
            "danger": 0.05
        }
    },
    "tiktok": {
        "gross_margin": {
            "healthy": 0.45,    # NeedCoverInfluencerCommission
            "warning": 0.35,
            "danger": 0.25
        },
        "shipping_ratio": {
            "healthy": 0.05,
            "warning": 0.08,
            "danger": 0.12
        },
        "inventory_days": {
            "healthy": 30,      # TikTok Best sellerweeksPeriod short 
            "warning": 45,
            "danger": 60
        },
        "cash_cycle": {
            "healthy": 60,      # Fast payment
            "warning": 90,
            "danger": 120
        },
        "net_margin": {
            "healthy": 0.15,    # InfluencerShare after 
            "warning": 0.08,
            "danger": 0.03
        }
    },
    "shopify": {
        "gross_margin": {
            "healthy": 0.60,    # DTC Requires high gross marginAdvertising
            "warning": 0.50,
            "danger": 0.40
        },
        "shipping_ratio": {
            "healthy": 0.08,    # 3PL Fee
            "warning": 0.12,
            "danger": 0.18
        },
        "inventory_days": {
            "healthy": 45,
            "warning": 60,
            "danger": 90
        },
        "cash_cycle": {
            "healthy": 45,      # Fast payment (2-3days)
            "warning": 70,
            "danger": 100
        },
        "net_margin": {
            "healthy": 0.20,
            "warning": 0.12,
            "danger": 0.05
        }
    }
}


# ============================================================
# Data Structures
# ============================================================

@dataclass
class SupplyChainInput:
    """Supply ChainInput Data"""
    # Procurementend
    product_cost: float          # ProductCost (FOB)
    supplier_payment_days: int   # SupplierPayment terms (days)
    production_days: int         # ProductionweeksPeriod (days)
    
    # Logisticsend
    shipping_cost_per_unit: float  # Single pieceInboundCost
    shipping_days: int             # TransportTimeeffect (days)
    
    # Saleend
    selling_price: float         # Selling Price
    fba_fee: float              # FBA Fulfillment
    storage_fee: float          # monthsaverageStoragefee ( each piece)
    ad_spend_ratio: float       # AdvertisingfeeProportion (0-1)
    
    # Inventoryend
    inventory_days: int         # CurrentInventorydays
    has_long_term_storage: bool #  is no has PeriodStoragefee
    
    # Optional:  from  API Get
    daily_sales: Optional[float] = None      # DayAverage sales
    current_inventory: Optional[int] = None  # CurrentInventoryquantity
    
    # Platform
    platform: str = "amazon"


@dataclass
class MetricResult:
    """singleItemMetricsResult"""
    name: str
    value: float
    unit: str
    status: HealthStatus
    benchmark: float
    description: str


@dataclass 
class BottleneckItem:
    """BottleneckItem"""
    priority: int           # excellent first Level 1-3
    severity: str          # High/ in / low 
    title: str
    problem: str
    impact: str
    suggestion: str


@dataclass
class AnalysisResult:
    """AnalyzeResult"""
    metrics: List[MetricResult]
    cost_breakdown: Dict[str, float]
    bottlenecks: List[BottleneckItem]
    summary: str


# ============================================================
# CoreCalculateFunction
# ============================================================

def evaluate_status(value: float, thresholds: dict, higher_is_better: bool = True) -> HealthStatus:
    """
    EvaluateMetricsHealthyStatus
    
    Args:
        value: MetricsValue
        thresholds: ThresholdDictionary {"healthy": x, "warning": y, "danger": z}
        higher_is_better: True=ValueexceedHighexceed good , False=Valueexceed low exceed good 
    """
    if higher_is_better:
        if value >= thresholds["healthy"]:
            return HealthStatus.HEALTHY
        elif value >= thresholds["warning"]:
            return HealthStatus.WARNING
        else:
            return HealthStatus.DANGER
    else:
        if value <= thresholds["healthy"]:
            return HealthStatus.HEALTHY
        elif value <= thresholds["warning"]:
            return HealthStatus.WARNING
        else:
            return HealthStatus.DANGER


def calculate_metrics(data: SupplyChainInput) -> List[MetricResult]:
    """
    Calculateplace has Key Metrics
    """
    benchmarks = BENCHMARKS.get(data.platform, BENCHMARKS["amazon"])
    metrics = []
    
    # 1. Gross Margin
    gross_profit = data.selling_price - data.product_cost - data.shipping_cost_per_unit - data.fba_fee
    gross_margin = gross_profit / data.selling_price
    metrics.append(MetricResult(
        name="Gross Margin",
        value=round(gross_margin * 100, 1),
        unit="%",
        status=evaluate_status(gross_margin, benchmarks["gross_margin"], higher_is_better=True),
        benchmark=benchmarks["gross_margin"]["healthy"] * 100,
        description=f"(Selling Price - ProductCost - Inbound - FBAfee) / Selling Price"
    ))
    
    # 2. InboundProportion
    shipping_ratio = data.shipping_cost_per_unit / data.selling_price
    metrics.append(MetricResult(
        name="InboundProportion",
        value=round(shipping_ratio * 100, 1),
        unit="%",
        status=evaluate_status(shipping_ratio, benchmarks["shipping_ratio"], higher_is_better=False),
        benchmark=benchmarks["shipping_ratio"]["healthy"] * 100,
        description="InboundCost / Selling Price"
    ))
    
    # 3. Net Margin
    ad_cost = data.selling_price * data.ad_spend_ratio
    other_cost = data.selling_price * 0.05  # Other FeesEstimate 5%
    net_profit = gross_profit - data.storage_fee - ad_cost - other_cost
    net_margin = net_profit / data.selling_price
    metrics.append(MetricResult(
        name="Net Margin",
        value=round(net_margin * 100, 1),
        unit="%",
        status=evaluate_status(net_margin, benchmarks["net_margin"], higher_is_better=True),
        benchmark=benchmarks["net_margin"]["healthy"] * 100,
        description="Deduct allCost after Profit Margin"
    ))
    
    # 4. Inventory Days
    metrics.append(MetricResult(
        name="Inventoryweeksconvert",
        value=data.inventory_days,
        unit="days",
        status=evaluate_status(data.inventory_days, benchmarks["inventory_days"], higher_is_better=False),
        benchmark=benchmarks["inventory_days"]["healthy"],
        description="CurrentInventoryCanselldays"
    ))
    
    # 5. CashweeksconvertweeksPeriod
    cash_cycle = (
        data.production_days + 
        data.shipping_days + 
        data.inventory_days + 
        14  # AmazonPayment Cycle
        - data.supplier_payment_days
    )
    metrics.append(MetricResult(
        name="Cash Cycle",
        value=cash_cycle,
        unit="days",
        status=evaluate_status(cash_cycle, benchmarks["cash_cycle"], higher_is_better=False),
        benchmark=benchmarks["cash_cycle"]["healthy"],
        description=" from PaymentComplete payment cycleweeksPeriod"
    ))
    
    return metrics


def calculate_cost_breakdown(data: SupplyChainInput) -> Dict[str, float]:
    """
    CalculateCostStructure breakdown
    """
    ad_cost = data.selling_price * data.ad_spend_ratio
    other_cost = data.selling_price * 0.05
    
    net_profit = (
        data.selling_price 
        - data.product_cost 
        - data.shipping_cost_per_unit 
        - data.fba_fee 
        - data.storage_fee 
        - ad_cost 
        - other_cost
    )
    
    return {
        "selling_price": data.selling_price,
        "product_cost": data.product_cost,
        "shipping_cost": data.shipping_cost_per_unit,
        "fba_fee": data.fba_fee,
        "storage_fee": data.storage_fee,
        "ad_cost": round(ad_cost, 2),
        "other_cost": round(other_cost, 2),
        "net_profit": round(net_profit, 2),
        # Proportion
        "product_cost_ratio": round(data.product_cost / data.selling_price * 100, 1),
        "shipping_ratio": round(data.shipping_cost_per_unit / data.selling_price * 100, 1),
        "fba_ratio": round(data.fba_fee / data.selling_price * 100, 1),
        "storage_ratio": round(data.storage_fee / data.selling_price * 100, 1),
        "ad_ratio": round(ad_cost / data.selling_price * 100, 1),
        "net_margin": round(net_profit / data.selling_price * 100, 1)
    }


def diagnose_bottlenecks(data: SupplyChainInput, metrics: List[MetricResult]) -> List[BottleneckItem]:
    """
    DiagnoseBottleneckandSort
    """
    bottlenecks = []
    benchmarks = BENCHMARKS.get(data.platform, BENCHMARKS["amazon"])
    
    # Check each Metrics
    for metric in metrics:
        if metric.status == HealthStatus.DANGER:
            severity = "High"
            priority = 1
        elif metric.status == HealthStatus.WARNING:
            severity = " in "
            priority = 2
        else:
            continue  # HealthyNot addBottleneck
            
        # Based onMetricsCategoryTypeGenerateRecommendation
        if metric.name == "Inventoryweeksconvert":
            bottlenecks.append(BottleneckItem(
                priority=priority,
                severity=severity,
                title="Inventoryweeksconvert slow ",
                problem=f"Current {metric.value} days vs Recommendation <{benchmarks['inventory_days']['healthy']} days",
                impact="CapitalOccupyIncrease，MayGeneratePeriodStoragefee",
                suggestion="1. Clear slow-movingSKU 2. Set safetyInventoryFormula 3.  small BatchHigh frequencyRestock"
            ))
        elif metric.name == "Cash Cycle":
            bottlenecks.append(BottleneckItem(
                priority=priority,
                severity=severity,
                title="Cash Cycle ",
                problem=f"Current {metric.value} days vs Recommendation <{benchmarks['cash_cycle']['healthy']} days",
                impact="CapitalUtilizeeffectRate low ，ImpactExpansionCapability",
                suggestion="1. StriveSupplierPayment terms 2. shrink short Inventorydays 3. ConsiderSupply ChainFinance"
            ))
        elif metric.name == "InboundProportion":
            bottlenecks.append(BottleneckItem(
                priority=priority,
                severity=severity,
                title="LogisticsCost High",
                problem=f"Current {metric.value}% vs Recommendation <{benchmarks['shipping_ratio']['healthy']*100}%",
                impact="ErodeProfitempty",
                suggestion="1. Sea freightReplaceAir freight 2. LCL/Full containerOptimization 3. Compare multiple freight forwarders"
            ))
        elif metric.name == "Gross Margin":
            bottlenecks.append(BottleneckItem(
                priority=priority,
                severity=severity,
                title="Gross Marginbias low ",
                problem=f"Current {metric.value}% vs Recommendation >{benchmarks['gross_margin']['healthy']*100}%",
                impact="Risk resistanceCapabilityWeak，difficult to SupportAdvertisingInput",
                suggestion="1. Raise price or Optimizationlistingconvert 2. reduce low ProcurementCost 3. OptimizationProductCombo"
            ))
        elif metric.name == "Net Margin":
            bottlenecks.append(BottleneckItem(
                priority=priority,
                severity=severity,
                title="Net Margin  low ",
                problem=f"Current {metric.value}% vs Recommendation >{benchmarks['net_margin']['healthy']*100}%",
                impact="ProfitCapabilityWeak，BusinessCannotSustain",
                suggestion="1. OptimizationAdvertisingACOS 2. ControlStoragefee 3. Increase average order value"
            ))
    
    # CheckPeriodStoragefee
    if data.has_long_term_storage:
        bottlenecks.append(BottleneckItem(
            priority=2,
            severity=" in ",
            title="ExistPeriodStoragefee",
            problem="PartInventorysuper 365days",
            impact="amount outside CostExpenditure，CapitalWaste",
            suggestion="1. ExportLibraryageReport 2. On-site promotion clearanceInventory 3. Remove or destroy"
        ))
    
    #  by excellent first LevelSort
    bottlenecks.sort(key=lambda x: x.priority)
    
    return bottlenecks[:3]  #  only Return Top 3


def analyze(data: SupplyChainInput) -> AnalysisResult:
    """
    ExecuteCompleteAnalyze
    """
    metrics = calculate_metrics(data)
    cost_breakdown = calculate_cost_breakdown(data)
    bottlenecks = diagnose_bottlenecks(data, metrics)
    
    # GenerateSummary
    danger_count = sum(1 for m in metrics if m.status == HealthStatus.DANGER)
    warning_count = sum(1 for m in metrics if m.status == HealthStatus.WARNING)
    
    if danger_count > 0:
        summary = f"Found {danger_count} CriticalIssueNeedImmediatelyProcess"
    elif warning_count > 0:
        summary = f"Found {warning_count} potential in IssueRecommendationOptimization"
    else:
        summary = "Supply ChainOverallHealthy，CanAttentionSustainOptimization"
    
    return AnalysisResult(
        metrics=metrics,
        cost_breakdown=cost_breakdown,
        bottlenecks=bottlenecks,
        summary=summary
    )


# ============================================================
# OutputFormat
# ============================================================

def format_metrics_table(metrics: List[MetricResult]) -> str:
    """FormatMetricsTable"""
    status_icons = {
        HealthStatus.HEALTHY: "✅",
        HealthStatus.WARNING: "⚠️",
        HealthStatus.DANGER: "🔴"
    }
    
    lines = ["| Metrics | Value | Benchmark | Status |", "|------|------|------|------|"]
    for m in metrics:
        icon = status_icons[m.status]
        lines.append(f"| {m.name} | {m.value}{m.unit} | {m.benchmark}{m.unit} | {icon} |")
    
    return "\n".join(lines)


def format_cost_breakdown(breakdown: Dict[str, float]) -> str:
    """FormatCostBreakdown"""
    lines = [
        f"Selling Price            .2f   100%",
        "─────────────────────────────",
        f"ProductCost        -.2f    {breakdown['product_cost_ratio']}%",
        f"InboundLogistics        -.2f     {breakdown['shipping_ratio']}%",
        f"FBA Fulfillment      -.2f    {breakdown['fba_ratio']}%",
        f"FBA Storagefee      -.2f     {breakdown['storage_ratio']}%",
        f"Advertisingfee          -.2f    {breakdown['ad_ratio']}%",
        f"OtherFee        -.2f     5.0%",
        "─────────────────────────────",
        f"Net Profit          .2f     {breakdown['net_margin']}%"
    ]
    return "\n".join(lines)


def format_bottlenecks(bottlenecks: List[BottleneckItem]) -> str:
    """FormatBottleneckcolumnTable"""
    if not bottlenecks:
        return "✅ No obvious bottleneck found"
    
    lines = []
    priority_icons = {1: "🥇", 2: "🥈", 3: "🥉"}
    
    for i, b in enumerate(bottlenecks, 1):
        icon = priority_icons.get(i, "•")
        lines.append(f"\n{icon} **【{b.severity}】{b.title}**")
        lines.append(f"   Issue: {b.problem}")
        lines.append(f"   Impact: {b.impact}")
        lines.append(f"   Recommendation: {b.suggestion}")
    
    return "\n".join(lines)


def format_full_report(result: AnalysisResult) -> str:
    """GenerateCompleteReport"""
    report = f"""
🔍 **Supply ChainBottleneck DiagnosisReport**

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 **Key Metrics**

{format_metrics_table(result.metrics)}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💰 **CostStructure breakdown** ( each piece)

```
{format_cost_breakdown(result.cost_breakdown)}
```

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🎯 **Top 3 Bottleneck Diagnosis**

{format_bottlenecks(result.bottlenecks)}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 **Summary**: {result.summary}
"""
    return report


# ============================================================
# CLI Entry Point
# ============================================================

def main():
    """CLI Entry Point - use at Test"""
    import sys
    
    # ExampleData
    test_data = SupplyChainInput(
        product_cost=8.00,
        supplier_payment_days=0,
        production_days=25,
        shipping_cost_per_unit=0.75,
        shipping_days=35,
        selling_price=25.00,
        fba_fee=5.00,
        storage_fee=0.50,
        ad_spend_ratio=0.10,
        inventory_days=60,
        has_long_term_storage=True,
        platform="amazon"
    )
    
    # If JSON input provided
    if len(sys.argv) > 1:
        try:
            input_json = json.loads(sys.argv[1])
            test_data = SupplyChainInput(**input_json)
        except Exception as e:
            print(f"Error parsing input: {e}")
            sys.exit(1)
    
    # ExecuteAnalyze
    result = analyze(test_data)
    
    # OutputReport
    print(format_full_report(result))
    
    # Output JSON (For program call)
    # print(json.dumps({
    #     "metrics": [{"name": m.name, "value": m.value, "status": m.status.value} for m in result.metrics],
    #     "bottlenecks": [{"title": b.title, "severity": b.severity} for b in result.bottlenecks],
    #     "summary": result.summary
    # }, ensure_ascii=False, indent=2))


if __name__ == "__main__":
    main()

Supply Chain Optimization Shopify

Skill

Supply Chain Bottleneck Analyzer for Shopify/DTC stores. Diagnose cash flow, inventory, shipping costs, and customer acquisition efficiency. Includes CAC/LTV...

---
name: supply-chain-optimization-shopify
version: 1.0.0
description: "Supply Chain Bottleneck Analyzer for Shopify/DTC stores. Diagnose cash flow, inventory, shipping costs, and customer acquisition efficiency. Includes CAC/LTV analysis, 3PL cost optimization, and ad spend benchmarks. No API key required for basic analysis."
metadata: {"nexscope":{"emoji":"📦","category":"ecommerce"}}
---

# Supply Chain Optimization — Shopify/DTC 📦

Supply chain bottleneck analyzer for Shopify and Direct-to-Consumer stores. Diagnose cash flow, inventory, shipping, and customer acquisition costs.

## Installation

```bash
npx skills add nexscope-ai/eCommerce-Skills --skill supply-chain-optimization-shopify -g
```

## Platform Characteristics

| Feature | Shopify/DTC | vs Amazon |
|---------|-------------|-----------|
| Fulfillment | Self-select (ShipBob/self) | FBA |
| Platform fee | None | 8-15% |
| Payment fee | 2.9% + $0.30 | Included in fee |
| Payment cycle | 2-3 days | 14 days |
| Traffic cost | High (self-built) | Low (platform) |
| Data ownership | Full | Limited |

## Cost Structure (Shopify/DTC)

```
Selling Price $XX
├── Product Cost
├── Inbound Shipping (to warehouse)
├── 3PL Storage Fee (e.g., ShipBob)
├── 3PL Fulfillment Fee
├── Payment Processing (2.9% + $0.30)
├── Shopify Subscription (allocated)
├── Advertising (Meta/Google/TikTok) ← Key Cost
└── Net Profit
```

## Benchmark Configuration

```python
BENCHMARKS = {
    "shopify": {
        "gross_margin": {
            "healthy": 0.60,    # DTC needs high margin for ads
            "warning": 0.50,
            "danger": 0.40
        },
        "shipping_ratio": {
            "healthy": 0.08,    # 3PL fees
            "warning": 0.12,
            "danger": 0.18
        },
        "inventory_days": {
            "healthy": 45,
            "warning": 60,
            "danger": 90
        },
        "cash_cycle": {
            "healthy": 45,      # Fast payment
            "warning": 70,
            "danger": 100
        },
        "net_margin": {
            "healthy": 0.20,
            "warning": 0.12,
            "danger": 0.05
        },
        # DTC-specific metrics
        "cac": {               # Customer Acquisition Cost
            "healthy": 0.25,   # CAC < 25% of price
            "warning": 0.35,
            "danger": 0.50
        },
        "ltv_cac_ratio": {     # LTV/CAC
            "healthy": 3.0,    # LTV > 3x CAC
            "warning": 2.0,
            "danger": 1.0
        },
        "ad_spend_ratio": {    # Ad spend ratio
            "healthy": 0.25,
            "warning": 0.35,
            "danger": 0.45
        }
    }
}
```

## DTC-Specific Costs

### Advertising Costs (Critical!)

```
Meta Ads (Facebook/Instagram): CPM $10-30
Google Ads: CPC $1-5
TikTok Ads: CPM $5-15
Influencer Marketing: Variable

DTC ad spend typically 20-40% of revenue
```

### 3PL Logistics Costs

```
Common 3PL Options:
├── ShipBob
├── Deliverr
├── ShipMonk
└── Red Stag

Fee Structure:
├── Receiving: $2-5/case
├── Storage: $0.5-1/cubic ft/month
├── Pick & Pack: $2-4/order
└── Shipping: By weight/zone
```

### Payment Processing Fees

```
Shopify Payments: 2.9% + $0.30
PayPal: 2.9% + $0.30
Stripe: 2.9% + $0.30

High AOV: Ratio acceptable
Low AOV: Erodes profit
```

## Input Data

```
**Sales (Shopify-specific)**
• Average Selling Price: $___
• Average Order Value (AOV): $___
• Payment Fee: 2.9% + $0.30

**Logistics (3PL)**
• 3PL Fulfillment Fee: $___/order
• 3PL Storage Fee: $___/unit/month
• Receiving Fee: $___/case

**Marketing (Critical!)**
• Ad Spend Ratio: ___%
• Customer Acquisition Cost (CAC): $___
• Customer Lifetime Value (LTV): $___
• Repeat Purchase Rate: ___%
```

## API Integration

### Shopify Admin API

```bash
export SHOPIFY_STORE_URL="xxx.myshopify.com"
export SHOPIFY_ACCESS_TOKEN="xxx"
```

### Available Data

| Data | API |
|------|-----|
| Orders | Orders API |
| Products | Products API |
| Inventory | Inventory API |
| Customers | Customers API |

### 3PL API (e.g., ShipBob)

```bash
export SHIPBOB_API_TOKEN="xxx"
```

## Bottleneck Diagnosis Focus

DTC-specific bottlenecks:

1. **High CAC** → Low ad efficiency, acquisition cost eating profit
2. **LTV/CAC < 3** → Customer value insufficient to support CAC
3. **High 3PL costs** → Poor logistics choice
4. **Low repeat rate** → Reliant on new customers, high cost
5. **Low gross margin** → Cannot support ad spend

## DTC Health Formula

```
Net Profit = Price - Product Cost - Shipping - Payment Fee - Ad Spend - Ops Cost

DTC Golden Ratios:
├── Gross Margin > 60%
├── Ad Spend < 30%
├── Shipping < 15%
├── Net Margin > 15%
└── LTV/CAC > 3
```

## vs Amazon Comparison

| Item | Amazon | Shopify/DTC |
|------|--------|-------------|
| Platform fee | 8-15% | 0% |
| Payment fee | Included | 2.9% + $0.30 |
| Payment cycle | 14 days | 2-3 days |
| Ad spend | 10-20% | 20-40% |
| Traffic | Platform | Self-built |
| Margin need | 40%+ | 60%+ |
| Data | Limited | Full ownership |

---

**Part of [Nexscope AI](https://www.nexscope.ai/) — AI tools for e-commerce sellers.**



FILE:scripts/calculator.py
#!/usr/bin/env python3
"""
Supply Chain Analyzer - Core Calculator
Supply Chain Analyzer - Core Calculator

Purpose: Calculate key metrics and diagnose bottlenecks
Version: 1.0.0
"""

import json
from dataclasses import dataclass
from typing import Optional, List, Dict
from enum import Enum


class HealthStatus(Enum):
    HEALTHY = "healthy"
    WARNING = "warning"
    DANGER = "danger"


# ============================================================
# Benchmark Configuration (customizable)
# ============================================================

BENCHMARKS = {
    "amazon": {
        "gross_margin": {
            "healthy": 0.40,    # >40% Healthy
            "warning": 0.30,    # 30-40% Warning
            "danger": 0.20      # <20% Danger
        },
        "shipping_ratio": {
            "healthy": 0.05,    # <5% Healthy
            "warning": 0.10,    # 5-10% Warning
            "danger": 0.15      # >15% Danger
        },
        "inventory_days": {
            "healthy": 45,      # <45days Healthy
            "warning": 60,      # 45-60days Warning
            "danger": 90        # >90days Danger
        },
        "cash_cycle": {
            "healthy": 90,      # <90days Healthy
            "warning": 120,     # 90-120days Warning
            "danger": 150       # >150days Danger
        },
        "net_margin": {
            "healthy": 0.20,    # >20% Healthy
            "warning": 0.10,    # 10-20% Warning
            "danger": 0.05      # <5% Danger
        }
    },
    "walmart": {
        "gross_margin": {
            "healthy": 0.35,    # Walmart Commission more  low 
            "warning": 0.25,
            "danger": 0.15
        },
        "shipping_ratio": {
            "healthy": 0.06,    # WFS ShippingSlightly higher
            "warning": 0.10,
            "danger": 0.15
        },
        "inventory_days": {
            "healthy": 45,
            "warning": 60,
            "danger": 90
        },
        "cash_cycle": {
            "healthy": 100,     # Payment CycleSlightly longer
            "warning": 130,
            "danger": 160
        },
        "net_margin": {
            "healthy": 0.18,
            "warning": 0.10,
            "danger": 0.05
        }
    },
    "tiktok": {
        "gross_margin": {
            "healthy": 0.45,    # NeedCoverInfluencerCommission
            "warning": 0.35,
            "danger": 0.25
        },
        "shipping_ratio": {
            "healthy": 0.05,
            "warning": 0.08,
            "danger": 0.12
        },
        "inventory_days": {
            "healthy": 30,      # TikTok Best sellerweeksPeriod short 
            "warning": 45,
            "danger": 60
        },
        "cash_cycle": {
            "healthy": 60,      # Fast payment
            "warning": 90,
            "danger": 120
        },
        "net_margin": {
            "healthy": 0.15,    # InfluencerShare after 
            "warning": 0.08,
            "danger": 0.03
        }
    },
    "shopify": {
        "gross_margin": {
            "healthy": 0.60,    # DTC Requires high gross marginAdvertising
            "warning": 0.50,
            "danger": 0.40
        },
        "shipping_ratio": {
            "healthy": 0.08,    # 3PL Fee
            "warning": 0.12,
            "danger": 0.18
        },
        "inventory_days": {
            "healthy": 45,
            "warning": 60,
            "danger": 90
        },
        "cash_cycle": {
            "healthy": 45,      # Fast payment (2-3days)
            "warning": 70,
            "danger": 100
        },
        "net_margin": {
            "healthy": 0.20,
            "warning": 0.12,
            "danger": 0.05
        }
    }
}


# ============================================================
# Data Structures
# ============================================================

@dataclass
class SupplyChainInput:
    """Supply ChainInput Data"""
    # Procurementend
    product_cost: float          # ProductCost (FOB)
    supplier_payment_days: int   # SupplierPayment terms (days)
    production_days: int         # ProductionweeksPeriod (days)
    
    # Logisticsend
    shipping_cost_per_unit: float  # Single pieceInboundCost
    shipping_days: int             # TransportTimeeffect (days)
    
    # Saleend
    selling_price: float         # Selling Price
    fba_fee: float              # FBA Fulfillment
    storage_fee: float          # monthsaverageStoragefee ( each piece)
    ad_spend_ratio: float       # AdvertisingfeeProportion (0-1)
    
    # Inventoryend
    inventory_days: int         # CurrentInventorydays
    has_long_term_storage: bool #  is no has PeriodStoragefee
    
    # Optional:  from  API Get
    daily_sales: Optional[float] = None      # DayAverage sales
    current_inventory: Optional[int] = None  # CurrentInventoryquantity
    
    # Platform
    platform: str = "amazon"


@dataclass
class MetricResult:
    """singleItemMetricsResult"""
    name: str
    value: float
    unit: str
    status: HealthStatus
    benchmark: float
    description: str


@dataclass 
class BottleneckItem:
    """BottleneckItem"""
    priority: int           # excellent first Level 1-3
    severity: str          # High/ in / low 
    title: str
    problem: str
    impact: str
    suggestion: str


@dataclass
class AnalysisResult:
    """AnalyzeResult"""
    metrics: List[MetricResult]
    cost_breakdown: Dict[str, float]
    bottlenecks: List[BottleneckItem]
    summary: str


# ============================================================
# CoreCalculateFunction
# ============================================================

def evaluate_status(value: float, thresholds: dict, higher_is_better: bool = True) -> HealthStatus:
    """
    EvaluateMetricsHealthyStatus
    
    Args:
        value: MetricsValue
        thresholds: ThresholdDictionary {"healthy": x, "warning": y, "danger": z}
        higher_is_better: True=ValueexceedHighexceed good , False=Valueexceed low exceed good 
    """
    if higher_is_better:
        if value >= thresholds["healthy"]:
            return HealthStatus.HEALTHY
        elif value >= thresholds["warning"]:
            return HealthStatus.WARNING
        else:
            return HealthStatus.DANGER
    else:
        if value <= thresholds["healthy"]:
            return HealthStatus.HEALTHY
        elif value <= thresholds["warning"]:
            return HealthStatus.WARNING
        else:
            return HealthStatus.DANGER


def calculate_metrics(data: SupplyChainInput) -> List[MetricResult]:
    """
    Calculateplace has Key Metrics
    """
    benchmarks = BENCHMARKS.get(data.platform, BENCHMARKS["amazon"])
    metrics = []
    
    # 1. Gross Margin
    gross_profit = data.selling_price - data.product_cost - data.shipping_cost_per_unit - data.fba_fee
    gross_margin = gross_profit / data.selling_price
    metrics.append(MetricResult(
        name="Gross Margin",
        value=round(gross_margin * 100, 1),
        unit="%",
        status=evaluate_status(gross_margin, benchmarks["gross_margin"], higher_is_better=True),
        benchmark=benchmarks["gross_margin"]["healthy"] * 100,
        description=f"(Selling Price - ProductCost - Inbound - FBAfee) / Selling Price"
    ))
    
    # 2. InboundProportion
    shipping_ratio = data.shipping_cost_per_unit / data.selling_price
    metrics.append(MetricResult(
        name="InboundProportion",
        value=round(shipping_ratio * 100, 1),
        unit="%",
        status=evaluate_status(shipping_ratio, benchmarks["shipping_ratio"], higher_is_better=False),
        benchmark=benchmarks["shipping_ratio"]["healthy"] * 100,
        description="InboundCost / Selling Price"
    ))
    
    # 3. Net Margin
    ad_cost = data.selling_price * data.ad_spend_ratio
    other_cost = data.selling_price * 0.05  # Other FeesEstimate 5%
    net_profit = gross_profit - data.storage_fee - ad_cost - other_cost
    net_margin = net_profit / data.selling_price
    metrics.append(MetricResult(
        name="Net Margin",
        value=round(net_margin * 100, 1),
        unit="%",
        status=evaluate_status(net_margin, benchmarks["net_margin"], higher_is_better=True),
        benchmark=benchmarks["net_margin"]["healthy"] * 100,
        description="Deduct allCost after Profit Margin"
    ))
    
    # 4. Inventory Days
    metrics.append(MetricResult(
        name="Inventoryweeksconvert",
        value=data.inventory_days,
        unit="days",
        status=evaluate_status(data.inventory_days, benchmarks["inventory_days"], higher_is_better=False),
        benchmark=benchmarks["inventory_days"]["healthy"],
        description="CurrentInventoryCanselldays"
    ))
    
    # 5. CashweeksconvertweeksPeriod
    cash_cycle = (
        data.production_days + 
        data.shipping_days + 
        data.inventory_days + 
        14  # AmazonPayment Cycle
        - data.supplier_payment_days
    )
    metrics.append(MetricResult(
        name="Cash Cycle",
        value=cash_cycle,
        unit="days",
        status=evaluate_status(cash_cycle, benchmarks["cash_cycle"], higher_is_better=False),
        benchmark=benchmarks["cash_cycle"]["healthy"],
        description=" from PaymentComplete payment cycleweeksPeriod"
    ))
    
    return metrics


def calculate_cost_breakdown(data: SupplyChainInput) -> Dict[str, float]:
    """
    CalculateCostStructure breakdown
    """
    ad_cost = data.selling_price * data.ad_spend_ratio
    other_cost = data.selling_price * 0.05
    
    net_profit = (
        data.selling_price 
        - data.product_cost 
        - data.shipping_cost_per_unit 
        - data.fba_fee 
        - data.storage_fee 
        - ad_cost 
        - other_cost
    )
    
    return {
        "selling_price": data.selling_price,
        "product_cost": data.product_cost,
        "shipping_cost": data.shipping_cost_per_unit,
        "fba_fee": data.fba_fee,
        "storage_fee": data.storage_fee,
        "ad_cost": round(ad_cost, 2),
        "other_cost": round(other_cost, 2),
        "net_profit": round(net_profit, 2),
        # Proportion
        "product_cost_ratio": round(data.product_cost / data.selling_price * 100, 1),
        "shipping_ratio": round(data.shipping_cost_per_unit / data.selling_price * 100, 1),
        "fba_ratio": round(data.fba_fee / data.selling_price * 100, 1),
        "storage_ratio": round(data.storage_fee / data.selling_price * 100, 1),
        "ad_ratio": round(ad_cost / data.selling_price * 100, 1),
        "net_margin": round(net_profit / data.selling_price * 100, 1)
    }


def diagnose_bottlenecks(data: SupplyChainInput, metrics: List[MetricResult]) -> List[BottleneckItem]:
    """
    DiagnoseBottleneckandSort
    """
    bottlenecks = []
    benchmarks = BENCHMARKS.get(data.platform, BENCHMARKS["amazon"])
    
    # Check each Metrics
    for metric in metrics:
        if metric.status == HealthStatus.DANGER:
            severity = "High"
            priority = 1
        elif metric.status == HealthStatus.WARNING:
            severity = " in "
            priority = 2
        else:
            continue  # HealthyNot addBottleneck
            
        # Based onMetricsCategoryTypeGenerateRecommendation
        if metric.name == "Inventoryweeksconvert":
            bottlenecks.append(BottleneckItem(
                priority=priority,
                severity=severity,
                title="Inventoryweeksconvert slow ",
                problem=f"Current {metric.value} days vs Recommendation <{benchmarks['inventory_days']['healthy']} days",
                impact="CapitalOccupyIncrease，MayGeneratePeriodStoragefee",
                suggestion="1. Clear slow-movingSKU 2. Set safetyInventoryFormula 3.  small BatchHigh frequencyRestock"
            ))
        elif metric.name == "Cash Cycle":
            bottlenecks.append(BottleneckItem(
                priority=priority,
                severity=severity,
                title="Cash Cycle ",
                problem=f"Current {metric.value} days vs Recommendation <{benchmarks['cash_cycle']['healthy']} days",
                impact="CapitalUtilizeeffectRate low ，ImpactExpansionCapability",
                suggestion="1. StriveSupplierPayment terms 2. shrink short Inventorydays 3. ConsiderSupply ChainFinance"
            ))
        elif metric.name == "InboundProportion":
            bottlenecks.append(BottleneckItem(
                priority=priority,
                severity=severity,
                title="LogisticsCost High",
                problem=f"Current {metric.value}% vs Recommendation <{benchmarks['shipping_ratio']['healthy']*100}%",
                impact="ErodeProfitempty",
                suggestion="1. Sea freightReplaceAir freight 2. LCL/Full containerOptimization 3. Compare multiple freight forwarders"
            ))
        elif metric.name == "Gross Margin":
            bottlenecks.append(BottleneckItem(
                priority=priority,
                severity=severity,
                title="Gross Marginbias low ",
                problem=f"Current {metric.value}% vs Recommendation >{benchmarks['gross_margin']['healthy']*100}%",
                impact="Risk resistanceCapabilityWeak，difficult to SupportAdvertisingInput",
                suggestion="1. Raise price or Optimizationlistingconvert 2. reduce low ProcurementCost 3. OptimizationProductCombo"
            ))
        elif metric.name == "Net Margin":
            bottlenecks.append(BottleneckItem(
                priority=priority,
                severity=severity,
                title="Net Margin  low ",
                problem=f"Current {metric.value}% vs Recommendation >{benchmarks['net_margin']['healthy']*100}%",
                impact="ProfitCapabilityWeak，BusinessCannotSustain",
                suggestion="1. OptimizationAdvertisingACOS 2. ControlStoragefee 3. Increase average order value"
            ))
    
    # CheckPeriodStoragefee
    if data.has_long_term_storage:
        bottlenecks.append(BottleneckItem(
            priority=2,
            severity=" in ",
            title="ExistPeriodStoragefee",
            problem="PartInventorysuper 365days",
            impact="amount outside CostExpenditure，CapitalWaste",
            suggestion="1. ExportLibraryageReport 2. On-site promotion clearanceInventory 3. Remove or destroy"
        ))
    
    #  by excellent first LevelSort
    bottlenecks.sort(key=lambda x: x.priority)
    
    return bottlenecks[:3]  #  only Return Top 3


def analyze(data: SupplyChainInput) -> AnalysisResult:
    """
    ExecuteCompleteAnalyze
    """
    metrics = calculate_metrics(data)
    cost_breakdown = calculate_cost_breakdown(data)
    bottlenecks = diagnose_bottlenecks(data, metrics)
    
    # GenerateSummary
    danger_count = sum(1 for m in metrics if m.status == HealthStatus.DANGER)
    warning_count = sum(1 for m in metrics if m.status == HealthStatus.WARNING)
    
    if danger_count > 0:
        summary = f"Found {danger_count} CriticalIssueNeedImmediatelyProcess"
    elif warning_count > 0:
        summary = f"Found {warning_count} potential in IssueRecommendationOptimization"
    else:
        summary = "Supply ChainOverallHealthy，CanAttentionSustainOptimization"
    
    return AnalysisResult(
        metrics=metrics,
        cost_breakdown=cost_breakdown,
        bottlenecks=bottlenecks,
        summary=summary
    )


# ============================================================
# OutputFormat
# ============================================================

def format_metrics_table(metrics: List[MetricResult]) -> str:
    """FormatMetricsTable"""
    status_icons = {
        HealthStatus.HEALTHY: "✅",
        HealthStatus.WARNING: "⚠️",
        HealthStatus.DANGER: "🔴"
    }
    
    lines = ["| Metrics | Value | Benchmark | Status |", "|------|------|------|------|"]
    for m in metrics:
        icon = status_icons[m.status]
        lines.append(f"| {m.name} | {m.value}{m.unit} | {m.benchmark}{m.unit} | {icon} |")
    
    return "\n".join(lines)


def format_cost_breakdown(breakdown: Dict[str, float]) -> str:
    """FormatCostBreakdown"""
    lines = [
        f"Selling Price            .2f   100%",
        "─────────────────────────────",
        f"ProductCost        -.2f    {breakdown['product_cost_ratio']}%",
        f"InboundLogistics        -.2f     {breakdown['shipping_ratio']}%",
        f"FBA Fulfillment      -.2f    {breakdown['fba_ratio']}%",
        f"FBA Storagefee      -.2f     {breakdown['storage_ratio']}%",
        f"Advertisingfee          -.2f    {breakdown['ad_ratio']}%",
        f"OtherFee        -.2f     5.0%",
        "─────────────────────────────",
        f"Net Profit          .2f     {breakdown['net_margin']}%"
    ]
    return "\n".join(lines)


def format_bottlenecks(bottlenecks: List[BottleneckItem]) -> str:
    """FormatBottleneckcolumnTable"""
    if not bottlenecks:
        return "✅ No obvious bottleneck found"
    
    lines = []
    priority_icons = {1: "🥇", 2: "🥈", 3: "🥉"}
    
    for i, b in enumerate(bottlenecks, 1):
        icon = priority_icons.get(i, "•")
        lines.append(f"\n{icon} **【{b.severity}】{b.title}**")
        lines.append(f"   Issue: {b.problem}")
        lines.append(f"   Impact: {b.impact}")
        lines.append(f"   Recommendation: {b.suggestion}")
    
    return "\n".join(lines)


def format_full_report(result: AnalysisResult) -> str:
    """GenerateCompleteReport"""
    report = f"""
🔍 **Supply ChainBottleneck DiagnosisReport**

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 **Key Metrics**

{format_metrics_table(result.metrics)}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💰 **CostStructure breakdown** ( each piece)

```
{format_cost_breakdown(result.cost_breakdown)}
```

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🎯 **Top 3 Bottleneck Diagnosis**

{format_bottlenecks(result.bottlenecks)}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 **Summary**: {result.summary}
"""
    return report


# ============================================================
# CLI Entry Point
# ============================================================

def main():
    """CLI Entry Point - use at Test"""
    import sys
    
    # ExampleData
    test_data = SupplyChainInput(
        product_cost=8.00,
        supplier_payment_days=0,
        production_days=25,
        shipping_cost_per_unit=0.75,
        shipping_days=35,
        selling_price=25.00,
        fba_fee=5.00,
        storage_fee=0.50,
        ad_spend_ratio=0.10,
        inventory_days=60,
        has_long_term_storage=True,
        platform="amazon"
    )
    
    # If JSON input provided
    if len(sys.argv) > 1:
        try:
            input_json = json.loads(sys.argv[1])
            test_data = SupplyChainInput(**input_json)
        except Exception as e:
            print(f"Error parsing input: {e}")
            sys.exit(1)
    
    # ExecuteAnalyze
    result = analyze(test_data)
    
    # OutputReport
    print(format_full_report(result))
    
    # Output JSON (For program call)
    # print(json.dumps({
    #     "metrics": [{"name": m.name, "value": m.value, "status": m.status.value} for m in result.metrics],
    #     "bottlenecks": [{"title": b.title, "severity": b.severity} for b in result.bottlenecks],
    #     "summary": result.summary
    # }, ensure_ascii=False, indent=2))


if __name__ == "__main__":
    main()

Supply Chain Optimization Amazon Lite

Skill

Supply Chain Optimization (Lite) - Diagnose bottlenecks and provide cost reduction strategies through conversation

---
name: supply-chain-optimization-amazon-lite
version: 1.0.0
description: Supply Chain Optimization (Lite) - Diagnose bottlenecks and provide cost reduction strategies through conversation
platform: amazon
lang: en
---

# Supply Chain Optimization (Lite)

Supply chain bottleneck analysis tool - Conversation-based version

No API integration required. Collect data through guided conversation, automatically diagnose bottlenecks and output cost reduction strategies.

## Use Cases

- Amazon seller supply chain health check
- Bottleneck identification and cost optimization
- Supply chain decision support

## Workflow

### Step 1: Trigger Skill

User says:
```
Analyze my supply chain
Supply chain diagnosis
I want to optimize supply chain costs
```

### Step 2: Business Profile Collection

Guide user to describe in natural language:

```
👋 Starting Supply Chain Analysis

Please describe your situation in a sentence or two, like:
"I sell kitchen products, 15 SKUs, $50K monthly sales, sourcing from Yiwu, sea freight to FBA, shipping costs seem high"

Or just tell me what problem you want to solve.
```

**Identify and confirm:**
- Category
- SKU count
- Monthly revenue scale
- Sourcing location
- Logistics model
- Main pain points

### Step 3: Supply Chain Data Collection

Guide user to provide key data:

```
📊 I need some data to locate bottlenecks (rough numbers are fine)

**Sourcing**
• Product cost (FOB): $___/unit
• Supplier payment terms: ___ days
• Lead time: ___ days

**Logistics**
• Shipping cost per unit: $___
• Transit time: ___ days

**Sales**
• Average selling price: $___
• FBA fulfillment fee: $___/unit
• Monthly storage fee: $___/unit
• Ad spend ratio: ___%

**Inventory**
• Current inventory days: ___ days
• Long-term storage fees: Yes/No

Just reply in natural language.
```

### Step 4: Bottleneck Diagnosis

Run calculation script:

```bash
python3 scripts/calculator.py '{"product_cost": 8, "supplier_payment_days": 0, ...}'
```

Output diagnosis report:
- Key metrics table (with health status)
- Cost structure breakdown
- Top 3 bottlenecks

### Step 5: Cost Reduction Strategies

For each bottleneck provide:
- Problem description
- Impact analysis
- Specific recommendations
- Action checklist

### Step 6: Output Format Selection

```
📤 Analysis complete! Choose output format:

1️⃣ **Text** - View in current conversation (already shown)
2️⃣ **Web Chart** - Generate visual report webpage
3️⃣ **Report Doc** - Document format for sharing/presentation

Reply with number or say "generate web report"
```

---

## Benchmark Configuration

The following benchmarks can be customized based on your business:

| Metric | Healthy | Warning | Danger |
|--------|---------|---------|--------|
| Gross Margin | >40% | 30-40% | <30% |
| Shipping Ratio | <5% | 5-10% | >10% |
| Net Margin | >20% | 10-20% | <10% |
| Inventory Turnover | <45 days | 45-60 days | >60 days |
| Cash Cycle | <90 days | 90-120 days | >120 days |

To adjust, modify `BENCHMARKS` in `scripts/calculator.py`.

---

## File Structure

```
amazon-lite/
├── SKILL.md          # Index (this file)
├── SKILL.en.md       # English version
├── SKILL.zh-CN.md    # Chinese version
├── _meta.json
└── scripts/
    └── calculator.py
```

---

_Version 1.0.0 | Platform: Amazon | Lang: English_

---

**Part of [Nexscope AI](https://www.nexscope.ai/) — AI tools for e-commerce sellers.**


FILE:scripts/calculator.py
#!/usr/bin/env python3
"""
Supply Chain Analyzer - Core Calculator
Supply Chain Analyzer - Core Calculator

Purpose: Calculate key metrics and diagnose bottlenecks
Version: 1.0.0
"""

import json
from dataclasses import dataclass
from typing import Optional, List, Dict
from enum import Enum


class HealthStatus(Enum):
    HEALTHY = "healthy"
    WARNING = "warning"
    DANGER = "danger"


# ============================================================
# Benchmark Configuration (customizable)
# ============================================================

BENCHMARKS = {
    "amazon": {
        "gross_margin": {
            "healthy": 0.40,    # >40% Healthy
            "warning": 0.30,    # 30-40% Warning
            "danger": 0.20      # <20% Danger
        },
        "shipping_ratio": {
            "healthy": 0.05,    # <5% Healthy
            "warning": 0.10,    # 5-10% Warning
            "danger": 0.15      # >15% Danger
        },
        "inventory_days": {
            "healthy": 45,      # <45days Healthy
            "warning": 60,      # 45-60days Warning
            "danger": 90        # >90days Danger
        },
        "cash_cycle": {
            "healthy": 90,      # <90days Healthy
            "warning": 120,     # 90-120days Warning
            "danger": 150       # >150days Danger
        },
        "net_margin": {
            "healthy": 0.20,    # >20% Healthy
            "warning": 0.10,    # 10-20% Warning
            "danger": 0.05      # <5% Danger
        }
    },
    "walmart": {
        "gross_margin": {
            "healthy": 0.35,    # Walmart Commission more  low 
            "warning": 0.25,
            "danger": 0.15
        },
        "shipping_ratio": {
            "healthy": 0.06,    # WFS ShippingSlightly higher
            "warning": 0.10,
            "danger": 0.15
        },
        "inventory_days": {
            "healthy": 45,
            "warning": 60,
            "danger": 90
        },
        "cash_cycle": {
            "healthy": 100,     # Payment CycleSlightly longer
            "warning": 130,
            "danger": 160
        },
        "net_margin": {
            "healthy": 0.18,
            "warning": 0.10,
            "danger": 0.05
        }
    },
    "tiktok": {
        "gross_margin": {
            "healthy": 0.45,    # NeedCoverInfluencerCommission
            "warning": 0.35,
            "danger": 0.25
        },
        "shipping_ratio": {
            "healthy": 0.05,
            "warning": 0.08,
            "danger": 0.12
        },
        "inventory_days": {
            "healthy": 30,      # TikTok Best sellerweeksPeriod short 
            "warning": 45,
            "danger": 60
        },
        "cash_cycle": {
            "healthy": 60,      # Fast payment
            "warning": 90,
            "danger": 120
        },
        "net_margin": {
            "healthy": 0.15,    # InfluencerShare after 
            "warning": 0.08,
            "danger": 0.03
        }
    },
    "shopify": {
        "gross_margin": {
            "healthy": 0.60,    # DTC Requires high gross marginAdvertising
            "warning": 0.50,
            "danger": 0.40
        },
        "shipping_ratio": {
            "healthy": 0.08,    # 3PL Fee
            "warning": 0.12,
            "danger": 0.18
        },
        "inventory_days": {
            "healthy": 45,
            "warning": 60,
            "danger": 90
        },
        "cash_cycle": {
            "healthy": 45,      # Fast payment (2-3days)
            "warning": 70,
            "danger": 100
        },
        "net_margin": {
            "healthy": 0.20,
            "warning": 0.12,
            "danger": 0.05
        }
    }
}


# ============================================================
# Data Structures
# ============================================================

@dataclass
class SupplyChainInput:
    """Supply ChainInput Data"""
    # Procurementend
    product_cost: float          # ProductCost (FOB)
    supplier_payment_days: int   # SupplierPayment terms (days)
    production_days: int         # ProductionweeksPeriod (days)
    
    # Logisticsend
    shipping_cost_per_unit: float  # Single pieceInboundCost
    shipping_days: int             # TransportTimeeffect (days)
    
    # Saleend
    selling_price: float         # Selling Price
    fba_fee: float              # FBA Fulfillment
    storage_fee: float          # monthsaverageStoragefee ( each piece)
    ad_spend_ratio: float       # AdvertisingfeeProportion (0-1)
    
    # Inventoryend
    inventory_days: int         # CurrentInventorydays
    has_long_term_storage: bool #  is no has PeriodStoragefee
    
    # Optional:  from  API Get
    daily_sales: Optional[float] = None      # DayAverage sales
    current_inventory: Optional[int] = None  # CurrentInventoryquantity
    
    # Platform
    platform: str = "amazon"


@dataclass
class MetricResult:
    """singleItemMetricsResult"""
    name: str
    value: float
    unit: str
    status: HealthStatus
    benchmark: float
    description: str


@dataclass 
class BottleneckItem:
    """BottleneckItem"""
    priority: int           # excellent first Level 1-3
    severity: str          # High/ in / low 
    title: str
    problem: str
    impact: str
    suggestion: str


@dataclass
class AnalysisResult:
    """AnalyzeResult"""
    metrics: List[MetricResult]
    cost_breakdown: Dict[str, float]
    bottlenecks: List[BottleneckItem]
    summary: str


# ============================================================
# CoreCalculateFunction
# ============================================================

def evaluate_status(value: float, thresholds: dict, higher_is_better: bool = True) -> HealthStatus:
    """
    EvaluateMetricsHealthyStatus
    
    Args:
        value: MetricsValue
        thresholds: ThresholdDictionary {"healthy": x, "warning": y, "danger": z}
        higher_is_better: True=ValueexceedHighexceed good , False=Valueexceed low exceed good 
    """
    if higher_is_better:
        if value >= thresholds["healthy"]:
            return HealthStatus.HEALTHY
        elif value >= thresholds["warning"]:
            return HealthStatus.WARNING
        else:
            return HealthStatus.DANGER
    else:
        if value <= thresholds["healthy"]:
            return HealthStatus.HEALTHY
        elif value <= thresholds["warning"]:
            return HealthStatus.WARNING
        else:
            return HealthStatus.DANGER


def calculate_metrics(data: SupplyChainInput) -> List[MetricResult]:
    """
    Calculateplace has Key Metrics
    """
    benchmarks = BENCHMARKS.get(data.platform, BENCHMARKS["amazon"])
    metrics = []
    
    # 1. Gross Margin
    gross_profit = data.selling_price - data.product_cost - data.shipping_cost_per_unit - data.fba_fee
    gross_margin = gross_profit / data.selling_price
    metrics.append(MetricResult(
        name="Gross Margin",
        value=round(gross_margin * 100, 1),
        unit="%",
        status=evaluate_status(gross_margin, benchmarks["gross_margin"], higher_is_better=True),
        benchmark=benchmarks["gross_margin"]["healthy"] * 100,
        description=f"(Selling Price - ProductCost - Inbound - FBAfee) / Selling Price"
    ))
    
    # 2. InboundProportion
    shipping_ratio = data.shipping_cost_per_unit / data.selling_price
    metrics.append(MetricResult(
        name="InboundProportion",
        value=round(shipping_ratio * 100, 1),
        unit="%",
        status=evaluate_status(shipping_ratio, benchmarks["shipping_ratio"], higher_is_better=False),
        benchmark=benchmarks["shipping_ratio"]["healthy"] * 100,
        description="InboundCost / Selling Price"
    ))
    
    # 3. Net Margin
    ad_cost = data.selling_price * data.ad_spend_ratio
    other_cost = data.selling_price * 0.05  # Other FeesEstimate 5%
    net_profit = gross_profit - data.storage_fee - ad_cost - other_cost
    net_margin = net_profit / data.selling_price
    metrics.append(MetricResult(
        name="Net Margin",
        value=round(net_margin * 100, 1),
        unit="%",
        status=evaluate_status(net_margin, benchmarks["net_margin"], higher_is_better=True),
        benchmark=benchmarks["net_margin"]["healthy"] * 100,
        description="Deduct allCost after Profit Margin"
    ))
    
    # 4. Inventory Days
    metrics.append(MetricResult(
        name="Inventoryweeksconvert",
        value=data.inventory_days,
        unit="days",
        status=evaluate_status(data.inventory_days, benchmarks["inventory_days"], higher_is_better=False),
        benchmark=benchmarks["inventory_days"]["healthy"],
        description="CurrentInventoryCanselldays"
    ))
    
    # 5. CashweeksconvertweeksPeriod
    cash_cycle = (
        data.production_days + 
        data.shipping_days + 
        data.inventory_days + 
        14  # AmazonPayment Cycle
        - data.supplier_payment_days
    )
    metrics.append(MetricResult(
        name="Cash Cycle",
        value=cash_cycle,
        unit="days",
        status=evaluate_status(cash_cycle, benchmarks["cash_cycle"], higher_is_better=False),
        benchmark=benchmarks["cash_cycle"]["healthy"],
        description=" from PaymentComplete payment cycleweeksPeriod"
    ))
    
    return metrics


def calculate_cost_breakdown(data: SupplyChainInput) -> Dict[str, float]:
    """
    CalculateCostStructure breakdown
    """
    ad_cost = data.selling_price * data.ad_spend_ratio
    other_cost = data.selling_price * 0.05
    
    net_profit = (
        data.selling_price 
        - data.product_cost 
        - data.shipping_cost_per_unit 
        - data.fba_fee 
        - data.storage_fee 
        - ad_cost 
        - other_cost
    )
    
    return {
        "selling_price": data.selling_price,
        "product_cost": data.product_cost,
        "shipping_cost": data.shipping_cost_per_unit,
        "fba_fee": data.fba_fee,
        "storage_fee": data.storage_fee,
        "ad_cost": round(ad_cost, 2),
        "other_cost": round(other_cost, 2),
        "net_profit": round(net_profit, 2),
        # Proportion
        "product_cost_ratio": round(data.product_cost / data.selling_price * 100, 1),
        "shipping_ratio": round(data.shipping_cost_per_unit / data.selling_price * 100, 1),
        "fba_ratio": round(data.fba_fee / data.selling_price * 100, 1),
        "storage_ratio": round(data.storage_fee / data.selling_price * 100, 1),
        "ad_ratio": round(ad_cost / data.selling_price * 100, 1),
        "net_margin": round(net_profit / data.selling_price * 100, 1)
    }


def diagnose_bottlenecks(data: SupplyChainInput, metrics: List[MetricResult]) -> List[BottleneckItem]:
    """
    DiagnoseBottleneckandSort
    """
    bottlenecks = []
    benchmarks = BENCHMARKS.get(data.platform, BENCHMARKS["amazon"])
    
    # Check each Metrics
    for metric in metrics:
        if metric.status == HealthStatus.DANGER:
            severity = "High"
            priority = 1
        elif metric.status == HealthStatus.WARNING:
            severity = " in "
            priority = 2
        else:
            continue  # HealthyNot addBottleneck
            
        # Based onMetricsCategoryTypeGenerateRecommendation
        if metric.name == "Inventoryweeksconvert":
            bottlenecks.append(BottleneckItem(
                priority=priority,
                severity=severity,
                title="Inventoryweeksconvert slow ",
                problem=f"Current {metric.value} days vs Recommendation <{benchmarks['inventory_days']['healthy']} days",
                impact="CapitalOccupyIncrease，MayGeneratePeriodStoragefee",
                suggestion="1. Clear slow-movingSKU 2. Set safetyInventoryFormula 3.  small BatchHigh frequencyRestock"
            ))
        elif metric.name == "Cash Cycle":
            bottlenecks.append(BottleneckItem(
                priority=priority,
                severity=severity,
                title="Cash Cycle ",
                problem=f"Current {metric.value} days vs Recommendation <{benchmarks['cash_cycle']['healthy']} days",
                impact="CapitalUtilizeeffectRate low ，ImpactExpansionCapability",
                suggestion="1. StriveSupplierPayment terms 2. shrink short Inventorydays 3. ConsiderSupply ChainFinance"
            ))
        elif metric.name == "InboundProportion":
            bottlenecks.append(BottleneckItem(
                priority=priority,
                severity=severity,
                title="LogisticsCost High",
                problem=f"Current {metric.value}% vs Recommendation <{benchmarks['shipping_ratio']['healthy']*100}%",
                impact="ErodeProfitempty",
                suggestion="1. Sea freightReplaceAir freight 2. LCL/Full containerOptimization 3. Compare multiple freight forwarders"
            ))
        elif metric.name == "Gross Margin":
            bottlenecks.append(BottleneckItem(
                priority=priority,
                severity=severity,
                title="Gross Marginbias low ",
                problem=f"Current {metric.value}% vs Recommendation >{benchmarks['gross_margin']['healthy']*100}%",
                impact="Risk resistanceCapabilityWeak，difficult to SupportAdvertisingInput",
                suggestion="1. Raise price or Optimizationlistingconvert 2. reduce low ProcurementCost 3. OptimizationProductCombo"
            ))
        elif metric.name == "Net Margin":
            bottlenecks.append(BottleneckItem(
                priority=priority,
                severity=severity,
                title="Net Margin  low ",
                problem=f"Current {metric.value}% vs Recommendation >{benchmarks['net_margin']['healthy']*100}%",
                impact="ProfitCapabilityWeak，BusinessCannotSustain",
                suggestion="1. OptimizationAdvertisingACOS 2. ControlStoragefee 3. Increase average order value"
            ))
    
    # CheckPeriodStoragefee
    if data.has_long_term_storage:
        bottlenecks.append(BottleneckItem(
            priority=2,
            severity=" in ",
            title="ExistPeriodStoragefee",
            problem="PartInventorysuper 365days",
            impact="amount outside CostExpenditure，CapitalWaste",
            suggestion="1. ExportLibraryageReport 2. On-site promotion clearanceInventory 3. Remove or destroy"
        ))
    
    #  by excellent first LevelSort
    bottlenecks.sort(key=lambda x: x.priority)
    
    return bottlenecks[:3]  #  only Return Top 3


def analyze(data: SupplyChainInput) -> AnalysisResult:
    """
    ExecuteCompleteAnalyze
    """
    metrics = calculate_metrics(data)
    cost_breakdown = calculate_cost_breakdown(data)
    bottlenecks = diagnose_bottlenecks(data, metrics)
    
    # GenerateSummary
    danger_count = sum(1 for m in metrics if m.status == HealthStatus.DANGER)
    warning_count = sum(1 for m in metrics if m.status == HealthStatus.WARNING)
    
    if danger_count > 0:
        summary = f"Found {danger_count} CriticalIssueNeedImmediatelyProcess"
    elif warning_count > 0:
        summary = f"Found {warning_count} potential in IssueRecommendationOptimization"
    else:
        summary = "Supply ChainOverallHealthy，CanAttentionSustainOptimization"
    
    return AnalysisResult(
        metrics=metrics,
        cost_breakdown=cost_breakdown,
        bottlenecks=bottlenecks,
        summary=summary
    )


# ============================================================
# OutputFormat
# ============================================================

def format_metrics_table(metrics: List[MetricResult]) -> str:
    """FormatMetricsTable"""
    status_icons = {
        HealthStatus.HEALTHY: "✅",
        HealthStatus.WARNING: "⚠️",
        HealthStatus.DANGER: "🔴"
    }
    
    lines = ["| Metrics | Value | Benchmark | Status |", "|------|------|------|------|"]
    for m in metrics:
        icon = status_icons[m.status]
        lines.append(f"| {m.name} | {m.value}{m.unit} | {m.benchmark}{m.unit} | {icon} |")
    
    return "\n".join(lines)


def format_cost_breakdown(breakdown: Dict[str, float]) -> str:
    """FormatCostBreakdown"""
    lines = [
        f"Selling Price            .2f   100%",
        "─────────────────────────────",
        f"ProductCost        -.2f    {breakdown['product_cost_ratio']}%",
        f"InboundLogistics        -.2f     {breakdown['shipping_ratio']}%",
        f"FBA Fulfillment      -.2f    {breakdown['fba_ratio']}%",
        f"FBA Storagefee      -.2f     {breakdown['storage_ratio']}%",
        f"Advertisingfee          -.2f    {breakdown['ad_ratio']}%",
        f"OtherFee        -.2f     5.0%",
        "─────────────────────────────",
        f"Net Profit          .2f     {breakdown['net_margin']}%"
    ]
    return "\n".join(lines)


def format_bottlenecks(bottlenecks: List[BottleneckItem]) -> str:
    """FormatBottleneckcolumnTable"""
    if not bottlenecks:
        return "✅ No obvious bottleneck found"
    
    lines = []
    priority_icons = {1: "🥇", 2: "🥈", 3: "🥉"}
    
    for i, b in enumerate(bottlenecks, 1):
        icon = priority_icons.get(i, "•")
        lines.append(f"\n{icon} **【{b.severity}】{b.title}**")
        lines.append(f"   Issue: {b.problem}")
        lines.append(f"   Impact: {b.impact}")
        lines.append(f"   Recommendation: {b.suggestion}")
    
    return "\n".join(lines)


def format_full_report(result: AnalysisResult) -> str:
    """GenerateCompleteReport"""
    report = f"""
🔍 **Supply ChainBottleneck DiagnosisReport**

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 **Key Metrics**

{format_metrics_table(result.metrics)}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💰 **CostStructure breakdown** ( each piece)

```
{format_cost_breakdown(result.cost_breakdown)}
```

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🎯 **Top 3 Bottleneck Diagnosis**

{format_bottlenecks(result.bottlenecks)}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 **Summary**: {result.summary}
"""
    return report


# ============================================================
# CLI Entry Point
# ============================================================

def main():
    """CLI Entry Point - use at Test"""
    import sys
    
    # ExampleData
    test_data = SupplyChainInput(
        product_cost=8.00,
        supplier_payment_days=0,
        production_days=25,
        shipping_cost_per_unit=0.75,
        shipping_days=35,
        selling_price=25.00,
        fba_fee=5.00,
        storage_fee=0.50,
        ad_spend_ratio=0.10,
        inventory_days=60,
        has_long_term_storage=True,
        platform="amazon"
    )
    
    # If JSON input provided
    if len(sys.argv) > 1:
        try:
            input_json = json.loads(sys.argv[1])
            test_data = SupplyChainInput(**input_json)
        except Exception as e:
            print(f"Error parsing input: {e}")
            sys.exit(1)
    
    # ExecuteAnalyze
    result = analyze(test_data)
    
    # OutputReport
    print(format_full_report(result))
    
    # Output JSON (For program call)
    # print(json.dumps({
    #     "metrics": [{"name": m.name, "value": m.value, "status": m.status.value} for m in result.metrics],
    #     "bottlenecks": [{"title": b.title, "severity": b.severity} for b in result.bottlenecks],
    #     "summary": result.summary
    # }, ensure_ascii=False, indent=2))


if __name__ == "__main__":
    main()

FILE:scripts/report_doc.py
#!/usr/bin/env python3
"""
Supply Chain Analyzer - Document Report Generator
Supply ChainAnalyze - Report documentGenerate（Suitable for sharing/Demo）
"""

from datetime import datetime
from calculator import SupplyChainInput, analyze, HealthStatus


def generate_doc_report(data: SupplyChainInput, output_path: str = "report.md") -> str:
    """
    GenerateReport document（Markdown Format，SuitableExport PDF/PPT）
    """
    result = analyze(data)
    
    # StatusIcon
    status_icons = {
        HealthStatus.HEALTHY: "🟢",
        HealthStatus.WARNING: "🟡",
        HealthStatus.DANGER: "🔴"
    }
    
    # MetricsTable
    metrics_table = "| Metrics | CurrentValue | HealthyBenchmark | Status |\n|:---:|:---:|:---:|:---:|\n"
    for m in result.metrics:
        icon = status_icons[m.status]
        metrics_table += f"| {m.name} | **{m.value}{m.unit}** | {m.benchmark}{m.unit} | {icon} |\n"
    
    # CostStructure
    cost = result.cost_breakdown
    cost_bars = ""
    cost_items = [
        ("ProductCost", cost['product_cost_ratio'], "🔴"),
        ("FBAFulfillment", cost['fba_ratio'], "🔵"),
        ("Advertisingfee", cost['ad_ratio'], "🟣"),
        ("InboundLogistics", cost['shipping_ratio'], "🟠"),
        ("Storagefee", cost['storage_ratio'], "🟤"),
        ("Other", 5, "⚪"),
        ("Net Profit", cost['net_margin'], "🟢"),
    ]
    for name, ratio, emoji in cost_items:
        bar = "█" * int(ratio / 2) if ratio > 0 else ""
        cost_bars += f"| {emoji} {name} | {bar} | {ratio}% |\n"
    
    # BottleneckPart
    bottlenecks_section = ""
    if result.bottlenecks:
        for i, b in enumerate(result.bottlenecks, 1):
            emoji = "🥇" if i == 1 else "🥈" if i == 2 else "🥉"
            bottlenecks_section += f"""
### {emoji} Bottleneck {i}: {b.title}

**CriticalprocessDegree**: {b.severity}

**IssueDescription**  
{b.problem}

**BusinessImpact**  
{b.impact}

**Optimization Suggestions**  
{b.suggestion}

---
"""
    else:
        bottlenecks_section = "\n✅ **No obvious bottleneck found，Supply ChainOverallHealthy**\n"
    
    # ExecuteList
    action_items = """
### 📋 ExecuteList

**basicweeks**
- [ ] Export FBA LibraryageReport，Mark exceeds 60 days SKU
- [ ] Calculate each  SKU safe all Inventoryquantity
- [ ] OrganizeSupplierContact info，Prepare negotiation

** below weeks**
- [ ] Clear slow-movingInventory（On-site promotion/Off-site clearance）
- [ ] ContactSuppliertalkPayment terms
- [ ] AdjustRestockfrequencyRate

**basicmonths**
- [ ] InventorydaysTarget：Drop to 45 days to  inside 
- [ ] Evaluate small BatchHigh frequencyRestockModeFeasibility
- [ ] Review execution results
"""
    
    # Assemble document
    doc = f"""---
title: Supply ChainBottleneckAnalyzeReport
date: {datetime.now().strftime("%Y-%m-%d")}
author: Supply Chain Analyzer
---

# 📦 Supply ChainBottleneckAnalyzeReport

> **GenerateTime**: {datetime.now().strftime("%Yyears%mmonths%dDay %H:%M")}  
> **AnalyzePlatform**: Amazon ({data.platform.upper()})

---

## 📌 CoreConclusion

<div style="background: #f0f9ff; padding: 20px; border-radius: 8px; border-left: 4px solid #3b82f6;">

**{result.summary}**

Based onProvided by youData，Found **{len([m for m in result.metrics if m.status != HealthStatus.HEALTHY])}** MetricsNeedAttention。

</div>

---

## 📊 Key MetricsOverview

{metrics_table}

---

## 💰 CostStructureAnalyze

** each pieceProductCostBreakdown** (Selling Price .2f)

| Itemitem | Proportion | Ratio |
|:---|:---|---:|
{cost_bars}

**Net Profit: .2f/piece ({cost['net_margin']}%)**

---

## 🎯 Bottleneck Diagnosis & Optimization Suggestions

{bottlenecks_section}

---

## 🚀 Action Plan

{action_items}

---

## 📈 prePeriodEffect

| OptimizationItem | Current | Target | prePeriodRevenue |
|:---|:---:|:---:|:---|
| Inventoryweeksconvert | {data.inventory_days}days | 45days | ReleaseInventoryCapital，ReduceStoragefee |
| PeriodStoragefee |  has  | no | Save $500+/months |
| SupplierPayment terms | {data.supplier_payment_days}days | 30days | Improve cash flow |

---

## 📎 Appendix

### DataSource

- ProductCost: data.product_cost/piece (UserInput)
- InboundCost: data.shipping_cost_per_unit/piece (UserInput)
- FBA Fee: data.fba_fee/piece (UserInput)
- Selling Price: data.selling_price/piece (UserInput)
- Inventorydays: {data.inventory_days}days (UserInput)

### BenchmarkValueDescription

basicReportUseHealthyBenchmarkValueBased onAmazonSellerIndustryData，Can be adjusted according to actual situation。

---

<div style="text-align: center; color: #6b7280; font-size: 12px; margin-top: 40px;">

**Powered by Supply Chain Analyzer Skill | NexScope**

</div>
"""
    
    with open(output_path, 'w', encoding='utf-8') as f:
        f.write(doc)
    
    return output_path


if __name__ == "__main__":
    # TestData
    test_data = SupplyChainInput(
        product_cost=8.00,
        supplier_payment_days=0,
        production_days=25,
        shipping_cost_per_unit=0.75,
        shipping_days=35,
        selling_price=25.00,
        fba_fee=5.00,
        storage_fee=0.50,
        ad_spend_ratio=0.10,
        inventory_days=60,
        has_long_term_storage=True,
        platform="amazon"
    )
    
    output = generate_doc_report(test_data, "supply_chain_report.md")
    print(f"✅ Report documentGenerate: {output}")

FILE:scripts/report_html.py
#!/usr/bin/env python3
"""
Supply Chain Analyzer - HTML Report Generator
Supply ChainAnalyze - WebchartTableReportGenerate
"""

import json
from datetime import datetime
from calculator import SupplyChainInput, analyze, HealthStatus


def generate_html_report(data: SupplyChainInput, output_path: str = "report.html") -> str:
    """
    GenerateWebchartTableReport
    """
    result = analyze(data)
    
    # Prepare imageTableData
    metrics_data = [
        {"name": m.name, "value": m.value, "benchmark": m.benchmark, "status": m.status.value}
        for m in result.metrics
    ]
    
    cost_data = result.cost_breakdown
    
    bottlenecks_html = ""
    severity_colors = {"High": "#ef4444", " in ": "#f59e0b", " low ": "#22c55e"}
    for i, b in enumerate(result.bottlenecks, 1):
        color = severity_colors.get(b.severity, "#6b7280")
        bottlenecks_html += f"""
        <div class="bottleneck-card">
            <div class="bottleneck-header">
                <span class="priority">#{i}</span>
                <span class="severity" style="background: {color}">{b.severity}</span>
                <span class="title">{b.title}</span>
            </div>
            <div class="bottleneck-body">
                <p><strong>Issue:</strong> {b.problem}</p>
                <p><strong>Impact:</strong> {b.impact}</p>
                <p><strong>Recommendation:</strong> {b.suggestion}</p>
            </div>
        </div>
        """
    
    html = f"""<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Supply ChainAnalyzeReport</title>
    <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
    <style>
        * {{ margin: 0; padding: 0; box-sizing: border-box; }}
        body {{
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
            background: linear-gradient(135deg, #1a1a2e 0%, #16213e 100%);
            color: #fff;
            min-height: 100vh;
            padding: 40px 20px;
        }}
        .container {{ max-width: 1200px; margin: 0 auto; }}
        .header {{
            text-align: center;
            margin-bottom: 40px;
        }}
        .header h1 {{
            font-size: 32px;
            margin-bottom: 8px;
        }}
        .header p {{
            color: rgba(255,255,255,0.6);
        }}
        .summary-banner {{
            background: linear-gradient(135deg, rgba(99, 102, 241, 0.2) 0%, rgba(139, 92, 246, 0.2) 100%);
            border: 1px solid rgba(99, 102, 241, 0.3);
            border-radius: 16px;
            padding: 24px 32px;
            margin-bottom: 40px;
            text-align: center;
        }}
        .summary-banner h2 {{
            font-size: 20px;
            margin-bottom: 8px;
        }}
        .grid {{
            display: grid;
            grid-template-columns: repeat(auto-fit, minmax(350px, 1fr));
            gap: 24px;
            margin-bottom: 40px;
        }}
        .card {{
            background: rgba(255,255,255,0.05);
            border: 1px solid rgba(255,255,255,0.1);
            border-radius: 16px;
            padding: 24px;
        }}
        .card h3 {{
            font-size: 18px;
            margin-bottom: 20px;
            display: flex;
            align-items: center;
            gap: 8px;
        }}
        .metrics-table {{
            width: 100%;
            border-collapse: collapse;
        }}
        .metrics-table th, .metrics-table td {{
            padding: 12px;
            text-align: left;
            border-bottom: 1px solid rgba(255,255,255,0.1);
        }}
        .metrics-table th {{
            color: rgba(255,255,255,0.6);
            font-weight: 500;
        }}
        .status {{
            display: inline-flex;
            align-items: center;
            gap: 4px;
        }}
        .status.healthy {{ color: #22c55e; }}
        .status.warning {{ color: #f59e0b; }}
        .status.danger {{ color: #ef4444; }}
        .chart-container {{
            position: relative;
            height: 300px;
        }}
        .bottleneck-card {{
            background: rgba(0,0,0,0.2);
            border-radius: 12px;
            padding: 16px;
            margin-bottom: 16px;
        }}
        .bottleneck-header {{
            display: flex;
            align-items: center;
            gap: 12px;
            margin-bottom: 12px;
        }}
        .priority {{
            background: rgba(99, 102, 241, 0.3);
            padding: 4px 10px;
            border-radius: 6px;
            font-weight: 600;
        }}
        .severity {{
            padding: 4px 10px;
            border-radius: 6px;
            font-size: 12px;
            font-weight: 600;
        }}
        .title {{
            font-weight: 600;
            font-size: 16px;
        }}
        .bottleneck-body p {{
            color: rgba(255,255,255,0.7);
            font-size: 14px;
            margin-bottom: 8px;
        }}
        .footer {{
            text-align: center;
            color: rgba(255,255,255,0.4);
            font-size: 12px;
            margin-top: 40px;
        }}
    </style>
</head>
<body>
    <div class="container">
        <div class="header">
            <h1>📦 Supply ChainBottleneckAnalyzeReport</h1>
            <p>GenerateTime: {datetime.now().strftime("%Y-%m-%d %H:%M")}</p>
        </div>
        
        <div class="summary-banner">
            <h2>{result.summary}</h2>
            <p>Based onProvided by youData，WeFound  {len(result.bottlenecks)} NeedAttentionIssue</p>
        </div>
        
        <div class="grid">
            <div class="card">
                <h3>📊 Key Metrics</h3>
                <table class="metrics-table">
                    <thead>
                        <tr>
                            <th>Metrics</th>
                            <th>Value</th>
                            <th>Benchmark</th>
                            <th>Status</th>
                        </tr>
                    </thead>
                    <tbody>
                        {"".join(f'''
                        <tr>
                            <td>{m.name}</td>
                            <td>{m.value}{m.unit}</td>
                            <td>{m.benchmark}{m.unit}</td>
                            <td><span class="status {m.status.value}">
                                {"✅" if m.status == HealthStatus.HEALTHY else "⚠️" if m.status == HealthStatus.WARNING else "🔴"}
                            </span></td>
                        </tr>
                        ''' for m in result.metrics)}
                    </tbody>
                </table>
            </div>
            
            <div class="card">
                <h3>💰 CostStructure</h3>
                <div class="chart-container">
                    <canvas id="costChart"></canvas>
                </div>
            </div>
        </div>
        
        <div class="card">
            <h3>🎯 Top 3 Bottleneck Diagnosis</h3>
            {bottlenecks_html if bottlenecks_html else "<p>✅ No obvious bottleneck found，Supply ChainOverallHealthy</p>"}
        </div>
        
        <div class="footer">
            <p>Powered by Supply Chain Analyzer Skill | NexScope</p>
        </div>
    </div>
    
    <script>
        // CostStructure pie chart
        const costCtx = document.getElementById('costChart').getContext('2d');
        new Chart(costCtx, {{
            type: 'doughnut',
            data: {{
                labels: ['ProductCost', 'InboundLogistics', 'FBAFulfillment', 'Storagefee', 'Advertisingfee', 'Other', 'Net Profit'],
                datasets: [{{
                    data: [
                        {cost_data['product_cost_ratio']},
                        {cost_data['shipping_ratio']},
                        {cost_data['fba_ratio']},
                        {cost_data['storage_ratio']},
                        {cost_data['ad_ratio']},
                        5,
                        {cost_data['net_margin']}
                    ],
                    backgroundColor: [
                        '#ef4444',
                        '#f59e0b',
                        '#3b82f6',
                        '#8b5cf6',
                        '#ec4899',
                        '#6b7280',
                        '#22c55e'
                    ],
                    borderWidth: 0
                }}]
            }},
            options: {{
                responsive: true,
                maintainAspectRatio: false,
                plugins: {{
                    legend: {{
                        position: 'right',
                        labels: {{
                            color: '#fff',
                            padding: 12
                        }}
                    }}
                }}
            }}
        }});
    </script>
</body>
</html>
"""
    
    with open(output_path, 'w', encoding='utf-8') as f:
        f.write(html)
    
    return output_path


if __name__ == "__main__":
    # TestData
    test_data = SupplyChainInput(
        product_cost=8.00,
        supplier_payment_days=0,
        production_days=25,
        shipping_cost_per_unit=0.75,
        shipping_days=35,
        selling_price=25.00,
        fba_fee=5.00,
        storage_fee=0.50,
        ad_spend_ratio=0.10,
        inventory_days=60,
        has_long_term_storage=True,
        platform="amazon"
    )
    
    output = generate_html_report(test_data, "supply_chain_report.html")
    print(f"✅ Report already Generate: {output}")

ClawHub Data Analysis Automation+2

Walmart Review Checker

Skill

Walmart review authenticity analyzer. Detect fake reviews, suspicious patterns, and rating manipulation. Includes WFS verified badge analysis, incentivized r...

---
name: walmart-review-checker
version: 1.0.0
description: "Walmart review authenticity analyzer. Detect fake reviews, suspicious patterns, and rating manipulation. Includes WFS verified badge analysis, incentivized review detection, and Walmart-specific red flag identification. No API key required."
metadata: {"nexscope":{"emoji":"🔍","category":"ecommerce"}}
---

# Walmart Review Checker 🔍

Review authenticity analyzer for Walmart — detect fake reviews, suspicious patterns, and feedback manipulation.

## Installation

```bash
npx skills add nexscope-ai/eCommerce-Skills --skill walmart-review-checker -g
```

## Features

- **Authenticity Score** — 0-100 comprehensive rating
- **WFS Verified Badge Analysis** — Check fulfillment verification patterns
- **Incentivized Review Detection** — Identify paid/incentivized reviews
- **Walmart-specific Red Flags** — Platform-specific warning signs
- **Progressive Analysis** — More data = deeper insights

## Walmart-Specific Detection

| Signal | Description |
|--------|-------------|
| WFS Badge | Verified fulfillment patterns |
| Incentivized | "Received free product" indicators |
| Review timing | Clustered reviews in short periods |
| Generic comments | Templated review patterns |

## Risk Levels

| Score | Level | Description |
|-------|-------|-------------|
| 70-100 | ✅ Low Risk | Reviews appear authentic |
| 50-69 | ⚠️ Medium Risk | Some concerns found |
| 30-49 | 🔴 High Risk | Multiple red flags |
| 0-29 | 💀 Critical | Likely manipulated reviews |

## Usage

### Paste Reviews

```
Check these Walmart reviews:

5 stars - Great product, fast shipping from WFS!
5 stars - Exactly as described, love it!
1 star - Arrived damaged.
```

### JSON Input

```bash
python3 scripts/analyzer.py '[
  {"content": "Great product!", "rating": 5, "date": "2024-01-15", "wfs_verified": true},
  {"content": "Amazing!", "rating": 5, "date": "2024-01-15", "wfs_verified": false}
]'
```

### Demo Mode

```bash
python3 scripts/analyzer.py --demo
```

## Output Example

```
📊 Walmart Review Authenticity Report

Product: Example Product
Reviews: 25
Analysis Level: L3

━━━━━━━━━━━━━━━━━━━━━━━━

Authenticity Score: 74/100 ✅

Low Risk - Reviews appear authentic.

━━━━━━━━━━━━━━━━━━━━━━━━

Detection Results

✅ Time Clustering: Normal
✅ WFS Verified Ratio: 68% (healthy)
⚠️ Generic Comments: 12%
```

---

**Part of [Nexscope AI](https://www.nexscope.ai/) — AI tools for e-commerce sellers.**

FILE:scripts/analyzer.py
#!/usr/bin/env python3
"""
Amazon Review Checker - Core Analyzer
AmazonReviewAuthenticityDetection - CoreAnalyzeEngine

Features:
- ProgressiveAnalyze ( has  many  few Data，Give conclusion)
-  many dimensionDegreeDetection (Time/Content/Rating/Account/VP)
- Friendly guidance (HintCanDeepenDirection)

Version: 1.0.0
"""

import json
import re
import math
from dataclasses import dataclass, field
from typing import List, Dict, Optional, Tuple
from datetime import datetime, timedelta
from collections import Counter
from enum import Enum
import sys


class RiskLevel(Enum):
    LOW = "low"           # 0-30
    MEDIUM = "medium"     # 31-60
    HIGH = "high"         # 61-80
    CRITICAL = "critical" # 81-100


class AnalysisLevel(Enum):
    L1_BASIC = "L1"      # onlyContent
    L2_TIMED = "L2"      # + Time
    L3_SCORED = "L3"     # + Rating
    L4_FULL = "L4"       #  all Field


# ============================================================
# Data Structures
# ============================================================

@dataclass
class Review:
    """Single itemReview"""
    content: str
    rating: Optional[int] = None          # 1-5 star
    date: Optional[str] = None            # DayPeriod
    reviewer_name: Optional[str] = None   # Reviewperson
    verified_purchase: Optional[bool] = None  # VP
    helpful_votes: Optional[int] = None   #  has Help
    reviewer_reviews_count: Optional[int] = None  # ReviewTotalReview Count
    
    @property
    def has_rating(self) -> bool:
        return self.rating is not None
    
    @property
    def has_date(self) -> bool:
        return self.date is not None
    
    @property
    def has_vp(self) -> bool:
        return self.verified_purchase is not None


@dataclass
class DimensionResult:
    """Single dimensionDegreeDetectionResult"""
    name: str
    name_zh: str
    score: float          # 0-100, exceedHighexceedSuspicious
    status: str           # ✅ ⚠️ 🔴
    detail: str
    detail_zh: str
    weight: float = 0.0


@dataclass
class SuspiciousReview:
    """SuspiciousReview"""
    content: str
    risk_score: float
    reasons: List[str]
    reasons_zh: List[str]


@dataclass
class AnalysisResult:
    """AnalyzeResult"""
    asin: str
    total_reviews: int
    analysis_level: AnalysisLevel
    authenticity_score: int       # 0-100, exceedHighexceedReal
    risk_level: RiskLevel
    dimensions: List[DimensionResult]
    suspicious_reviews: List[SuspiciousReview]
    available_fields: List[str]
    missing_fields: List[str]
    deepening_hints: List[str]
    deepening_hints_zh: List[str]
    summary: str
    summary_zh: str


# ============================================================
# DetectionAlgorithm
# ============================================================

def detect_content_similarity(reviews: List[Review]) -> DimensionResult:
    """DetectionSimilar contentDegree"""
    if len(reviews) < 2:
        return DimensionResult(
            name="Content Similarity",
            name_zh="Similar contentDegree",
            score=0,
            status="✅",
            detail="Not enough reviews to compare",
            detail_zh="Review CountInsufficient，CannotComparison",
            weight=0.20
        )
    
    # Simple similarityDegreeDetection：CheckRepeated phrases
    contents = [r.content.lower() for r in reviews]
    
    # Extract3-gram
    def get_ngrams(text, n=3):
        words = re.findall(r'\w+', text)
        return [' '.join(words[i:i+n]) for i in range(len(words)-n+1)]
    
    all_ngrams = []
    for content in contents:
        all_ngrams.extend(get_ngrams(content))
    
    # Statistics heavy complex
    ngram_counts = Counter(all_ngrams)
    repeated = sum(1 for count in ngram_counts.values() if count > 1)
    total = len(ngram_counts) if ngram_counts else 1
    
    similarity_ratio = repeated / total if total > 0 else 0
    score = min(100, similarity_ratio * 500)  # put big 
    
    # CheckHighDegreeSimilarReview for 
    similar_pairs = 0
    for i, c1 in enumerate(contents):
        for c2 in contents[i+1:]:
            if len(c1) > 20 and len(c2) > 20:
                # Simple Jaccard SimilarDegree
                set1, set2 = set(c1.split()), set(c2.split())
                if set1 and set2:
                    jaccard = len(set1 & set2) / len(set1 | set2)
                    if jaccard > 0.5:
                        similar_pairs += 1
    
    if similar_pairs > 0:
        score = max(score, 50 + similar_pairs * 10)
    
    score = min(100, score)
    
    if score < 30:
        status = "✅"
    elif score < 60:
        status = "⚠️"
    else:
        status = "🔴"
    
    return DimensionResult(
        name="Content Similarity",
        name_zh="Similar contentDegree",
        score=round(score, 1),
        status=status,
        detail=f"Found {similar_pairs} similar review pairs",
        detail_zh=f"Found {similar_pairs} groupHighDegreeSimilarReview",
        weight=0.20
    )


def detect_time_clustering(reviews: List[Review]) -> Optional[DimensionResult]:
    """DetectionTimeAggregate"""
    dated_reviews = [r for r in reviews if r.has_date]
    
    if len(dated_reviews) < 5:
        return None  # DataInsufficient
    
    # ParseDayPeriod
    dates = []
    for r in dated_reviews:
        try:
            # TryMultipleFormat
            for fmt in ['%Y-%m-%d', '%B %d, %Y', '%d %B %Y', '%m/%d/%Y']:
                try:
                    dates.append(datetime.strptime(r.date, fmt))
                    break
                except:
                    continue
        except:
            pass
    
    if len(dates) < 5:
        return None
    
    dates.sort()
    
    # CalculateAdjacentReviewTimeseparate
    intervals = [(dates[i+1] - dates[i]).days for i in range(len(dates)-1)]
    
    if not intervals:
        return None
    
    # DetectionAggregate： short Time inside Large amountReview
    short_intervals = sum(1 for i in intervals if i <= 1)  # 1days inside 
    clustering_ratio = short_intervals / len(intervals)
    
    # Detection 48h Outbreak
    burst_count = 0
    window_size = 2  # 2daysWindow
    for i in range(len(dates) - 1):
        count_in_window = sum(1 for d in dates if 0 <= (d - dates[i]).days <= window_size)
        burst_count = max(burst_count, count_in_window)
    
    score = 0
    if clustering_ratio > 0.5:
        score += 40
    if clustering_ratio > 0.7:
        score += 20
    if burst_count > len(dates) * 0.3:
        score += 30
    
    score = min(100, score)
    
    if score < 30:
        status = "✅"
    elif score < 60:
        status = "⚠️"
    else:
        status = "🔴"
    
    return DimensionResult(
        name="Time Clustering",
        name_zh="TimeAggregate",
        score=round(score, 1),
        status=status,
        detail=f"Max {burst_count} reviews in 48h window, {clustering_ratio*100:.0f}% within 1 day",
        detail_zh=f"48h inside  most  many  {burst_count} itemReview，{clustering_ratio*100:.0f}%  in 1days inside ",
        weight=0.25
    )


def detect_rating_distribution(reviews: List[Review]) -> Optional[DimensionResult]:
    """DetectionRating Distribution"""
    rated_reviews = [r for r in reviews if r.has_rating]
    
    if len(rated_reviews) < 5:
        return None
    
    ratings = [r.rating for r in rated_reviews]
    rating_counts = Counter(ratings)
    total = len(ratings)
    
    # CalculateDistribution
    five_star_ratio = rating_counts.get(5, 0) / total
    one_star_ratio = rating_counts.get(1, 0) / total
    extreme_ratio = five_star_ratio + one_star_ratio
    
    # Natural distribution usually is：5star ~50-60%, 4star ~20%, 3star ~10%, 2star ~5%, 1star ~10%
    # Abnormal case： all 5star、Polarized
    
    score = 0
    anomaly_detail = []
    
    if five_star_ratio > 0.85:
        score += 50
        anomaly_detail.append(f"{five_star_ratio*100:.0f}% 5-star (abnormal)")
    elif five_star_ratio > 0.75:
        score += 30
        anomaly_detail.append(f"{five_star_ratio*100:.0f}% 5-star (suspicious)")
    
    # Polarized
    if extreme_ratio > 0.9 and one_star_ratio > 0.1:
        score += 30
        anomaly_detail.append("Polarized distribution")
    
    # MissingMiddleRating
    mid_ratings = sum(rating_counts.get(r, 0) for r in [2, 3, 4])
    if mid_ratings / total < 0.1 and total > 10:
        score += 20
        anomaly_detail.append("Missing mid-range ratings")
    
    score = min(100, score)
    
    if score < 30:
        status = "✅"
    elif score < 60:
        status = "⚠️"
    else:
        status = "🔴"
    
    dist_str = ", ".join([f"{r}★:{rating_counts.get(r,0)}" for r in [5,4,3,2,1]])
    
    return DimensionResult(
        name="Rating Distribution",
        name_zh="Rating Distribution",
        score=round(score, 1),
        status=status,
        detail=f"Distribution: {dist_str}. {'; '.join(anomaly_detail) if anomaly_detail else 'Normal'}",
        detail_zh=f"Distribution: {dist_str}。{'; '.join(anomaly_detail) if anomaly_detail else 'Normal'}",
        weight=0.20
    )


def detect_vp_ratio(reviews: List[Review]) -> Optional[DimensionResult]:
    """Detection Verified Purchase Ratio"""
    vp_reviews = [r for r in reviews if r.has_vp]
    
    if len(vp_reviews) < 5:
        return None
    
    vp_count = sum(1 for r in vp_reviews if r.verified_purchase)
    vp_ratio = vp_count / len(vp_reviews)
    
    # Normal VP Ratio should  should  in  60-80%
    score = 0
    if vp_ratio < 0.4:
        score = 70
    elif vp_ratio < 0.5:
        score = 50
    elif vp_ratio < 0.6:
        score = 30
    else:
        score = 10
    
    if score < 30:
        status = "✅"
    elif score < 60:
        status = "⚠️"
    else:
        status = "🔴"
    
    return DimensionResult(
        name="Verified Purchase Ratio",
        name_zh="VPRatio",
        score=round(score, 1),
        status=status,
        detail=f"{vp_ratio*100:.0f}% verified purchase ({vp_count}/{len(vp_reviews)})",
        detail_zh=f"{vp_ratio*100:.0f}%  already VerifyPurchase ({vp_count}/{len(vp_reviews)})",
        weight=0.15
    )


def detect_review_length(reviews: List[Review]) -> DimensionResult:
    """DetectionReviewDegreeDistribution"""
    lengths = [len(r.content) for r in reviews]
    
    if not lengths:
        return DimensionResult(
            name="Review Length",
            name_zh="ReviewDegree",
            score=0,
            status="✅",
            detail="No reviews",
            detail_zh="noReview",
            weight=0.05
        )
    
    avg_length = sum(lengths) / len(lengths)
    short_count = sum(1 for l in lengths if l < 50)
    short_ratio = short_count / len(lengths)
    
    # DetectionTemplate（DegreeHighDegreeConsistent）
    if len(lengths) > 5:
        length_std = (sum((l - avg_length) ** 2 for l in lengths) / len(lengths)) ** 0.5
        cv = length_std / avg_length if avg_length > 0 else 0  # Variation coefficient
    else:
        cv = 1
    
    score = 0
    if short_ratio > 0.7:
        score += 40
    if cv < 0.3 and len(lengths) > 10:  # DegreeToo consistent
        score += 40
    
    score = min(100, score)
    
    if score < 30:
        status = "✅"
    elif score < 60:
        status = "⚠️"
    else:
        status = "🔴"
    
    return DimensionResult(
        name="Review Length",
        name_zh="ReviewDegree",
        score=round(score, 1),
        status=status,
        detail=f"Avg length: {avg_length:.0f} chars, {short_ratio*100:.0f}% short (<50)",
        detail_zh=f"AverageDegree: {avg_length:.0f} Character, {short_ratio*100:.0f}%   short  (<50)",
        weight=0.05
    )


def detect_keywords(reviews: List[Review]) -> DimensionResult:
    """DetectionFake ordersKeywords"""
    # Common fake ordersReviewKeywords
    suspicious_keywords = [
        'received free', 'free product', 'in exchange', 'honest review',
        'discount code', 'promotional', 'gifted', 'complimentary',
        'five stars', '5 stars', 'best ever', 'amazing product',
        'highly recommend', 'must buy', 'perfect product',
        #  in text
        'Positive ReviewCashback', 'Five starPositive Review', 'Free trial', 'Gift'
    ]
    
    keyword_hits = 0
    for review in reviews:
        content_lower = review.content.lower()
        for keyword in suspicious_keywords:
            if keyword.lower() in content_lower:
                keyword_hits += 1
                break
    
    hit_ratio = keyword_hits / len(reviews) if reviews else 0
    score = min(100, hit_ratio * 200)
    
    if score < 30:
        status = "✅"
    elif score < 60:
        status = "⚠️"
    else:
        status = "🔴"
    
    return DimensionResult(
        name="Suspicious Keywords",
        name_zh="SuspiciousKeywords",
        score=round(score, 1),
        status=status,
        detail=f"{keyword_hits} reviews contain suspicious keywords",
        detail_zh=f"{keyword_hits} itemReviewPackagecontainSuspiciousKeywords",
        weight=0.05
    )


def identify_suspicious_reviews(reviews: List[Review], dimensions: List[DimensionResult]) -> List[SuspiciousReview]:
    """IdentifyHigh RiskReview"""
    suspicious = []
    
    for review in reviews:
        risk_score = 0
        reasons = []
        reasons_zh = []
        
        #  short Review
        if len(review.content) < 30:
            risk_score += 20
            reasons.append("Very short review")
            reasons_zh.append("Review  short ")
        
        # non VP
        if review.has_vp and not review.verified_purchase:
            risk_score += 25
            reasons.append("Not verified purchase")
            reasons_zh.append("nonVerifyPurchase")
        
        # ExtremeRating + TemplateContent
        if review.has_rating and review.rating == 5:
            generic_phrases = ['great', 'amazing', 'perfect', 'love it', 'best', 'excellent']
            if any(p in review.content.lower() for p in generic_phrases) and len(review.content) < 100:
                risk_score += 30
                reasons.append("Generic 5-star template")
                reasons_zh.append("Template5starPositive Review")
        
        # SuspiciousKeywords
        suspicious_keywords = ['received free', 'in exchange', 'honest review', 'discount']
        if any(k in review.content.lower() for k in suspicious_keywords):
            risk_score += 35
            reasons.append("Contains incentivized review keywords")
            reasons_zh.append("Contains incentiveReviewKeywords")
        
        if risk_score >= 40:
            suspicious.append(SuspiciousReview(
                content=review.content[:100] + "..." if len(review.content) > 100 else review.content,
                risk_score=min(100, risk_score),
                reasons=reasons,
                reasons_zh=reasons_zh
            ))
    
    #  by RiskScoreSort
    suspicious.sort(key=lambda x: x.risk_score, reverse=True)
    return suspicious[:10]  # Top 10


def determine_analysis_level(reviews: List[Review]) -> Tuple[AnalysisLevel, List[str], List[str]]:
    """ConfirmAnalyzelayerLevelAndMissing field"""
    available = ["content"]
    missing = []
    
    has_rating = any(r.has_rating for r in reviews)
    has_date = any(r.has_date for r in reviews)
    has_vp = any(r.has_vp for r in reviews)
    has_reviewer = any(r.reviewer_name for r in reviews)
    
    if has_rating:
        available.append("rating")
    else:
        missing.append("rating")
    
    if has_date:
        available.append("date")
    else:
        missing.append("date")
    
    if has_vp:
        available.append("verified_purchase")
    else:
        missing.append("verified_purchase")
    
    if has_reviewer:
        available.append("reviewer_info")
    else:
        missing.append("reviewer_info")
    
    # Determine levelLevel
    if has_rating and has_date and has_vp:
        level = AnalysisLevel.L4_FULL
    elif has_rating and has_date:
        level = AnalysisLevel.L3_SCORED
    elif has_date:
        level = AnalysisLevel.L2_TIMED
    else:
        level = AnalysisLevel.L1_BASIC
    
    return level, available, missing


def generate_deepening_hints(missing: List[str]) -> Tuple[List[str], List[str]]:
    """GenerateDeepenHint"""
    hints_en = []
    hints_zh = []
    
    hint_map = {
        "rating": (
            "Add star ratings → Unlock 'Rating Distribution Analysis'",
            "Add starLevelRating → Unlock「Rating DistributionAnalyze」"
        ),
        "date": (
            "Add review dates → Unlock 'Time Clustering Detection'",
            "SupplementReviewDayPeriod → Unlock「TimeAggregateDetection」"
        ),
        "verified_purchase": (
            "Add VP status → Unlock 'Verified Purchase Analysis'",
            "SupplementVPStatus → Unlock「PurchaseVerifyAnalyze」"
        ),
        "reviewer_info": (
            "Add reviewer info → Unlock 'Account Profile Analysis'",
            "SupplementReviewpersonInformation → Unlock「Account profileAnalyze」"
        ),
    }
    
    for field in missing:
        if field in hint_map:
            hints_en.append(hint_map[field][0])
            hints_zh.append(hint_map[field][1])
    
    return hints_en, hints_zh


def analyze_reviews(reviews: List[Review], asin: str = "UNKNOWN") -> AnalysisResult:
    """MainAnalyzeFunction"""
    if not reviews:
        return AnalysisResult(
            asin=asin,
            total_reviews=0,
            analysis_level=AnalysisLevel.L1_BASIC,
            authenticity_score=50,
            risk_level=RiskLevel.MEDIUM,
            dimensions=[],
            suspicious_reviews=[],
            available_fields=[],
            missing_fields=["content"],
            deepening_hints=["Please provide review data"],
            deepening_hints_zh=["Please provideReview Countdata"],
            summary="No reviews to analyze",
            summary_zh="noReview Countdata"
        )
    
    # ConfirmAnalyzelayerLevel
    level, available, missing = determine_analysis_level(reviews)
    hints_en, hints_zh = generate_deepening_hints(missing)
    
    # ExecuteDetection
    dimensions = []
    
    # L1: BasicDetection (AlwaysExecute)
    dimensions.append(detect_content_similarity(reviews))
    dimensions.append(detect_review_length(reviews))
    dimensions.append(detect_keywords(reviews))
    
    # L2+: TimeDetection
    time_result = detect_time_clustering(reviews)
    if time_result:
        dimensions.append(time_result)
    
    # L3+: RatingDetection
    rating_result = detect_rating_distribution(reviews)
    if rating_result:
        dimensions.append(rating_result)
    
    # L4: VPDetection
    vp_result = detect_vp_ratio(reviews)
    if vp_result:
        dimensions.append(vp_result)
    
    # CalculateComprehensiveScore (WeightedAverageSuspiciousDegree，ThenConvert toAuthenticityScore)
    total_weight = sum(d.weight for d in dimensions)
    if total_weight > 0:
        suspicion_score = sum(d.score * d.weight for d in dimensions) / total_weight
    else:
        suspicion_score = 50
    
    authenticity_score = max(0, min(100, 100 - suspicion_score))
    
    # ConfirmRiskGrade
    if authenticity_score >= 70:
        risk_level = RiskLevel.LOW
    elif authenticity_score >= 50:
        risk_level = RiskLevel.MEDIUM
    elif authenticity_score >= 30:
        risk_level = RiskLevel.HIGH
    else:
        risk_level = RiskLevel.CRITICAL
    
    # IdentifySuspiciousReview
    suspicious = identify_suspicious_reviews(reviews, dimensions)
    
    # GenerateSummary
    risk_text = {
        RiskLevel.LOW: ("Low risk - Reviews appear authentic", "Low Risk - ReviewLooks likeReal"),
        RiskLevel.MEDIUM: ("Medium risk - Some concerns detected", " in  etcRisk - FoundSomeConcern"),
        RiskLevel.HIGH: ("High risk - Multiple red flags", "High Risk -  many DangerSignal"),
        RiskLevel.CRITICAL: ("Critical risk - Likely fake reviews", "CriticalRisk - MayExistLarge amountFakeReview"),
    }
    
    summary_en = f"{risk_text[risk_level][0]}. Analyzed {len(reviews)} reviews at {level.value} level."
    summary_zh = f"{risk_text[risk_level][1]}。Analyze  {len(reviews)} itemReview，AnalyzelayerLevel {level.value}。"
    
    return AnalysisResult(
        asin=asin,
        total_reviews=len(reviews),
        analysis_level=level,
        authenticity_score=round(authenticity_score),
        risk_level=risk_level,
        dimensions=dimensions,
        suspicious_reviews=suspicious,
        available_fields=available,
        missing_fields=missing,
        deepening_hints=hints_en,
        deepening_hints_zh=hints_zh,
        summary=summary_en,
        summary_zh=summary_zh
    )


# ============================================================
# OutputFormat
# ============================================================

def format_report(result: AnalysisResult, lang: str = "en") -> str:
    """FormatReport"""
    risk_icons = {
        RiskLevel.LOW: "✅",
        RiskLevel.MEDIUM: "⚠️",
        RiskLevel.HIGH: "🔴",
        RiskLevel.CRITICAL: "💀",
    }
    
    if lang == "zh":
        lines = [
            f"📊 **ReviewAuthenticityAnalyzeReport**",
            f"",
            f"**ASIN**: {result.asin}",
            f"**Review Count**: {result.total_reviews}",
            f"**AnalyzelayerLevel**: {result.analysis_level.value}",
            f"",
            f"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            f"",
            f"## AuthenticityRating: {result.authenticity_score}/100 {risk_icons[result.risk_level]}",
            f"",
            f"{result.summary_zh}",
            f"",
            f"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            f"",
            f"## DetectiondimensionDegree",
            f"",
        ]
        
        for d in result.dimensions:
            lines.append(f"{d.status} **{d.name_zh}**: {d.score:.0f}/100")
            lines.append(f"   {d.detail_zh}")
            lines.append("")
        
        if result.suspicious_reviews:
            lines.append("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
            lines.append("")
            lines.append(f"## High RiskReview (Top {len(result.suspicious_reviews)})")
            lines.append("")
            for i, sr in enumerate(result.suspicious_reviews[:5], 1):
                lines.append(f"**{i}. Risk {sr.risk_score:.0f}%**")
                lines.append(f'   "{sr.content}"')
                lines.append(f"   Reason: {', '.join(sr.reasons_zh)}")
                lines.append("")
        
        if result.deepening_hints_zh:
            lines.append("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
            lines.append("")
            lines.append("🔍 **Want more accurateAnalyze？Supplement with following info:**")
            lines.append("")
            for hint in result.deepening_hints_zh:
                lines.append(f"• {hint}")
    else:
        lines = [
            f"📊 **Review Authenticity Report**",
            f"",
            f"**ASIN**: {result.asin}",
            f"**Reviews**: {result.total_reviews}",
            f"**Analysis Level**: {result.analysis_level.value}",
            f"",
            f"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            f"",
            f"## Authenticity Score: {result.authenticity_score}/100 {risk_icons[result.risk_level]}",
            f"",
            f"{result.summary}",
            f"",
            f"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            f"",
            f"## Detection Dimensions",
            f"",
        ]
        
        for d in result.dimensions:
            lines.append(f"{d.status} **{d.name}**: {d.score:.0f}/100")
            lines.append(f"   {d.detail}")
            lines.append("")
        
        if result.suspicious_reviews:
            lines.append("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
            lines.append("")
            lines.append(f"## Suspicious Reviews (Top {len(result.suspicious_reviews)})")
            lines.append("")
            for i, sr in enumerate(result.suspicious_reviews[:5], 1):
                lines.append(f"**{i}. Risk {sr.risk_score:.0f}%**")
                lines.append(f'   "{sr.content}"')
                lines.append(f"   Reasons: {', '.join(sr.reasons)}")
                lines.append("")
        
        if result.deepening_hints:
            lines.append("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
            lines.append("")
            lines.append("🔍 **Want more accurate analysis? Add the following:**")
            lines.append("")
            for hint in result.deepening_hints:
                lines.append(f"• {hint}")
    
    return "\n".join(lines)


# ============================================================
# Parse
# ============================================================

def parse_simple_reviews(text: str) -> List[Review]:
    """ParseSimpleTextFormatReview"""
    reviews = []
    
    # TrySplit by paragraph
    paragraphs = re.split(r'\n\n+', text.strip())
    
    for para in paragraphs:
        para = para.strip()
        if len(para) > 10:
            review = Review(content=para)
            
            # TryExtract starLevel
            star_match = re.search(r'(\d)\s*(?:star|★|⭐)', para, re.I)
            if star_match:
                review.rating = int(star_match.group(1))
            
            # TryExtractDayPeriod
            date_match = re.search(r'(\d{4}-\d{2}-\d{2}|\w+\s+\d{1,2},?\s+\d{4})', para)
            if date_match:
                review.date = date_match.group(1)
            
            # TryExtract VP
            if 'verified purchase' in para.lower() or 'VP' in para:
                review.verified_purchase = True
            elif 'not verified' in para.lower():
                review.verified_purchase = False
            
            reviews.append(review)
    
    return reviews


# ============================================================
# CLI Entry Point
# ============================================================

def main():
    """CLI Entry Point"""
    # TestData
    test_reviews = [
        Review(content="Great product! Works perfectly. Highly recommend to everyone.", rating=5, verified_purchase=True, date="2024-01-15"),
        Review(content="Amazing! Best purchase ever. Love it!", rating=5, verified_purchase=False, date="2024-01-15"),
        Review(content="Great product! Works perfectly. Must buy!", rating=5, verified_purchase=False, date="2024-01-16"),
        Review(content="Received free product in exchange for honest review. It's good.", rating=5, verified_purchase=False, date="2024-01-16"),
        Review(content="Excellent quality, fast shipping. Very satisfied with purchase.", rating=5, verified_purchase=True, date="2024-01-20"),
        Review(content="Not as described. Cheap quality.", rating=1, verified_purchase=True, date="2024-02-01"),
        Review(content="Perfect!", rating=5, verified_purchase=False, date="2024-01-16"),
        Review(content="Good value for money. Does what it says.", rating=4, verified_purchase=True, date="2024-02-15"),
        Review(content="Five stars! Amazing product!", rating=5, verified_purchase=False, date="2024-01-17"),
        Review(content="Decent product for the price.", rating=3, verified_purchase=True, date="2024-03-01"),
    ]
    
    # If command lineInput
    if len(sys.argv) > 1:
        arg = sys.argv[1]
        if arg == "--demo":
            pass  # UseTestData
        elif arg.startswith('['):
            # JSON group
            try:
                data = json.loads(arg)
                test_reviews = [Review(**r) for r in data]
            except:
                pass
        else:
            # pureText
            test_reviews = parse_simple_reviews(arg)
    
    result = analyze_reviews(test_reviews, asin="B08XXXXX")
    
    # Default ChineseOutput
    lang = "zh" if "--zh" in sys.argv else "en"
    print(format_report(result, lang))


if __name__ == "__main__":
    main()

FILE:scripts/parser.py
#!/usr/bin/env python3
"""
Review Parser - Multi-format Input Parser
ReviewParse -  many FormatInputParse

SupportFormat:
- pureText (Paragraph separator)
- JSON
- CSV
- TSV
- Markdown Table

Version: 1.0.0
"""

import json
import csv
import re
from typing import List, Optional
from dataclasses import dataclass
from io import StringIO


@dataclass
class Review:
    """Single itemReview"""
    content: str
    rating: Optional[int] = None
    date: Optional[str] = None
    reviewer_name: Optional[str] = None
    verified_purchase: Optional[bool] = None
    helpful_votes: Optional[int] = None
    reviewer_reviews_count: Optional[int] = None


class ReviewParser:
    """ many FormatReviewParse"""
    
    @staticmethod
    def detect_format(text: str) -> str:
        """DetectionInputFormat"""
        text = text.strip()
        
        # JSON group
        if text.startswith('[') and text.endswith(']'):
            try:
                json.loads(text)
                return 'json'
            except:
                pass
        
        # JSON Object
        if text.startswith('{'):
            try:
                json.loads(text)
                return 'json_single'
            except:
                pass
        
        # CSV (CheckComma separated with header)
        lines = text.split('\n')
        if len(lines) > 1:
            first_line = lines[0].lower()
            if ',' in first_line and any(h in first_line for h in ['content', 'review', 'rating', 'date', 'text']):
                return 'csv'
        
        # TSV
        if len(lines) > 1 and '\t' in lines[0]:
            return 'tsv'
        
        # Markdown Table
        if '|' in text and '---' in text:
            return 'markdown'
        
        # DefaultpureText
        return 'text'
    
    @staticmethod
    def parse(text: str) -> List[Review]:
        """ParseReview"""
        format_type = ReviewParser.detect_format(text)
        
        parsers = {
            'json': ReviewParser.parse_json,
            'json_single': ReviewParser.parse_json_single,
            'csv': ReviewParser.parse_csv,
            'tsv': ReviewParser.parse_tsv,
            'markdown': ReviewParser.parse_markdown,
            'text': ReviewParser.parse_text,
        }
        
        parser = parsers.get(format_type, ReviewParser.parse_text)
        return parser(text)
    
    @staticmethod
    def parse_json(text: str) -> List[Review]:
        """Parse JSON group"""
        try:
            data = json.loads(text)
            reviews = []
            for item in data:
                review = Review(
                    content=item.get('content', item.get('text', item.get('review', ''))),
                    rating=item.get('rating', item.get('stars', item.get('star'))),
                    date=item.get('date', item.get('review_date')),
                    reviewer_name=item.get('reviewer_name', item.get('author', item.get('name'))),
                    verified_purchase=item.get('verified_purchase', item.get('vp', item.get('verified'))),
                    helpful_votes=item.get('helpful_votes', item.get('helpful')),
                )
                if review.content:
                    reviews.append(review)
            return reviews
        except:
            return []
    
    @staticmethod
    def parse_json_single(text: str) -> List[Review]:
        """ParseSingle JSON Object"""
        try:
            item = json.loads(text)
            review = Review(
                content=item.get('content', item.get('text', item.get('review', ''))),
                rating=item.get('rating', item.get('stars')),
                date=item.get('date'),
                reviewer_name=item.get('reviewer_name', item.get('author')),
                verified_purchase=item.get('verified_purchase', item.get('vp')),
            )
            return [review] if review.content else []
        except:
            return []
    
    @staticmethod
    def parse_csv(text: str) -> List[Review]:
        """Parse CSV"""
        reviews = []
        try:
            reader = csv.DictReader(StringIO(text))
            for row in reader:
                # TryMultipleField name
                content = (
                    row.get('content') or row.get('Content') or
                    row.get('review') or row.get('Review') or
                    row.get('text') or row.get('Text') or
                    row.get('review_text') or row.get('body') or ''
                )
                
                rating_str = (
                    row.get('rating') or row.get('Rating') or
                    row.get('stars') or row.get('Stars') or
                    row.get('star') or ''
                )
                rating = None
                if rating_str:
                    try:
                        rating = int(float(rating_str))
                    except:
                        pass
                
                date = (
                    row.get('date') or row.get('Date') or
                    row.get('review_date') or row.get('created_at') or None
                )
                
                vp_str = (
                    row.get('verified_purchase') or row.get('vp') or
                    row.get('verified') or row.get('VP') or ''
                )
                vp = None
                if vp_str:
                    vp = vp_str.lower() in ['true', 'yes', '1', 'y', 'verified']
                
                reviewer = (
                    row.get('reviewer_name') or row.get('author') or
                    row.get('name') or row.get('reviewer') or None
                )
                
                if content:
                    reviews.append(Review(
                        content=content,
                        rating=rating,
                        date=date,
                        reviewer_name=reviewer,
                        verified_purchase=vp,
                    ))
        except Exception as e:
            print(f"CSV parse error: {e}")
        
        return reviews
    
    @staticmethod
    def parse_tsv(text: str) -> List[Review]:
        """Parse TSV"""
        # Convert to CSV FormatProcess
        csv_text = text.replace('\t', ',')
        return ReviewParser.parse_csv(csv_text)
    
    @staticmethod
    def parse_markdown(text: str) -> List[Review]:
        """Parse Markdown Table"""
        reviews = []
        lines = text.strip().split('\n')
        
        # find to Tablehead
        header_line = None
        data_start = 0
        for i, line in enumerate(lines):
            if '|' in line and '---' not in line:
                header_line = line
                data_start = i + 2  # Skip separator lines
                break
        
        if not header_line:
            return []
        
        # ParseTablehead
        headers = [h.strip().lower() for h in header_line.split('|') if h.strip()]
        
        # ParseDatarow
        for line in lines[data_start:]:
            if '|' not in line:
                continue
            
            cells = [c.strip() for c in line.split('|') if c.strip()]
            if len(cells) < len(headers):
                continue
            
            row = dict(zip(headers, cells))
            
            content = row.get('content', row.get('review', row.get('text', '')))
            rating = None
            rating_str = row.get('rating', row.get('stars', ''))
            if rating_str:
                try:
                    rating = int(float(rating_str.replace('★', '').strip()))
                except:
                    pass
            
            if content:
                reviews.append(Review(
                    content=content,
                    rating=rating,
                    date=row.get('date'),
                    reviewer_name=row.get('author', row.get('reviewer')),
                ))
        
        return reviews
    
    @staticmethod
    def parse_text(text: str) -> List[Review]:
        """ParsepureText"""
        reviews = []
        
        # TrySplit by paragraph
        paragraphs = re.split(r'\n\n+', text.strip())
        
        for para in paragraphs:
            para = para.strip()
            if len(para) < 10:
                continue
            
            review = Review(content=para)
            
            # TryExtract starLevel
            star_patterns = [
                r'(\d)\s*(?:star|stars|★|⭐)',
                r'(?:star|stars|rating)[:\s]*(\d)',
                r'^(\d)★',
                r'^(\d)\s*star',
            ]
            for pattern in star_patterns:
                match = re.search(pattern, para, re.I)
                if match:
                    review.rating = int(match.group(1))
                    break
            
            # TryExtractDayPeriod
            date_patterns = [
                r'(\d{4}-\d{2}-\d{2})',
                r'(\w+\s+\d{1,2},?\s+\d{4})',
                r'(\d{1,2}/\d{1,2}/\d{4})',
            ]
            for pattern in date_patterns:
                match = re.search(pattern, para)
                if match:
                    review.date = match.group(1)
                    break
            
            # TryExtract VP Status
            if re.search(r'verified\s*purchase', para, re.I):
                review.verified_purchase = True
            elif re.search(r'not\s*verified', para, re.I):
                review.verified_purchase = False
            
            reviews.append(review)
        
        return reviews


def parse_reviews(text: str) -> List[Review]:
    """ConvenientFunction"""
    return ReviewParser.parse(text)


# CLI
if __name__ == "__main__":
    import sys
    
    if len(sys.argv) > 1:
        text = sys.argv[1]
    else:
        # TestData
        text = """
content,rating,date,verified_purchase
"Great product!",5,2024-01-15,true
"Not good",2,2024-01-16,false
"Amazing!",5,2024-01-17,true
"""
    
    reviews = parse_reviews(text)
    print(f"Parsed {len(reviews)} reviews:")
    for r in reviews:
        print(f"  - {r.rating}★ | VP:{r.verified_purchase} | {r.content[:50]}...")

FILE:scripts/report_html.py
#!/usr/bin/env python3
"""
Review Analysis HTML Report Generator
ReviewAnalyze HTML ReportGenerate

Features:
- CanViewTable (Chart.js)
- Responsive layout
-  deep colorMaintopic
- InteractiveDataDisplay

Version: 1.0.0
"""

import json
from typing import List, Dict, Any
from datetime import datetime


def generate_html_report(
    asin: str,
    authenticity_score: int,
    risk_level: str,
    dimensions: List[Dict[str, Any]],
    suspicious_reviews: List[Dict[str, Any]],
    total_reviews: int,
    analysis_level: str,
    summary: str,
    output_path: str = "review_analysis_report.html"
) -> str:
    """Generate HTML Report"""
    
    # RiskGradeColor
    risk_colors = {
        "low": "#10b981",      # Green
        "medium": "#f59e0b",   # Yellow
        "high": "#ef4444",     # Red
        "critical": "#7c2d12", #  deep red
    }
    
    risk_color = risk_colors.get(risk_level.lower(), "#6b7280")
    
    # dimensionDegreeData (use at chartTable)
    dimension_labels = json.dumps([d.get('name', d.get('name_zh', '')) for d in dimensions])
    dimension_scores = json.dumps([d.get('score', 0) for d in dimensions])
    
    # SuspiciousReview JSON
    suspicious_json = json.dumps(suspicious_reviews[:10], ensure_ascii=False, default=str)
    
    html = f"""<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Review Analysis Report - {asin}</title>
    <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
    <style>
        * {{
            margin: 0;
            padding: 0;
            box-sizing: border-box;
        }}
        
        body {{
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
            background: linear-gradient(135deg, #1a1a2e 0%, #16213e 100%);
            color: #e4e4e7;
            min-height: 100vh;
            padding: 20px;
        }}
        
        .container {{
            max-width: 1200px;
            margin: 0 auto;
        }}
        
        .header {{
            text-align: center;
            padding: 40px 20px;
            background: rgba(255,255,255,0.05);
            border-radius: 16px;
            margin-bottom: 30px;
        }}
        
        .header h1 {{
            font-size: 2rem;
            background: linear-gradient(90deg, #a78bfa, #818cf8);
            -webkit-background-clip: text;
            -webkit-text-fill-color: transparent;
            margin-bottom: 10px;
        }}
        
        .header .asin {{
            color: #a1a1aa;
            font-size: 1.1rem;
        }}
        
        .score-card {{
            background: rgba(255,255,255,0.08);
            border-radius: 16px;
            padding: 40px;
            text-align: center;
            margin-bottom: 30px;
            border: 1px solid rgba(255,255,255,0.1);
        }}
        
        .score-number {{
            font-size: 5rem;
            font-weight: bold;
            color: {risk_color};
            line-height: 1;
        }}
        
        .score-label {{
            font-size: 1.2rem;
            color: #a1a1aa;
            margin-top: 10px;
        }}
        
        .risk-badge {{
            display: inline-block;
            padding: 8px 20px;
            border-radius: 20px;
            background: {risk_color};
            color: white;
            font-weight: 600;
            margin-top: 15px;
            text-transform: uppercase;
        }}
        
        .grid {{
            display: grid;
            grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
            gap: 20px;
            margin-bottom: 30px;
        }}
        
        .card {{
            background: rgba(255,255,255,0.08);
            border-radius: 12px;
            padding: 24px;
            border: 1px solid rgba(255,255,255,0.1);
        }}
        
        .card h3 {{
            font-size: 1.1rem;
            margin-bottom: 20px;
            color: #a78bfa;
        }}
        
        .stat {{
            display: flex;
            justify-content: space-between;
            padding: 12px 0;
            border-bottom: 1px solid rgba(255,255,255,0.1);
        }}
        
        .stat:last-child {{
            border-bottom: none;
        }}
        
        .stat-label {{
            color: #a1a1aa;
        }}
        
        .stat-value {{
            font-weight: 600;
        }}
        
        .chart-container {{
            position: relative;
            height: 300px;
            width: 100%;
        }}
        
        .dimension-item {{
            display: flex;
            align-items: center;
            padding: 12px 0;
            border-bottom: 1px solid rgba(255,255,255,0.1);
        }}
        
        .dimension-icon {{
            width: 30px;
            font-size: 1.2rem;
        }}
        
        .dimension-name {{
            flex: 1;
        }}
        
        .dimension-score {{
            font-weight: 600;
            width: 80px;
            text-align: right;
        }}
        
        .suspicious-item {{
            background: rgba(239, 68, 68, 0.1);
            border: 1px solid rgba(239, 68, 68, 0.3);
            border-radius: 8px;
            padding: 16px;
            margin-bottom: 12px;
        }}
        
        .suspicious-header {{
            display: flex;
            justify-content: space-between;
            margin-bottom: 8px;
        }}
        
        .suspicious-risk {{
            color: #ef4444;
            font-weight: 600;
        }}
        
        .suspicious-content {{
            color: #d4d4d8;
            font-style: italic;
            margin-bottom: 8px;
        }}
        
        .suspicious-reasons {{
            color: #a1a1aa;
            font-size: 0.9rem;
        }}
        
        .summary {{
            background: rgba(167, 139, 250, 0.1);
            border: 1px solid rgba(167, 139, 250, 0.3);
            border-radius: 12px;
            padding: 20px;
            margin-bottom: 30px;
        }}
        
        .footer {{
            text-align: center;
            padding: 20px;
            color: #71717a;
            font-size: 0.9rem;
        }}
        
        @media (max-width: 768px) {{
            .score-number {{
                font-size: 3rem;
            }}
            .grid {{
                grid-template-columns: 1fr;
            }}
        }}
    </style>
</head>
<body>
    <div class="container">
        <div class="header">
            <h1>📊 Review Authenticity Analysis</h1>
            <div class="asin">ASIN: {asin}</div>
        </div>
        
        <div class="score-card">
            <div class="score-number">{authenticity_score}</div>
            <div class="score-label">Authenticity Score (0-100)</div>
            <div class="risk-badge">{risk_level.upper()} RISK</div>
        </div>
        
        <div class="summary">
            <strong>Summary:</strong> {summary}
        </div>
        
        <div class="grid">
            <div class="card">
                <h3>📈 Overview</h3>
                <div class="stat">
                    <span class="stat-label">Total Reviews</span>
                    <span class="stat-value">{total_reviews}</span>
                </div>
                <div class="stat">
                    <span class="stat-label">Analysis Level</span>
                    <span class="stat-value">{analysis_level}</span>
                </div>
                <div class="stat">
                    <span class="stat-label">Suspicious Reviews</span>
                    <span class="stat-value">{len(suspicious_reviews)}</span>
                </div>
                <div class="stat">
                    <span class="stat-label">Generated</span>
                    <span class="stat-value">{datetime.now().strftime('%Y-%m-%d %H:%M')}</span>
                </div>
            </div>
            
            <div class="card">
                <h3>🎯 Detection Dimensions</h3>
                <div class="chart-container">
                    <canvas id="dimensionChart"></canvas>
                </div>
            </div>
        </div>
        
        <div class="card" style="margin-bottom: 30px;">
            <h3>🔍 Dimension Details</h3>
            {"".join([f'''
            <div class="dimension-item">
                <div class="dimension-icon">{d.get('status', '❓')}</div>
                <div class="dimension-name">{d.get('name', d.get('name_zh', ''))}</div>
                <div class="dimension-score" style="color: {'#10b981' if d.get('score', 0) < 30 else '#f59e0b' if d.get('score', 0) < 60 else '#ef4444'}">{d.get('score', 0):.0f}/100</div>
            </div>
            <div style="color: #a1a1aa; font-size: 0.9rem; padding-left: 30px; padding-bottom: 12px;">{d.get('detail', d.get('detail_zh', ''))}</div>
            ''' for d in dimensions])}
        </div>
        
        <div class="card">
            <h3>⚠️ Suspicious Reviews (Top {min(len(suspicious_reviews), 5)})</h3>
            <div id="suspiciousReviews"></div>
        </div>
        
        <div class="footer">
            <p>Generated by Amazon Review Checker | Nexscope AI</p>
            <p>This analysis is for reference only. Results may not be 100% accurate.</p>
        </div>
    </div>
    
    <script>
        // dimensionDegreeRadar chart
        const ctx = document.getElementById('dimensionChart').getContext('2d');
        new Chart(ctx, {{
            type: 'radar',
            data: {{
                labels: {dimension_labels},
                datasets: [{{
                    label: 'Suspicion Score',
                    data: {dimension_scores},
                    backgroundColor: 'rgba(167, 139, 250, 0.2)',
                    borderColor: 'rgba(167, 139, 250, 1)',
                    borderWidth: 2,
                    pointBackgroundColor: 'rgba(167, 139, 250, 1)',
                }}]
            }},
            options: {{
                responsive: true,
                maintainAspectRatio: false,
                scales: {{
                    r: {{
                        beginAtZero: true,
                        max: 100,
                        ticks: {{
                            color: '#a1a1aa',
                            backdropColor: 'transparent'
                        }},
                        grid: {{
                            color: 'rgba(255,255,255,0.1)'
                        }},
                        pointLabels: {{
                            color: '#e4e4e7',
                            font: {{ size: 11 }}
                        }}
                    }}
                }},
                plugins: {{
                    legend: {{
                        display: false
                    }}
                }}
            }}
        }});
        
        // SuspiciousReview
        const suspicious = {suspicious_json};
        const container = document.getElementById('suspiciousReviews');
        
        if (suspicious.length === 0) {{
            container.innerHTML = '<p style="color: #10b981;">No highly suspicious reviews detected.</p>';
        }} else {{
            suspicious.slice(0, 5).forEach((review, index) => {{
                container.innerHTML += `
                    <div class="suspicious-item">
                        <div class="suspicious-header">
                            <span>#{index + 1}</span>
                            <span class="suspicious-risk">Risk: {review.risk_score?.toFixed(0) || 'N/A'}%</span>
                        </div>
                        <div class="suspicious-content">"{review.content}"</div>
                        <div class="suspicious-reasons">Reasons: {(review.reasons || review.reasons_zh || []).join(', ')}</div>
                    </div>
                `;
            }});
        }}
    </script>
</body>
</html>
"""
    
    # SaveFile
    with open(output_path, 'w', encoding='utf-8') as f:
        f.write(html)
    
    print(f"✅ HTML report saved to: {output_path}")
    return output_path


# CLI
if __name__ == "__main__":
    # TestData
    generate_html_report(
        asin="B08XXXXX",
        authenticity_score=66,
        risk_level="medium",
        dimensions=[
            {"name": "Content Similarity", "name_zh": "Similar contentDegree", "score": 24, "status": "✅", "detail": "Found 0 similar review pairs"},
            {"name": "Time Clustering", "name_zh": "TimeAggregate", "score": 70, "status": "🔴", "detail": "6 reviews in 48h window"},
            {"name": "Rating Distribution", "name_zh": "Rating Distribution", "score": 0, "status": "✅", "detail": "Normal distribution"},
            {"name": "VP Ratio", "name_zh": "VPRatio", "score": 30, "status": "⚠️", "detail": "50% verified purchase"},
            {"name": "Review Length", "name_zh": "ReviewDegree", "score": 0, "status": "✅", "detail": "Normal length distribution"},
            {"name": "Suspicious Keywords", "name_zh": "SuspiciousKeywords", "score": 80, "status": "🔴", "detail": "4 reviews contain suspicious keywords"},
        ],
        suspicious_reviews=[
            {"content": "Perfect!", "risk_score": 75, "reasons": ["Very short", "Not VP", "Generic template"]},
            {"content": "Five stars! Amazing product!", "risk_score": 75, "reasons": ["Very short", "Not VP", "Generic template"]},
            {"content": "Received free product in exchange for honest review...", "risk_score": 60, "reasons": ["Not VP", "Incentivized review"]},
        ],
        total_reviews=10,
        analysis_level="L4",
        summary="Medium risk - Some concerns detected. Analyzed 10 reviews at L4 level.",
        output_path="review_analysis_report.html"
    )

Ebay Review Checker

Skill

eBay review and feedback authenticity analyzer. Detect fake reviews, suspicious seller feedback patterns, and buyer manipulation. Includes time clustering de...

---
name: ebay-review-checker
version: 1.0.0
description: "eBay review and feedback authenticity analyzer. Detect fake reviews, suspicious seller feedback patterns, and buyer manipulation. Includes time clustering detection, content similarity analysis, and eBay-specific red flag identification. No API key required."
metadata: {"nexscope":{"emoji":"🔍","category":"ecommerce"}}
---

# eBay Review Checker 🔍

Review and feedback authenticity analyzer for eBay — detect fake reviews, suspicious patterns, and feedback manipulation.

## Installation

```bash
npx skills add nexscope-ai/eCommerce-Skills --skill ebay-review-checker -g
```

## Features

- **Seller Feedback Analysis** — Analyze seller feedback authenticity
- **Buyer Feedback Patterns** — Detect suspicious buyer behavior
- **eBay-specific Red Flags** — Platform-specific warning signs
- **Progressive Analysis** — More data = deeper insights

## eBay-Specific Detection

| Signal | Description |
|--------|-------------|
| Feedback timing | Clustered feedback in short periods |
| Generic comments | "A+++" or "Great seller" patterns |
| Account age | New accounts leaving multiple feedbacks |
| Transaction patterns | Unusual buying/selling patterns |

## Risk Levels

| Score | Level | Description |
|-------|-------|-------------|
| 70-100 | ✅ Low Risk | Feedback appears authentic |
| 50-69 | ⚠️ Medium Risk | Some concerns found |
| 30-49 | 🔴 High Risk | Multiple red flags |
| 0-29 | 💀 Critical | Likely manipulated feedback |

## Usage

### Paste Feedback

```
Check this seller feedback:

Positive - Great seller, fast shipping! A+++
Positive - Excellent transaction, thank you!
Positive - Perfect! Would buy again.
Negative - Item never arrived.
```

### JSON Input

```bash
python3 scripts/analyzer.py '[
  {"content": "A+++ seller!", "rating": "positive", "date": "2024-01-15"},
  {"content": "Fast shipping", "rating": "positive", "date": "2024-01-15"}
]'
```

## Output Example

```
📊 eBay Feedback Authenticity Report

Seller: example_seller
Feedback Count: 50
Analysis Level: L3

━━━━━━━━━━━━━━━━━━━━━━━━

Authenticity Score: 72/100 ✅

Low Risk - Feedback appears authentic.

━━━━━━━━━━━━━━━━━━━━━━━━

Detection Results

✅ Time Clustering: Normal
⚠️ Generic Comments: 15% (slightly high)
✅ Account Diversity: Good
```

---

**Part of [Nexscope AI](https://www.nexscope.ai/) — AI tools for e-commerce sellers.**

FILE:scripts/analyzer.py
#!/usr/bin/env python3
"""
Amazon Review Checker - Core Analyzer
AmazonReviewAuthenticityDetection - CoreAnalyzeEngine

Features:
- ProgressiveAnalyze ( has  many  few Data，Give conclusion)
-  many dimensionDegreeDetection (Time/Content/Rating/Account/VP)
- Friendly guidance (HintCanDeepenDirection)

Version: 1.0.0
"""

import json
import re
import math
from dataclasses import dataclass, field
from typing import List, Dict, Optional, Tuple
from datetime import datetime, timedelta
from collections import Counter
from enum import Enum
import sys


class RiskLevel(Enum):
    LOW = "low"           # 0-30
    MEDIUM = "medium"     # 31-60
    HIGH = "high"         # 61-80
    CRITICAL = "critical" # 81-100


class AnalysisLevel(Enum):
    L1_BASIC = "L1"      # onlyContent
    L2_TIMED = "L2"      # + Time
    L3_SCORED = "L3"     # + Rating
    L4_FULL = "L4"       #  all Field


# ============================================================
# Data Structures
# ============================================================

@dataclass
class Review:
    """Single itemReview"""
    content: str
    rating: Optional[int] = None          # 1-5 star
    date: Optional[str] = None            # DayPeriod
    reviewer_name: Optional[str] = None   # Reviewperson
    verified_purchase: Optional[bool] = None  # VP
    helpful_votes: Optional[int] = None   #  has Help
    reviewer_reviews_count: Optional[int] = None  # ReviewTotalReview Count
    
    @property
    def has_rating(self) -> bool:
        return self.rating is not None
    
    @property
    def has_date(self) -> bool:
        return self.date is not None
    
    @property
    def has_vp(self) -> bool:
        return self.verified_purchase is not None


@dataclass
class DimensionResult:
    """Single dimensionDegreeDetectionResult"""
    name: str
    name_zh: str
    score: float          # 0-100, exceedHighexceedSuspicious
    status: str           # ✅ ⚠️ 🔴
    detail: str
    detail_zh: str
    weight: float = 0.0


@dataclass
class SuspiciousReview:
    """SuspiciousReview"""
    content: str
    risk_score: float
    reasons: List[str]
    reasons_zh: List[str]


@dataclass
class AnalysisResult:
    """AnalyzeResult"""
    asin: str
    total_reviews: int
    analysis_level: AnalysisLevel
    authenticity_score: int       # 0-100, exceedHighexceedReal
    risk_level: RiskLevel
    dimensions: List[DimensionResult]
    suspicious_reviews: List[SuspiciousReview]
    available_fields: List[str]
    missing_fields: List[str]
    deepening_hints: List[str]
    deepening_hints_zh: List[str]
    summary: str
    summary_zh: str


# ============================================================
# DetectionAlgorithm
# ============================================================

def detect_content_similarity(reviews: List[Review]) -> DimensionResult:
    """DetectionSimilar contentDegree"""
    if len(reviews) < 2:
        return DimensionResult(
            name="Content Similarity",
            name_zh="Similar contentDegree",
            score=0,
            status="✅",
            detail="Not enough reviews to compare",
            detail_zh="Review CountInsufficient，CannotComparison",
            weight=0.20
        )
    
    # Simple similarityDegreeDetection：CheckRepeated phrases
    contents = [r.content.lower() for r in reviews]
    
    # Extract3-gram
    def get_ngrams(text, n=3):
        words = re.findall(r'\w+', text)
        return [' '.join(words[i:i+n]) for i in range(len(words)-n+1)]
    
    all_ngrams = []
    for content in contents:
        all_ngrams.extend(get_ngrams(content))
    
    # Statistics heavy complex
    ngram_counts = Counter(all_ngrams)
    repeated = sum(1 for count in ngram_counts.values() if count > 1)
    total = len(ngram_counts) if ngram_counts else 1
    
    similarity_ratio = repeated / total if total > 0 else 0
    score = min(100, similarity_ratio * 500)  # put big 
    
    # CheckHighDegreeSimilarReview for 
    similar_pairs = 0
    for i, c1 in enumerate(contents):
        for c2 in contents[i+1:]:
            if len(c1) > 20 and len(c2) > 20:
                # Simple Jaccard SimilarDegree
                set1, set2 = set(c1.split()), set(c2.split())
                if set1 and set2:
                    jaccard = len(set1 & set2) / len(set1 | set2)
                    if jaccard > 0.5:
                        similar_pairs += 1
    
    if similar_pairs > 0:
        score = max(score, 50 + similar_pairs * 10)
    
    score = min(100, score)
    
    if score < 30:
        status = "✅"
    elif score < 60:
        status = "⚠️"
    else:
        status = "🔴"
    
    return DimensionResult(
        name="Content Similarity",
        name_zh="Similar contentDegree",
        score=round(score, 1),
        status=status,
        detail=f"Found {similar_pairs} similar review pairs",
        detail_zh=f"Found {similar_pairs} groupHighDegreeSimilarReview",
        weight=0.20
    )


def detect_time_clustering(reviews: List[Review]) -> Optional[DimensionResult]:
    """DetectionTimeAggregate"""
    dated_reviews = [r for r in reviews if r.has_date]
    
    if len(dated_reviews) < 5:
        return None  # DataInsufficient
    
    # ParseDayPeriod
    dates = []
    for r in dated_reviews:
        try:
            # TryMultipleFormat
            for fmt in ['%Y-%m-%d', '%B %d, %Y', '%d %B %Y', '%m/%d/%Y']:
                try:
                    dates.append(datetime.strptime(r.date, fmt))
                    break
                except:
                    continue
        except:
            pass
    
    if len(dates) < 5:
        return None
    
    dates.sort()
    
    # CalculateAdjacentReviewTimeseparate
    intervals = [(dates[i+1] - dates[i]).days for i in range(len(dates)-1)]
    
    if not intervals:
        return None
    
    # DetectionAggregate： short Time inside Large amountReview
    short_intervals = sum(1 for i in intervals if i <= 1)  # 1days inside 
    clustering_ratio = short_intervals / len(intervals)
    
    # Detection 48h Outbreak
    burst_count = 0
    window_size = 2  # 2daysWindow
    for i in range(len(dates) - 1):
        count_in_window = sum(1 for d in dates if 0 <= (d - dates[i]).days <= window_size)
        burst_count = max(burst_count, count_in_window)
    
    score = 0
    if clustering_ratio > 0.5:
        score += 40
    if clustering_ratio > 0.7:
        score += 20
    if burst_count > len(dates) * 0.3:
        score += 30
    
    score = min(100, score)
    
    if score < 30:
        status = "✅"
    elif score < 60:
        status = "⚠️"
    else:
        status = "🔴"
    
    return DimensionResult(
        name="Time Clustering",
        name_zh="TimeAggregate",
        score=round(score, 1),
        status=status,
        detail=f"Max {burst_count} reviews in 48h window, {clustering_ratio*100:.0f}% within 1 day",
        detail_zh=f"48h inside  most  many  {burst_count} itemReview，{clustering_ratio*100:.0f}%  in 1days inside ",
        weight=0.25
    )


def detect_rating_distribution(reviews: List[Review]) -> Optional[DimensionResult]:
    """DetectionRating Distribution"""
    rated_reviews = [r for r in reviews if r.has_rating]
    
    if len(rated_reviews) < 5:
        return None
    
    ratings = [r.rating for r in rated_reviews]
    rating_counts = Counter(ratings)
    total = len(ratings)
    
    # CalculateDistribution
    five_star_ratio = rating_counts.get(5, 0) / total
    one_star_ratio = rating_counts.get(1, 0) / total
    extreme_ratio = five_star_ratio + one_star_ratio
    
    # Natural distribution usually is：5star ~50-60%, 4star ~20%, 3star ~10%, 2star ~5%, 1star ~10%
    # Abnormal case： all 5star、Polarized
    
    score = 0
    anomaly_detail = []
    
    if five_star_ratio > 0.85:
        score += 50
        anomaly_detail.append(f"{five_star_ratio*100:.0f}% 5-star (abnormal)")
    elif five_star_ratio > 0.75:
        score += 30
        anomaly_detail.append(f"{five_star_ratio*100:.0f}% 5-star (suspicious)")
    
    # Polarized
    if extreme_ratio > 0.9 and one_star_ratio > 0.1:
        score += 30
        anomaly_detail.append("Polarized distribution")
    
    # MissingMiddleRating
    mid_ratings = sum(rating_counts.get(r, 0) for r in [2, 3, 4])
    if mid_ratings / total < 0.1 and total > 10:
        score += 20
        anomaly_detail.append("Missing mid-range ratings")
    
    score = min(100, score)
    
    if score < 30:
        status = "✅"
    elif score < 60:
        status = "⚠️"
    else:
        status = "🔴"
    
    dist_str = ", ".join([f"{r}★:{rating_counts.get(r,0)}" for r in [5,4,3,2,1]])
    
    return DimensionResult(
        name="Rating Distribution",
        name_zh="Rating Distribution",
        score=round(score, 1),
        status=status,
        detail=f"Distribution: {dist_str}. {'; '.join(anomaly_detail) if anomaly_detail else 'Normal'}",
        detail_zh=f"Distribution: {dist_str}。{'; '.join(anomaly_detail) if anomaly_detail else 'Normal'}",
        weight=0.20
    )


def detect_vp_ratio(reviews: List[Review]) -> Optional[DimensionResult]:
    """Detection Verified Purchase Ratio"""
    vp_reviews = [r for r in reviews if r.has_vp]
    
    if len(vp_reviews) < 5:
        return None
    
    vp_count = sum(1 for r in vp_reviews if r.verified_purchase)
    vp_ratio = vp_count / len(vp_reviews)
    
    # Normal VP Ratio should  should  in  60-80%
    score = 0
    if vp_ratio < 0.4:
        score = 70
    elif vp_ratio < 0.5:
        score = 50
    elif vp_ratio < 0.6:
        score = 30
    else:
        score = 10
    
    if score < 30:
        status = "✅"
    elif score < 60:
        status = "⚠️"
    else:
        status = "🔴"
    
    return DimensionResult(
        name="Verified Purchase Ratio",
        name_zh="VPRatio",
        score=round(score, 1),
        status=status,
        detail=f"{vp_ratio*100:.0f}% verified purchase ({vp_count}/{len(vp_reviews)})",
        detail_zh=f"{vp_ratio*100:.0f}%  already VerifyPurchase ({vp_count}/{len(vp_reviews)})",
        weight=0.15
    )


def detect_review_length(reviews: List[Review]) -> DimensionResult:
    """DetectionReviewDegreeDistribution"""
    lengths = [len(r.content) for r in reviews]
    
    if not lengths:
        return DimensionResult(
            name="Review Length",
            name_zh="ReviewDegree",
            score=0,
            status="✅",
            detail="No reviews",
            detail_zh="noReview",
            weight=0.05
        )
    
    avg_length = sum(lengths) / len(lengths)
    short_count = sum(1 for l in lengths if l < 50)
    short_ratio = short_count / len(lengths)
    
    # DetectionTemplate（DegreeHighDegreeConsistent）
    if len(lengths) > 5:
        length_std = (sum((l - avg_length) ** 2 for l in lengths) / len(lengths)) ** 0.5
        cv = length_std / avg_length if avg_length > 0 else 0  # Variation coefficient
    else:
        cv = 1
    
    score = 0
    if short_ratio > 0.7:
        score += 40
    if cv < 0.3 and len(lengths) > 10:  # DegreeToo consistent
        score += 40
    
    score = min(100, score)
    
    if score < 30:
        status = "✅"
    elif score < 60:
        status = "⚠️"
    else:
        status = "🔴"
    
    return DimensionResult(
        name="Review Length",
        name_zh="ReviewDegree",
        score=round(score, 1),
        status=status,
        detail=f"Avg length: {avg_length:.0f} chars, {short_ratio*100:.0f}% short (<50)",
        detail_zh=f"AverageDegree: {avg_length:.0f} Character, {short_ratio*100:.0f}%   short  (<50)",
        weight=0.05
    )


def detect_keywords(reviews: List[Review]) -> DimensionResult:
    """DetectionFake ordersKeywords"""
    # Common fake ordersReviewKeywords
    suspicious_keywords = [
        'received free', 'free product', 'in exchange', 'honest review',
        'discount code', 'promotional', 'gifted', 'complimentary',
        'five stars', '5 stars', 'best ever', 'amazing product',
        'highly recommend', 'must buy', 'perfect product',
        #  in text
        'Positive ReviewCashback', 'Five starPositive Review', 'Free trial', 'Gift'
    ]
    
    keyword_hits = 0
    for review in reviews:
        content_lower = review.content.lower()
        for keyword in suspicious_keywords:
            if keyword.lower() in content_lower:
                keyword_hits += 1
                break
    
    hit_ratio = keyword_hits / len(reviews) if reviews else 0
    score = min(100, hit_ratio * 200)
    
    if score < 30:
        status = "✅"
    elif score < 60:
        status = "⚠️"
    else:
        status = "🔴"
    
    return DimensionResult(
        name="Suspicious Keywords",
        name_zh="SuspiciousKeywords",
        score=round(score, 1),
        status=status,
        detail=f"{keyword_hits} reviews contain suspicious keywords",
        detail_zh=f"{keyword_hits} itemReviewPackagecontainSuspiciousKeywords",
        weight=0.05
    )


def identify_suspicious_reviews(reviews: List[Review], dimensions: List[DimensionResult]) -> List[SuspiciousReview]:
    """IdentifyHigh RiskReview"""
    suspicious = []
    
    for review in reviews:
        risk_score = 0
        reasons = []
        reasons_zh = []
        
        #  short Review
        if len(review.content) < 30:
            risk_score += 20
            reasons.append("Very short review")
            reasons_zh.append("Review  short ")
        
        # non VP
        if review.has_vp and not review.verified_purchase:
            risk_score += 25
            reasons.append("Not verified purchase")
            reasons_zh.append("nonVerifyPurchase")
        
        # ExtremeRating + TemplateContent
        if review.has_rating and review.rating == 5:
            generic_phrases = ['great', 'amazing', 'perfect', 'love it', 'best', 'excellent']
            if any(p in review.content.lower() for p in generic_phrases) and len(review.content) < 100:
                risk_score += 30
                reasons.append("Generic 5-star template")
                reasons_zh.append("Template5starPositive Review")
        
        # SuspiciousKeywords
        suspicious_keywords = ['received free', 'in exchange', 'honest review', 'discount']
        if any(k in review.content.lower() for k in suspicious_keywords):
            risk_score += 35
            reasons.append("Contains incentivized review keywords")
            reasons_zh.append("Contains incentiveReviewKeywords")
        
        if risk_score >= 40:
            suspicious.append(SuspiciousReview(
                content=review.content[:100] + "..." if len(review.content) > 100 else review.content,
                risk_score=min(100, risk_score),
                reasons=reasons,
                reasons_zh=reasons_zh
            ))
    
    #  by RiskScoreSort
    suspicious.sort(key=lambda x: x.risk_score, reverse=True)
    return suspicious[:10]  # Top 10


def determine_analysis_level(reviews: List[Review]) -> Tuple[AnalysisLevel, List[str], List[str]]:
    """ConfirmAnalyzelayerLevelAndMissing field"""
    available = ["content"]
    missing = []
    
    has_rating = any(r.has_rating for r in reviews)
    has_date = any(r.has_date for r in reviews)
    has_vp = any(r.has_vp for r in reviews)
    has_reviewer = any(r.reviewer_name for r in reviews)
    
    if has_rating:
        available.append("rating")
    else:
        missing.append("rating")
    
    if has_date:
        available.append("date")
    else:
        missing.append("date")
    
    if has_vp:
        available.append("verified_purchase")
    else:
        missing.append("verified_purchase")
    
    if has_reviewer:
        available.append("reviewer_info")
    else:
        missing.append("reviewer_info")
    
    # Determine levelLevel
    if has_rating and has_date and has_vp:
        level = AnalysisLevel.L4_FULL
    elif has_rating and has_date:
        level = AnalysisLevel.L3_SCORED
    elif has_date:
        level = AnalysisLevel.L2_TIMED
    else:
        level = AnalysisLevel.L1_BASIC
    
    return level, available, missing


def generate_deepening_hints(missing: List[str]) -> Tuple[List[str], List[str]]:
    """GenerateDeepenHint"""
    hints_en = []
    hints_zh = []
    
    hint_map = {
        "rating": (
            "Add star ratings → Unlock 'Rating Distribution Analysis'",
            "Add starLevelRating → Unlock「Rating DistributionAnalyze」"
        ),
        "date": (
            "Add review dates → Unlock 'Time Clustering Detection'",
            "SupplementReviewDayPeriod → Unlock「TimeAggregateDetection」"
        ),
        "verified_purchase": (
            "Add VP status → Unlock 'Verified Purchase Analysis'",
            "SupplementVPStatus → Unlock「PurchaseVerifyAnalyze」"
        ),
        "reviewer_info": (
            "Add reviewer info → Unlock 'Account Profile Analysis'",
            "SupplementReviewpersonInformation → Unlock「Account profileAnalyze」"
        ),
    }
    
    for field in missing:
        if field in hint_map:
            hints_en.append(hint_map[field][0])
            hints_zh.append(hint_map[field][1])
    
    return hints_en, hints_zh


def analyze_reviews(reviews: List[Review], asin: str = "UNKNOWN") -> AnalysisResult:
    """MainAnalyzeFunction"""
    if not reviews:
        return AnalysisResult(
            asin=asin,
            total_reviews=0,
            analysis_level=AnalysisLevel.L1_BASIC,
            authenticity_score=50,
            risk_level=RiskLevel.MEDIUM,
            dimensions=[],
            suspicious_reviews=[],
            available_fields=[],
            missing_fields=["content"],
            deepening_hints=["Please provide review data"],
            deepening_hints_zh=["Please provideReview Countdata"],
            summary="No reviews to analyze",
            summary_zh="noReview Countdata"
        )
    
    # ConfirmAnalyzelayerLevel
    level, available, missing = determine_analysis_level(reviews)
    hints_en, hints_zh = generate_deepening_hints(missing)
    
    # ExecuteDetection
    dimensions = []
    
    # L1: BasicDetection (AlwaysExecute)
    dimensions.append(detect_content_similarity(reviews))
    dimensions.append(detect_review_length(reviews))
    dimensions.append(detect_keywords(reviews))
    
    # L2+: TimeDetection
    time_result = detect_time_clustering(reviews)
    if time_result:
        dimensions.append(time_result)
    
    # L3+: RatingDetection
    rating_result = detect_rating_distribution(reviews)
    if rating_result:
        dimensions.append(rating_result)
    
    # L4: VPDetection
    vp_result = detect_vp_ratio(reviews)
    if vp_result:
        dimensions.append(vp_result)
    
    # CalculateComprehensiveScore (WeightedAverageSuspiciousDegree，ThenConvert toAuthenticityScore)
    total_weight = sum(d.weight for d in dimensions)
    if total_weight > 0:
        suspicion_score = sum(d.score * d.weight for d in dimensions) / total_weight
    else:
        suspicion_score = 50
    
    authenticity_score = max(0, min(100, 100 - suspicion_score))
    
    # ConfirmRiskGrade
    if authenticity_score >= 70:
        risk_level = RiskLevel.LOW
    elif authenticity_score >= 50:
        risk_level = RiskLevel.MEDIUM
    elif authenticity_score >= 30:
        risk_level = RiskLevel.HIGH
    else:
        risk_level = RiskLevel.CRITICAL
    
    # IdentifySuspiciousReview
    suspicious = identify_suspicious_reviews(reviews, dimensions)
    
    # GenerateSummary
    risk_text = {
        RiskLevel.LOW: ("Low risk - Reviews appear authentic", "Low Risk - ReviewLooks likeReal"),
        RiskLevel.MEDIUM: ("Medium risk - Some concerns detected", " in  etcRisk - FoundSomeConcern"),
        RiskLevel.HIGH: ("High risk - Multiple red flags", "High Risk -  many DangerSignal"),
        RiskLevel.CRITICAL: ("Critical risk - Likely fake reviews", "CriticalRisk - MayExistLarge amountFakeReview"),
    }
    
    summary_en = f"{risk_text[risk_level][0]}. Analyzed {len(reviews)} reviews at {level.value} level."
    summary_zh = f"{risk_text[risk_level][1]}。Analyze  {len(reviews)} itemReview，AnalyzelayerLevel {level.value}。"
    
    return AnalysisResult(
        asin=asin,
        total_reviews=len(reviews),
        analysis_level=level,
        authenticity_score=round(authenticity_score),
        risk_level=risk_level,
        dimensions=dimensions,
        suspicious_reviews=suspicious,
        available_fields=available,
        missing_fields=missing,
        deepening_hints=hints_en,
        deepening_hints_zh=hints_zh,
        summary=summary_en,
        summary_zh=summary_zh
    )


# ============================================================
# OutputFormat
# ============================================================

def format_report(result: AnalysisResult, lang: str = "en") -> str:
    """FormatReport"""
    risk_icons = {
        RiskLevel.LOW: "✅",
        RiskLevel.MEDIUM: "⚠️",
        RiskLevel.HIGH: "🔴",
        RiskLevel.CRITICAL: "💀",
    }
    
    if lang == "zh":
        lines = [
            f"📊 **ReviewAuthenticityAnalyzeReport**",
            f"",
            f"**ASIN**: {result.asin}",
            f"**Review Count**: {result.total_reviews}",
            f"**AnalyzelayerLevel**: {result.analysis_level.value}",
            f"",
            f"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            f"",
            f"## AuthenticityRating: {result.authenticity_score}/100 {risk_icons[result.risk_level]}",
            f"",
            f"{result.summary_zh}",
            f"",
            f"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            f"",
            f"## DetectiondimensionDegree",
            f"",
        ]
        
        for d in result.dimensions:
            lines.append(f"{d.status} **{d.name_zh}**: {d.score:.0f}/100")
            lines.append(f"   {d.detail_zh}")
            lines.append("")
        
        if result.suspicious_reviews:
            lines.append("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
            lines.append("")
            lines.append(f"## High RiskReview (Top {len(result.suspicious_reviews)})")
            lines.append("")
            for i, sr in enumerate(result.suspicious_reviews[:5], 1):
                lines.append(f"**{i}. Risk {sr.risk_score:.0f}%**")
                lines.append(f'   "{sr.content}"')
                lines.append(f"   Reason: {', '.join(sr.reasons_zh)}")
                lines.append("")
        
        if result.deepening_hints_zh:
            lines.append("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
            lines.append("")
            lines.append("🔍 **Want more accurateAnalyze？Supplement with following info:**")
            lines.append("")
            for hint in result.deepening_hints_zh:
                lines.append(f"• {hint}")
    else:
        lines = [
            f"📊 **Review Authenticity Report**",
            f"",
            f"**ASIN**: {result.asin}",
            f"**Reviews**: {result.total_reviews}",
            f"**Analysis Level**: {result.analysis_level.value}",
            f"",
            f"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            f"",
            f"## Authenticity Score: {result.authenticity_score}/100 {risk_icons[result.risk_level]}",
            f"",
            f"{result.summary}",
            f"",
            f"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            f"",
            f"## Detection Dimensions",
            f"",
        ]
        
        for d in result.dimensions:
            lines.append(f"{d.status} **{d.name}**: {d.score:.0f}/100")
            lines.append(f"   {d.detail}")
            lines.append("")
        
        if result.suspicious_reviews:
            lines.append("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
            lines.append("")
            lines.append(f"## Suspicious Reviews (Top {len(result.suspicious_reviews)})")
            lines.append("")
            for i, sr in enumerate(result.suspicious_reviews[:5], 1):
                lines.append(f"**{i}. Risk {sr.risk_score:.0f}%**")
                lines.append(f'   "{sr.content}"')
                lines.append(f"   Reasons: {', '.join(sr.reasons)}")
                lines.append("")
        
        if result.deepening_hints:
            lines.append("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
            lines.append("")
            lines.append("🔍 **Want more accurate analysis? Add the following:**")
            lines.append("")
            for hint in result.deepening_hints:
                lines.append(f"• {hint}")
    
    return "\n".join(lines)


# ============================================================
# Parse
# ============================================================

def parse_simple_reviews(text: str) -> List[Review]:
    """ParseSimpleTextFormatReview"""
    reviews = []
    
    # TrySplit by paragraph
    paragraphs = re.split(r'\n\n+', text.strip())
    
    for para in paragraphs:
        para = para.strip()
        if len(para) > 10:
            review = Review(content=para)
            
            # TryExtract starLevel
            star_match = re.search(r'(\d)\s*(?:star|★|⭐)', para, re.I)
            if star_match:
                review.rating = int(star_match.group(1))
            
            # TryExtractDayPeriod
            date_match = re.search(r'(\d{4}-\d{2}-\d{2}|\w+\s+\d{1,2},?\s+\d{4})', para)
            if date_match:
                review.date = date_match.group(1)
            
            # TryExtract VP
            if 'verified purchase' in para.lower() or 'VP' in para:
                review.verified_purchase = True
            elif 'not verified' in para.lower():
                review.verified_purchase = False
            
            reviews.append(review)
    
    return reviews


# ============================================================
# CLI Entry Point
# ============================================================

def main():
    """CLI Entry Point"""
    # TestData
    test_reviews = [
        Review(content="Great product! Works perfectly. Highly recommend to everyone.", rating=5, verified_purchase=True, date="2024-01-15"),
        Review(content="Amazing! Best purchase ever. Love it!", rating=5, verified_purchase=False, date="2024-01-15"),
        Review(content="Great product! Works perfectly. Must buy!", rating=5, verified_purchase=False, date="2024-01-16"),
        Review(content="Received free product in exchange for honest review. It's good.", rating=5, verified_purchase=False, date="2024-01-16"),
        Review(content="Excellent quality, fast shipping. Very satisfied with purchase.", rating=5, verified_purchase=True, date="2024-01-20"),
        Review(content="Not as described. Cheap quality.", rating=1, verified_purchase=True, date="2024-02-01"),
        Review(content="Perfect!", rating=5, verified_purchase=False, date="2024-01-16"),
        Review(content="Good value for money. Does what it says.", rating=4, verified_purchase=True, date="2024-02-15"),
        Review(content="Five stars! Amazing product!", rating=5, verified_purchase=False, date="2024-01-17"),
        Review(content="Decent product for the price.", rating=3, verified_purchase=True, date="2024-03-01"),
    ]
    
    # If command lineInput
    if len(sys.argv) > 1:
        arg = sys.argv[1]
        if arg == "--demo":
            pass  # UseTestData
        elif arg.startswith('['):
            # JSON group
            try:
                data = json.loads(arg)
                test_reviews = [Review(**r) for r in data]
            except:
                pass
        else:
            # pureText
            test_reviews = parse_simple_reviews(arg)
    
    result = analyze_reviews(test_reviews, asin="B08XXXXX")
    
    # Default ChineseOutput
    lang = "zh" if "--zh" in sys.argv else "en"
    print(format_report(result, lang))


if __name__ == "__main__":
    main()

FILE:scripts/parser.py
#!/usr/bin/env python3
"""
Review Parser - Multi-format Input Parser
ReviewParse -  many FormatInputParse

SupportFormat:
- pureText (Paragraph separator)
- JSON
- CSV
- TSV
- Markdown Table

Version: 1.0.0
"""

import json
import csv
import re
from typing import List, Optional
from dataclasses import dataclass
from io import StringIO


@dataclass
class Review:
    """Single itemReview"""
    content: str
    rating: Optional[int] = None
    date: Optional[str] = None
    reviewer_name: Optional[str] = None
    verified_purchase: Optional[bool] = None
    helpful_votes: Optional[int] = None
    reviewer_reviews_count: Optional[int] = None


class ReviewParser:
    """ many FormatReviewParse"""
    
    @staticmethod
    def detect_format(text: str) -> str:
        """DetectionInputFormat"""
        text = text.strip()
        
        # JSON group
        if text.startswith('[') and text.endswith(']'):
            try:
                json.loads(text)
                return 'json'
            except:
                pass
        
        # JSON Object
        if text.startswith('{'):
            try:
                json.loads(text)
                return 'json_single'
            except:
                pass
        
        # CSV (CheckComma separated with header)
        lines = text.split('\n')
        if len(lines) > 1:
            first_line = lines[0].lower()
            if ',' in first_line and any(h in first_line for h in ['content', 'review', 'rating', 'date', 'text']):
                return 'csv'
        
        # TSV
        if len(lines) > 1 and '\t' in lines[0]:
            return 'tsv'
        
        # Markdown Table
        if '|' in text and '---' in text:
            return 'markdown'
        
        # DefaultpureText
        return 'text'
    
    @staticmethod
    def parse(text: str) -> List[Review]:
        """ParseReview"""
        format_type = ReviewParser.detect_format(text)
        
        parsers = {
            'json': ReviewParser.parse_json,
            'json_single': ReviewParser.parse_json_single,
            'csv': ReviewParser.parse_csv,
            'tsv': ReviewParser.parse_tsv,
            'markdown': ReviewParser.parse_markdown,
            'text': ReviewParser.parse_text,
        }
        
        parser = parsers.get(format_type, ReviewParser.parse_text)
        return parser(text)
    
    @staticmethod
    def parse_json(text: str) -> List[Review]:
        """Parse JSON group"""
        try:
            data = json.loads(text)
            reviews = []
            for item in data:
                review = Review(
                    content=item.get('content', item.get('text', item.get('review', ''))),
                    rating=item.get('rating', item.get('stars', item.get('star'))),
                    date=item.get('date', item.get('review_date')),
                    reviewer_name=item.get('reviewer_name', item.get('author', item.get('name'))),
                    verified_purchase=item.get('verified_purchase', item.get('vp', item.get('verified'))),
                    helpful_votes=item.get('helpful_votes', item.get('helpful')),
                )
                if review.content:
                    reviews.append(review)
            return reviews
        except:
            return []
    
    @staticmethod
    def parse_json_single(text: str) -> List[Review]:
        """ParseSingle JSON Object"""
        try:
            item = json.loads(text)
            review = Review(
                content=item.get('content', item.get('text', item.get('review', ''))),
                rating=item.get('rating', item.get('stars')),
                date=item.get('date'),
                reviewer_name=item.get('reviewer_name', item.get('author')),
                verified_purchase=item.get('verified_purchase', item.get('vp')),
            )
            return [review] if review.content else []
        except:
            return []
    
    @staticmethod
    def parse_csv(text: str) -> List[Review]:
        """Parse CSV"""
        reviews = []
        try:
            reader = csv.DictReader(StringIO(text))
            for row in reader:
                # TryMultipleField name
                content = (
                    row.get('content') or row.get('Content') or
                    row.get('review') or row.get('Review') or
                    row.get('text') or row.get('Text') or
                    row.get('review_text') or row.get('body') or ''
                )
                
                rating_str = (
                    row.get('rating') or row.get('Rating') or
                    row.get('stars') or row.get('Stars') or
                    row.get('star') or ''
                )
                rating = None
                if rating_str:
                    try:
                        rating = int(float(rating_str))
                    except:
                        pass
                
                date = (
                    row.get('date') or row.get('Date') or
                    row.get('review_date') or row.get('created_at') or None
                )
                
                vp_str = (
                    row.get('verified_purchase') or row.get('vp') or
                    row.get('verified') or row.get('VP') or ''
                )
                vp = None
                if vp_str:
                    vp = vp_str.lower() in ['true', 'yes', '1', 'y', 'verified']
                
                reviewer = (
                    row.get('reviewer_name') or row.get('author') or
                    row.get('name') or row.get('reviewer') or None
                )
                
                if content:
                    reviews.append(Review(
                        content=content,
                        rating=rating,
                        date=date,
                        reviewer_name=reviewer,
                        verified_purchase=vp,
                    ))
        except Exception as e:
            print(f"CSV parse error: {e}")
        
        return reviews
    
    @staticmethod
    def parse_tsv(text: str) -> List[Review]:
        """Parse TSV"""
        # Convert to CSV FormatProcess
        csv_text = text.replace('\t', ',')
        return ReviewParser.parse_csv(csv_text)
    
    @staticmethod
    def parse_markdown(text: str) -> List[Review]:
        """Parse Markdown Table"""
        reviews = []
        lines = text.strip().split('\n')
        
        # find to Tablehead
        header_line = None
        data_start = 0
        for i, line in enumerate(lines):
            if '|' in line and '---' not in line:
                header_line = line
                data_start = i + 2  # Skip separator lines
                break
        
        if not header_line:
            return []
        
        # ParseTablehead
        headers = [h.strip().lower() for h in header_line.split('|') if h.strip()]
        
        # ParseDatarow
        for line in lines[data_start:]:
            if '|' not in line:
                continue
            
            cells = [c.strip() for c in line.split('|') if c.strip()]
            if len(cells) < len(headers):
                continue
            
            row = dict(zip(headers, cells))
            
            content = row.get('content', row.get('review', row.get('text', '')))
            rating = None
            rating_str = row.get('rating', row.get('stars', ''))
            if rating_str:
                try:
                    rating = int(float(rating_str.replace('★', '').strip()))
                except:
                    pass
            
            if content:
                reviews.append(Review(
                    content=content,
                    rating=rating,
                    date=row.get('date'),
                    reviewer_name=row.get('author', row.get('reviewer')),
                ))
        
        return reviews
    
    @staticmethod
    def parse_text(text: str) -> List[Review]:
        """ParsepureText"""
        reviews = []
        
        # TrySplit by paragraph
        paragraphs = re.split(r'\n\n+', text.strip())
        
        for para in paragraphs:
            para = para.strip()
            if len(para) < 10:
                continue
            
            review = Review(content=para)
            
            # TryExtract starLevel
            star_patterns = [
                r'(\d)\s*(?:star|stars|★|⭐)',
                r'(?:star|stars|rating)[:\s]*(\d)',
                r'^(\d)★',
                r'^(\d)\s*star',
            ]
            for pattern in star_patterns:
                match = re.search(pattern, para, re.I)
                if match:
                    review.rating = int(match.group(1))
                    break
            
            # TryExtractDayPeriod
            date_patterns = [
                r'(\d{4}-\d{2}-\d{2})',
                r'(\w+\s+\d{1,2},?\s+\d{4})',
                r'(\d{1,2}/\d{1,2}/\d{4})',
            ]
            for pattern in date_patterns:
                match = re.search(pattern, para)
                if match:
                    review.date = match.group(1)
                    break
            
            # TryExtract VP Status
            if re.search(r'verified\s*purchase', para, re.I):
                review.verified_purchase = True
            elif re.search(r'not\s*verified', para, re.I):
                review.verified_purchase = False
            
            reviews.append(review)
        
        return reviews


def parse_reviews(text: str) -> List[Review]:
    """ConvenientFunction"""
    return ReviewParser.parse(text)


# CLI
if __name__ == "__main__":
    import sys
    
    if len(sys.argv) > 1:
        text = sys.argv[1]
    else:
        # TestData
        text = """
content,rating,date,verified_purchase
"Great product!",5,2024-01-15,true
"Not good",2,2024-01-16,false
"Amazing!",5,2024-01-17,true
"""
    
    reviews = parse_reviews(text)
    print(f"Parsed {len(reviews)} reviews:")
    for r in reviews:
        print(f"  - {r.rating}★ | VP:{r.verified_purchase} | {r.content[:50]}...")

FILE:scripts/report_html.py
#!/usr/bin/env python3
"""
Review Analysis HTML Report Generator
ReviewAnalyze HTML ReportGenerate

Features:
- CanViewTable (Chart.js)
- Responsive layout
-  deep colorMaintopic
- InteractiveDataDisplay

Version: 1.0.0
"""

import json
from typing import List, Dict, Any
from datetime import datetime


def generate_html_report(
    asin: str,
    authenticity_score: int,
    risk_level: str,
    dimensions: List[Dict[str, Any]],
    suspicious_reviews: List[Dict[str, Any]],
    total_reviews: int,
    analysis_level: str,
    summary: str,
    output_path: str = "review_analysis_report.html"
) -> str:
    """Generate HTML Report"""
    
    # RiskGradeColor
    risk_colors = {
        "low": "#10b981",      # Green
        "medium": "#f59e0b",   # Yellow
        "high": "#ef4444",     # Red
        "critical": "#7c2d12", #  deep red
    }
    
    risk_color = risk_colors.get(risk_level.lower(), "#6b7280")
    
    # dimensionDegreeData (use at chartTable)
    dimension_labels = json.dumps([d.get('name', d.get('name_zh', '')) for d in dimensions])
    dimension_scores = json.dumps([d.get('score', 0) for d in dimensions])
    
    # SuspiciousReview JSON
    suspicious_json = json.dumps(suspicious_reviews[:10], ensure_ascii=False, default=str)
    
    html = f"""<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Review Analysis Report - {asin}</title>
    <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
    <style>
        * {{
            margin: 0;
            padding: 0;
            box-sizing: border-box;
        }}
        
        body {{
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
            background: linear-gradient(135deg, #1a1a2e 0%, #16213e 100%);
            color: #e4e4e7;
            min-height: 100vh;
            padding: 20px;
        }}
        
        .container {{
            max-width: 1200px;
            margin: 0 auto;
        }}
        
        .header {{
            text-align: center;
            padding: 40px 20px;
            background: rgba(255,255,255,0.05);
            border-radius: 16px;
            margin-bottom: 30px;
        }}
        
        .header h1 {{
            font-size: 2rem;
            background: linear-gradient(90deg, #a78bfa, #818cf8);
            -webkit-background-clip: text;
            -webkit-text-fill-color: transparent;
            margin-bottom: 10px;
        }}
        
        .header .asin {{
            color: #a1a1aa;
            font-size: 1.1rem;
        }}
        
        .score-card {{
            background: rgba(255,255,255,0.08);
            border-radius: 16px;
            padding: 40px;
            text-align: center;
            margin-bottom: 30px;
            border: 1px solid rgba(255,255,255,0.1);
        }}
        
        .score-number {{
            font-size: 5rem;
            font-weight: bold;
            color: {risk_color};
            line-height: 1;
        }}
        
        .score-label {{
            font-size: 1.2rem;
            color: #a1a1aa;
            margin-top: 10px;
        }}
        
        .risk-badge {{
            display: inline-block;
            padding: 8px 20px;
            border-radius: 20px;
            background: {risk_color};
            color: white;
            font-weight: 600;
            margin-top: 15px;
            text-transform: uppercase;
        }}
        
        .grid {{
            display: grid;
            grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
            gap: 20px;
            margin-bottom: 30px;
        }}
        
        .card {{
            background: rgba(255,255,255,0.08);
            border-radius: 12px;
            padding: 24px;
            border: 1px solid rgba(255,255,255,0.1);
        }}
        
        .card h3 {{
            font-size: 1.1rem;
            margin-bottom: 20px;
            color: #a78bfa;
        }}
        
        .stat {{
            display: flex;
            justify-content: space-between;
            padding: 12px 0;
            border-bottom: 1px solid rgba(255,255,255,0.1);
        }}
        
        .stat:last-child {{
            border-bottom: none;
        }}
        
        .stat-label {{
            color: #a1a1aa;
        }}
        
        .stat-value {{
            font-weight: 600;
        }}
        
        .chart-container {{
            position: relative;
            height: 300px;
            width: 100%;
        }}
        
        .dimension-item {{
            display: flex;
            align-items: center;
            padding: 12px 0;
            border-bottom: 1px solid rgba(255,255,255,0.1);
        }}
        
        .dimension-icon {{
            width: 30px;
            font-size: 1.2rem;
        }}
        
        .dimension-name {{
            flex: 1;
        }}
        
        .dimension-score {{
            font-weight: 600;
            width: 80px;
            text-align: right;
        }}
        
        .suspicious-item {{
            background: rgba(239, 68, 68, 0.1);
            border: 1px solid rgba(239, 68, 68, 0.3);
            border-radius: 8px;
            padding: 16px;
            margin-bottom: 12px;
        }}
        
        .suspicious-header {{
            display: flex;
            justify-content: space-between;
            margin-bottom: 8px;
        }}
        
        .suspicious-risk {{
            color: #ef4444;
            font-weight: 600;
        }}
        
        .suspicious-content {{
            color: #d4d4d8;
            font-style: italic;
            margin-bottom: 8px;
        }}
        
        .suspicious-reasons {{
            color: #a1a1aa;
            font-size: 0.9rem;
        }}
        
        .summary {{
            background: rgba(167, 139, 250, 0.1);
            border: 1px solid rgba(167, 139, 250, 0.3);
            border-radius: 12px;
            padding: 20px;
            margin-bottom: 30px;
        }}
        
        .footer {{
            text-align: center;
            padding: 20px;
            color: #71717a;
            font-size: 0.9rem;
        }}
        
        @media (max-width: 768px) {{
            .score-number {{
                font-size: 3rem;
            }}
            .grid {{
                grid-template-columns: 1fr;
            }}
        }}
    </style>
</head>
<body>
    <div class="container">
        <div class="header">
            <h1>📊 Review Authenticity Analysis</h1>
            <div class="asin">ASIN: {asin}</div>
        </div>
        
        <div class="score-card">
            <div class="score-number">{authenticity_score}</div>
            <div class="score-label">Authenticity Score (0-100)</div>
            <div class="risk-badge">{risk_level.upper()} RISK</div>
        </div>
        
        <div class="summary">
            <strong>Summary:</strong> {summary}
        </div>
        
        <div class="grid">
            <div class="card">
                <h3>📈 Overview</h3>
                <div class="stat">
                    <span class="stat-label">Total Reviews</span>
                    <span class="stat-value">{total_reviews}</span>
                </div>
                <div class="stat">
                    <span class="stat-label">Analysis Level</span>
                    <span class="stat-value">{analysis_level}</span>
                </div>
                <div class="stat">
                    <span class="stat-label">Suspicious Reviews</span>
                    <span class="stat-value">{len(suspicious_reviews)}</span>
                </div>
                <div class="stat">
                    <span class="stat-label">Generated</span>
                    <span class="stat-value">{datetime.now().strftime('%Y-%m-%d %H:%M')}</span>
                </div>
            </div>
            
            <div class="card">
                <h3>🎯 Detection Dimensions</h3>
                <div class="chart-container">
                    <canvas id="dimensionChart"></canvas>
                </div>
            </div>
        </div>
        
        <div class="card" style="margin-bottom: 30px;">
            <h3>🔍 Dimension Details</h3>
            {"".join([f'''
            <div class="dimension-item">
                <div class="dimension-icon">{d.get('status', '❓')}</div>
                <div class="dimension-name">{d.get('name', d.get('name_zh', ''))}</div>
                <div class="dimension-score" style="color: {'#10b981' if d.get('score', 0) < 30 else '#f59e0b' if d.get('score', 0) < 60 else '#ef4444'}">{d.get('score', 0):.0f}/100</div>
            </div>
            <div style="color: #a1a1aa; font-size: 0.9rem; padding-left: 30px; padding-bottom: 12px;">{d.get('detail', d.get('detail_zh', ''))}</div>
            ''' for d in dimensions])}
        </div>
        
        <div class="card">
            <h3>⚠️ Suspicious Reviews (Top {min(len(suspicious_reviews), 5)})</h3>
            <div id="suspiciousReviews"></div>
        </div>
        
        <div class="footer">
            <p>Generated by Amazon Review Checker | Nexscope AI</p>
            <p>This analysis is for reference only. Results may not be 100% accurate.</p>
        </div>
    </div>
    
    <script>
        // dimensionDegreeRadar chart
        const ctx = document.getElementById('dimensionChart').getContext('2d');
        new Chart(ctx, {{
            type: 'radar',
            data: {{
                labels: {dimension_labels},
                datasets: [{{
                    label: 'Suspicion Score',
                    data: {dimension_scores},
                    backgroundColor: 'rgba(167, 139, 250, 0.2)',
                    borderColor: 'rgba(167, 139, 250, 1)',
                    borderWidth: 2,
                    pointBackgroundColor: 'rgba(167, 139, 250, 1)',
                }}]
            }},
            options: {{
                responsive: true,
                maintainAspectRatio: false,
                scales: {{
                    r: {{
                        beginAtZero: true,
                        max: 100,
                        ticks: {{
                            color: '#a1a1aa',
                            backdropColor: 'transparent'
                        }},
                        grid: {{
                            color: 'rgba(255,255,255,0.1)'
                        }},
                        pointLabels: {{
                            color: '#e4e4e7',
                            font: {{ size: 11 }}
                        }}
                    }}
                }},
                plugins: {{
                    legend: {{
                        display: false
                    }}
                }}
            }}
        }});
        
        // SuspiciousReview
        const suspicious = {suspicious_json};
        const container = document.getElementById('suspiciousReviews');
        
        if (suspicious.length === 0) {{
            container.innerHTML = '<p style="color: #10b981;">No highly suspicious reviews detected.</p>';
        }} else {{
            suspicious.slice(0, 5).forEach((review, index) => {{
                container.innerHTML += `
                    <div class="suspicious-item">
                        <div class="suspicious-header">
                            <span>#{index + 1}</span>
                            <span class="suspicious-risk">Risk: {review.risk_score?.toFixed(0) || 'N/A'}%</span>
                        </div>
                        <div class="suspicious-content">"{review.content}"</div>
                        <div class="suspicious-reasons">Reasons: {(review.reasons || review.reasons_zh || []).join(', ')}</div>
                    </div>
                `;
            }});
        }}
    </script>
</body>
</html>
"""
    
    # SaveFile
    with open(output_path, 'w', encoding='utf-8') as f:
        f.write(html)
    
    print(f"✅ HTML report saved to: {output_path}")
    return output_path


# CLI
if __name__ == "__main__":
    # TestData
    generate_html_report(
        asin="B08XXXXX",
        authenticity_score=66,
        risk_level="medium",
        dimensions=[
            {"name": "Content Similarity", "name_zh": "Similar contentDegree", "score": 24, "status": "✅", "detail": "Found 0 similar review pairs"},
            {"name": "Time Clustering", "name_zh": "TimeAggregate", "score": 70, "status": "🔴", "detail": "6 reviews in 48h window"},
            {"name": "Rating Distribution", "name_zh": "Rating Distribution", "score": 0, "status": "✅", "detail": "Normal distribution"},
            {"name": "VP Ratio", "name_zh": "VPRatio", "score": 30, "status": "⚠️", "detail": "50% verified purchase"},
            {"name": "Review Length", "name_zh": "ReviewDegree", "score": 0, "status": "✅", "detail": "Normal length distribution"},
            {"name": "Suspicious Keywords", "name_zh": "SuspiciousKeywords", "score": 80, "status": "🔴", "detail": "4 reviews contain suspicious keywords"},
        ],
        suspicious_reviews=[
            {"content": "Perfect!", "risk_score": 75, "reasons": ["Very short", "Not VP", "Generic template"]},
            {"content": "Five stars! Amazing product!", "risk_score": 75, "reasons": ["Very short", "Not VP", "Generic template"]},
            {"content": "Received free product in exchange for honest review...", "risk_score": 60, "reasons": ["Not VP", "Incentivized review"]},
        ],
        total_reviews=10,
        analysis_level="L4",
        summary="Medium risk - Some concerns detected. Analyzed 10 reviews at L4 level.",
        output_path="review_analysis_report.html"
    )

Amazon Review Checker

Skill

Amazon review authenticity analyzer. Detect fake reviews, suspicious patterns, and rating manipulation. Includes time clustering detection, content similarit...

---
name: amazon-review-checker
version: 1.0.0
description: "Amazon review authenticity analyzer. Detect fake reviews, suspicious patterns, and rating manipulation. Includes time clustering detection, content similarity analysis, rating distribution checks, and verified purchase validation. Progressive analysis with L1-L4 depth levels. No API key required."
metadata: {"nexscope":{"emoji":"🔍","category":"ecommerce"}}
---

# Amazon Review Checker 🔍

Review authenticity analyzer — detect fake reviews, suspicious patterns, and rating manipulation.

## Installation

```bash
npx skills add nexscope-ai/eCommerce-Skills --skill amazon-review-checker -g
```

## Features

- **Authenticity Score** — 0-100 comprehensive rating
- **Suspicious Pattern Detection** — Time clustering, content similarity, rating anomalies
- **Fake Review Flagging** — Mark high-risk reviews with explanations
- **Progressive Analysis** — More data = deeper insights

## Progressive Analysis Levels

| Level | Required Data | Unlocked Analysis |
|-------|---------------|-------------------|
| **L1 Basic** | Review content | Similarity, length, keywords |
| **L2 Advanced** | + Review date | Time clustering detection |
| **L3 Deep** | + Star rating | Rating distribution analysis |
| **L4 Complete** | + VP status | Verified purchase validation |

## Detection Dimensions

| Dimension | Weight | Method |
|-----------|--------|--------|
| Time Clustering | 25% | Sliding window + burst detection |
| Content Similarity | 20% | N-gram + Jaccard similarity |
| Rating Distribution | 20% | Chi-square test vs natural distribution |
| VP Ratio | 15% | Compare to category benchmark |
| Review Length | 5% | Entropy analysis |
| Suspicious Keywords | 5% | Keyword pattern matching |

## Risk Levels

| Score | Level | Description |
|-------|-------|-------------|
| 70-100 | ✅ Low Risk | Reviews appear authentic |
| 50-69 | ⚠️ Medium Risk | Some concerns found |
| 30-49 | 🔴 High Risk | Multiple red flags |
| 0-29 | 💀 Critical | Likely mass fake reviews |

## Usage

### Method 1: Paste Reviews

Paste reviews directly in conversation:

```
Check these reviews:

5 stars - Great product! Works perfectly.
5 stars - Amazing! Best purchase ever.
1 star - Not as described.
```

### Method 2: JSON Input

```bash
python3 scripts/analyzer.py '[
  {"content": "Great product!", "rating": 5, "date": "2024-01-15", "verified_purchase": true},
  {"content": "Amazing!", "rating": 5, "date": "2024-01-15", "verified_purchase": false}
]'
```

### Method 3: Demo Mode

```bash
python3 scripts/analyzer.py --demo
```

## Output Example

```
📊 Review Authenticity Report

ASIN: B08XXXXX
Reviews: 10
Analysis Level: L4

━━━━━━━━━━━━━━━━━━━━━━━━

Authenticity Score: 66/100 ⚠️

Medium Risk - Some concerns found.

━━━━━━━━━━━━━━━━━━━━━━━━

Detection Dimensions

🔴 Time Clustering: 70/100
   Max 6 reviews within 48h

✅ Content Similarity: 24/100
   Found 0 highly similar review groups

━━━━━━━━━━━━━━━━━━━━━━━━

High-Risk Reviews (Top 3)

1. Risk 75% - "Perfect!"
   Reason: Too short, non-VP, templated 5-star

🔍 Want more accurate analysis? Add:
• Reviewer info → Unlock "Account Profile Analysis"
```

## Interaction Flow

```
User Input (any format)
        ↓
Smart field detection
        ↓
Analyze with available data
        ↓
Results + depth suggestions
        ↓
User continues or ends
```

---

**Part of [Nexscope AI](https://www.nexscope.ai/) — AI tools for e-commerce sellers.**

FILE:scripts/analyzer.py
#!/usr/bin/env python3
"""
Amazon Review Checker - Core Analyzer
AmazonReviewAuthenticityDetection - CoreAnalyzeEngine

Features:
- ProgressiveAnalyze ( has  many  few Data，Give conclusion)
-  many dimensionDegreeDetection (Time/Content/Rating/Account/VP)
- Friendly guidance (HintCanDeepenDirection)

Version: 1.0.0
"""

import json
import re
import math
from dataclasses import dataclass, field
from typing import List, Dict, Optional, Tuple
from datetime import datetime, timedelta
from collections import Counter
from enum import Enum
import sys


class RiskLevel(Enum):
    LOW = "low"           # 0-30
    MEDIUM = "medium"     # 31-60
    HIGH = "high"         # 61-80
    CRITICAL = "critical" # 81-100


class AnalysisLevel(Enum):
    L1_BASIC = "L1"      # onlyContent
    L2_TIMED = "L2"      # + Time
    L3_SCORED = "L3"     # + Rating
    L4_FULL = "L4"       #  all Field


# ============================================================
# Data Structures
# ============================================================

@dataclass
class Review:
    """Single itemReview"""
    content: str
    rating: Optional[int] = None          # 1-5 star
    date: Optional[str] = None            # DayPeriod
    reviewer_name: Optional[str] = None   # Reviewperson
    verified_purchase: Optional[bool] = None  # VP
    helpful_votes: Optional[int] = None   #  has Help
    reviewer_reviews_count: Optional[int] = None  # ReviewTotalReview Count
    
    @property
    def has_rating(self) -> bool:
        return self.rating is not None
    
    @property
    def has_date(self) -> bool:
        return self.date is not None
    
    @property
    def has_vp(self) -> bool:
        return self.verified_purchase is not None


@dataclass
class DimensionResult:
    """Single dimensionDegreeDetectionResult"""
    name: str
    name_zh: str
    score: float          # 0-100, exceedHighexceedSuspicious
    status: str           # ✅ ⚠️ 🔴
    detail: str
    detail_zh: str
    weight: float = 0.0


@dataclass
class SuspiciousReview:
    """SuspiciousReview"""
    content: str
    risk_score: float
    reasons: List[str]
    reasons_zh: List[str]


@dataclass
class AnalysisResult:
    """AnalyzeResult"""
    asin: str
    total_reviews: int
    analysis_level: AnalysisLevel
    authenticity_score: int       # 0-100, exceedHighexceedReal
    risk_level: RiskLevel
    dimensions: List[DimensionResult]
    suspicious_reviews: List[SuspiciousReview]
    available_fields: List[str]
    missing_fields: List[str]
    deepening_hints: List[str]
    deepening_hints_zh: List[str]
    summary: str
    summary_zh: str


# ============================================================
# DetectionAlgorithm
# ============================================================

def detect_content_similarity(reviews: List[Review]) -> DimensionResult:
    """DetectionSimilar contentDegree"""
    if len(reviews) < 2:
        return DimensionResult(
            name="Content Similarity",
            name_zh="Similar contentDegree",
            score=0,
            status="✅",
            detail="Not enough reviews to compare",
            detail_zh="Review CountInsufficient，CannotComparison",
            weight=0.20
        )
    
    # Simple similarityDegreeDetection：CheckRepeated phrases
    contents = [r.content.lower() for r in reviews]
    
    # Extract3-gram
    def get_ngrams(text, n=3):
        words = re.findall(r'\w+', text)
        return [' '.join(words[i:i+n]) for i in range(len(words)-n+1)]
    
    all_ngrams = []
    for content in contents:
        all_ngrams.extend(get_ngrams(content))
    
    # Statistics heavy complex
    ngram_counts = Counter(all_ngrams)
    repeated = sum(1 for count in ngram_counts.values() if count > 1)
    total = len(ngram_counts) if ngram_counts else 1
    
    similarity_ratio = repeated / total if total > 0 else 0
    score = min(100, similarity_ratio * 500)  # put big 
    
    # CheckHighDegreeSimilarReview for 
    similar_pairs = 0
    for i, c1 in enumerate(contents):
        for c2 in contents[i+1:]:
            if len(c1) > 20 and len(c2) > 20:
                # Simple Jaccard SimilarDegree
                set1, set2 = set(c1.split()), set(c2.split())
                if set1 and set2:
                    jaccard = len(set1 & set2) / len(set1 | set2)
                    if jaccard > 0.5:
                        similar_pairs += 1
    
    if similar_pairs > 0:
        score = max(score, 50 + similar_pairs * 10)
    
    score = min(100, score)
    
    if score < 30:
        status = "✅"
    elif score < 60:
        status = "⚠️"
    else:
        status = "🔴"
    
    return DimensionResult(
        name="Content Similarity",
        name_zh="Similar contentDegree",
        score=round(score, 1),
        status=status,
        detail=f"Found {similar_pairs} similar review pairs",
        detail_zh=f"Found {similar_pairs} groupHighDegreeSimilarReview",
        weight=0.20
    )


def detect_time_clustering(reviews: List[Review]) -> Optional[DimensionResult]:
    """DetectionTimeAggregate"""
    dated_reviews = [r for r in reviews if r.has_date]
    
    if len(dated_reviews) < 5:
        return None  # DataInsufficient
    
    # ParseDayPeriod
    dates = []
    for r in dated_reviews:
        try:
            # TryMultipleFormat
            for fmt in ['%Y-%m-%d', '%B %d, %Y', '%d %B %Y', '%m/%d/%Y']:
                try:
                    dates.append(datetime.strptime(r.date, fmt))
                    break
                except:
                    continue
        except:
            pass
    
    if len(dates) < 5:
        return None
    
    dates.sort()
    
    # CalculateAdjacentReviewTimeseparate
    intervals = [(dates[i+1] - dates[i]).days for i in range(len(dates)-1)]
    
    if not intervals:
        return None
    
    # DetectionAggregate： short Time inside Large amountReview
    short_intervals = sum(1 for i in intervals if i <= 1)  # 1days inside 
    clustering_ratio = short_intervals / len(intervals)
    
    # Detection 48h Outbreak
    burst_count = 0
    window_size = 2  # 2daysWindow
    for i in range(len(dates) - 1):
        count_in_window = sum(1 for d in dates if 0 <= (d - dates[i]).days <= window_size)
        burst_count = max(burst_count, count_in_window)
    
    score = 0
    if clustering_ratio > 0.5:
        score += 40
    if clustering_ratio > 0.7:
        score += 20
    if burst_count > len(dates) * 0.3:
        score += 30
    
    score = min(100, score)
    
    if score < 30:
        status = "✅"
    elif score < 60:
        status = "⚠️"
    else:
        status = "🔴"
    
    return DimensionResult(
        name="Time Clustering",
        name_zh="TimeAggregate",
        score=round(score, 1),
        status=status,
        detail=f"Max {burst_count} reviews in 48h window, {clustering_ratio*100:.0f}% within 1 day",
        detail_zh=f"48h inside  most  many  {burst_count} itemReview，{clustering_ratio*100:.0f}%  in 1days inside ",
        weight=0.25
    )


def detect_rating_distribution(reviews: List[Review]) -> Optional[DimensionResult]:
    """DetectionRating Distribution"""
    rated_reviews = [r for r in reviews if r.has_rating]
    
    if len(rated_reviews) < 5:
        return None
    
    ratings = [r.rating for r in rated_reviews]
    rating_counts = Counter(ratings)
    total = len(ratings)
    
    # CalculateDistribution
    five_star_ratio = rating_counts.get(5, 0) / total
    one_star_ratio = rating_counts.get(1, 0) / total
    extreme_ratio = five_star_ratio + one_star_ratio
    
    # Natural distribution usually is：5star ~50-60%, 4star ~20%, 3star ~10%, 2star ~5%, 1star ~10%
    # Abnormal case： all 5star、Polarized
    
    score = 0
    anomaly_detail = []
    
    if five_star_ratio > 0.85:
        score += 50
        anomaly_detail.append(f"{five_star_ratio*100:.0f}% 5-star (abnormal)")
    elif five_star_ratio > 0.75:
        score += 30
        anomaly_detail.append(f"{five_star_ratio*100:.0f}% 5-star (suspicious)")
    
    # Polarized
    if extreme_ratio > 0.9 and one_star_ratio > 0.1:
        score += 30
        anomaly_detail.append("Polarized distribution")
    
    # MissingMiddleRating
    mid_ratings = sum(rating_counts.get(r, 0) for r in [2, 3, 4])
    if mid_ratings / total < 0.1 and total > 10:
        score += 20
        anomaly_detail.append("Missing mid-range ratings")
    
    score = min(100, score)
    
    if score < 30:
        status = "✅"
    elif score < 60:
        status = "⚠️"
    else:
        status = "🔴"
    
    dist_str = ", ".join([f"{r}★:{rating_counts.get(r,0)}" for r in [5,4,3,2,1]])
    
    return DimensionResult(
        name="Rating Distribution",
        name_zh="Rating Distribution",
        score=round(score, 1),
        status=status,
        detail=f"Distribution: {dist_str}. {'; '.join(anomaly_detail) if anomaly_detail else 'Normal'}",
        detail_zh=f"Distribution: {dist_str}。{'; '.join(anomaly_detail) if anomaly_detail else 'Normal'}",
        weight=0.20
    )


def detect_vp_ratio(reviews: List[Review]) -> Optional[DimensionResult]:
    """Detection Verified Purchase Ratio"""
    vp_reviews = [r for r in reviews if r.has_vp]
    
    if len(vp_reviews) < 5:
        return None
    
    vp_count = sum(1 for r in vp_reviews if r.verified_purchase)
    vp_ratio = vp_count / len(vp_reviews)
    
    # Normal VP Ratio should  should  in  60-80%
    score = 0
    if vp_ratio < 0.4:
        score = 70
    elif vp_ratio < 0.5:
        score = 50
    elif vp_ratio < 0.6:
        score = 30
    else:
        score = 10
    
    if score < 30:
        status = "✅"
    elif score < 60:
        status = "⚠️"
    else:
        status = "🔴"
    
    return DimensionResult(
        name="Verified Purchase Ratio",
        name_zh="VPRatio",
        score=round(score, 1),
        status=status,
        detail=f"{vp_ratio*100:.0f}% verified purchase ({vp_count}/{len(vp_reviews)})",
        detail_zh=f"{vp_ratio*100:.0f}%  already VerifyPurchase ({vp_count}/{len(vp_reviews)})",
        weight=0.15
    )


def detect_review_length(reviews: List[Review]) -> DimensionResult:
    """DetectionReviewDegreeDistribution"""
    lengths = [len(r.content) for r in reviews]
    
    if not lengths:
        return DimensionResult(
            name="Review Length",
            name_zh="ReviewDegree",
            score=0,
            status="✅",
            detail="No reviews",
            detail_zh="noReview",
            weight=0.05
        )
    
    avg_length = sum(lengths) / len(lengths)
    short_count = sum(1 for l in lengths if l < 50)
    short_ratio = short_count / len(lengths)
    
    # DetectionTemplate（DegreeHighDegreeConsistent）
    if len(lengths) > 5:
        length_std = (sum((l - avg_length) ** 2 for l in lengths) / len(lengths)) ** 0.5
        cv = length_std / avg_length if avg_length > 0 else 0  # Variation coefficient
    else:
        cv = 1
    
    score = 0
    if short_ratio > 0.7:
        score += 40
    if cv < 0.3 and len(lengths) > 10:  # DegreeToo consistent
        score += 40
    
    score = min(100, score)
    
    if score < 30:
        status = "✅"
    elif score < 60:
        status = "⚠️"
    else:
        status = "🔴"
    
    return DimensionResult(
        name="Review Length",
        name_zh="ReviewDegree",
        score=round(score, 1),
        status=status,
        detail=f"Avg length: {avg_length:.0f} chars, {short_ratio*100:.0f}% short (<50)",
        detail_zh=f"AverageDegree: {avg_length:.0f} Character, {short_ratio*100:.0f}%   short  (<50)",
        weight=0.05
    )


def detect_keywords(reviews: List[Review]) -> DimensionResult:
    """DetectionFake ordersKeywords"""
    # Common fake ordersReviewKeywords
    suspicious_keywords = [
        'received free', 'free product', 'in exchange', 'honest review',
        'discount code', 'promotional', 'gifted', 'complimentary',
        'five stars', '5 stars', 'best ever', 'amazing product',
        'highly recommend', 'must buy', 'perfect product',
        #  in text
        'Positive ReviewCashback', 'Five starPositive Review', 'Free trial', 'Gift'
    ]
    
    keyword_hits = 0
    for review in reviews:
        content_lower = review.content.lower()
        for keyword in suspicious_keywords:
            if keyword.lower() in content_lower:
                keyword_hits += 1
                break
    
    hit_ratio = keyword_hits / len(reviews) if reviews else 0
    score = min(100, hit_ratio * 200)
    
    if score < 30:
        status = "✅"
    elif score < 60:
        status = "⚠️"
    else:
        status = "🔴"
    
    return DimensionResult(
        name="Suspicious Keywords",
        name_zh="SuspiciousKeywords",
        score=round(score, 1),
        status=status,
        detail=f"{keyword_hits} reviews contain suspicious keywords",
        detail_zh=f"{keyword_hits} itemReviewPackagecontainSuspiciousKeywords",
        weight=0.05
    )


def identify_suspicious_reviews(reviews: List[Review], dimensions: List[DimensionResult]) -> List[SuspiciousReview]:
    """IdentifyHigh RiskReview"""
    suspicious = []
    
    for review in reviews:
        risk_score = 0
        reasons = []
        reasons_zh = []
        
        #  short Review
        if len(review.content) < 30:
            risk_score += 20
            reasons.append("Very short review")
            reasons_zh.append("Review  short ")
        
        # non VP
        if review.has_vp and not review.verified_purchase:
            risk_score += 25
            reasons.append("Not verified purchase")
            reasons_zh.append("nonVerifyPurchase")
        
        # ExtremeRating + TemplateContent
        if review.has_rating and review.rating == 5:
            generic_phrases = ['great', 'amazing', 'perfect', 'love it', 'best', 'excellent']
            if any(p in review.content.lower() for p in generic_phrases) and len(review.content) < 100:
                risk_score += 30
                reasons.append("Generic 5-star template")
                reasons_zh.append("Template5starPositive Review")
        
        # SuspiciousKeywords
        suspicious_keywords = ['received free', 'in exchange', 'honest review', 'discount']
        if any(k in review.content.lower() for k in suspicious_keywords):
            risk_score += 35
            reasons.append("Contains incentivized review keywords")
            reasons_zh.append("Contains incentiveReviewKeywords")
        
        if risk_score >= 40:
            suspicious.append(SuspiciousReview(
                content=review.content[:100] + "..." if len(review.content) > 100 else review.content,
                risk_score=min(100, risk_score),
                reasons=reasons,
                reasons_zh=reasons_zh
            ))
    
    #  by RiskScoreSort
    suspicious.sort(key=lambda x: x.risk_score, reverse=True)
    return suspicious[:10]  # Top 10


def determine_analysis_level(reviews: List[Review]) -> Tuple[AnalysisLevel, List[str], List[str]]:
    """ConfirmAnalyzelayerLevelAndMissing field"""
    available = ["content"]
    missing = []
    
    has_rating = any(r.has_rating for r in reviews)
    has_date = any(r.has_date for r in reviews)
    has_vp = any(r.has_vp for r in reviews)
    has_reviewer = any(r.reviewer_name for r in reviews)
    
    if has_rating:
        available.append("rating")
    else:
        missing.append("rating")
    
    if has_date:
        available.append("date")
    else:
        missing.append("date")
    
    if has_vp:
        available.append("verified_purchase")
    else:
        missing.append("verified_purchase")
    
    if has_reviewer:
        available.append("reviewer_info")
    else:
        missing.append("reviewer_info")
    
    # Determine levelLevel
    if has_rating and has_date and has_vp:
        level = AnalysisLevel.L4_FULL
    elif has_rating and has_date:
        level = AnalysisLevel.L3_SCORED
    elif has_date:
        level = AnalysisLevel.L2_TIMED
    else:
        level = AnalysisLevel.L1_BASIC
    
    return level, available, missing


def generate_deepening_hints(missing: List[str]) -> Tuple[List[str], List[str]]:
    """GenerateDeepenHint"""
    hints_en = []
    hints_zh = []
    
    hint_map = {
        "rating": (
            "Add star ratings → Unlock 'Rating Distribution Analysis'",
            "Add starLevelRating → Unlock「Rating DistributionAnalyze」"
        ),
        "date": (
            "Add review dates → Unlock 'Time Clustering Detection'",
            "SupplementReviewDayPeriod → Unlock「TimeAggregateDetection」"
        ),
        "verified_purchase": (
            "Add VP status → Unlock 'Verified Purchase Analysis'",
            "SupplementVPStatus → Unlock「PurchaseVerifyAnalyze」"
        ),
        "reviewer_info": (
            "Add reviewer info → Unlock 'Account Profile Analysis'",
            "SupplementReviewpersonInformation → Unlock「Account profileAnalyze」"
        ),
    }
    
    for field in missing:
        if field in hint_map:
            hints_en.append(hint_map[field][0])
            hints_zh.append(hint_map[field][1])
    
    return hints_en, hints_zh


def analyze_reviews(reviews: List[Review], asin: str = "UNKNOWN") -> AnalysisResult:
    """MainAnalyzeFunction"""
    if not reviews:
        return AnalysisResult(
            asin=asin,
            total_reviews=0,
            analysis_level=AnalysisLevel.L1_BASIC,
            authenticity_score=50,
            risk_level=RiskLevel.MEDIUM,
            dimensions=[],
            suspicious_reviews=[],
            available_fields=[],
            missing_fields=["content"],
            deepening_hints=["Please provide review data"],
            deepening_hints_zh=["Please provideReview Countdata"],
            summary="No reviews to analyze",
            summary_zh="noReview Countdata"
        )
    
    # ConfirmAnalyzelayerLevel
    level, available, missing = determine_analysis_level(reviews)
    hints_en, hints_zh = generate_deepening_hints(missing)
    
    # ExecuteDetection
    dimensions = []
    
    # L1: BasicDetection (AlwaysExecute)
    dimensions.append(detect_content_similarity(reviews))
    dimensions.append(detect_review_length(reviews))
    dimensions.append(detect_keywords(reviews))
    
    # L2+: TimeDetection
    time_result = detect_time_clustering(reviews)
    if time_result:
        dimensions.append(time_result)
    
    # L3+: RatingDetection
    rating_result = detect_rating_distribution(reviews)
    if rating_result:
        dimensions.append(rating_result)
    
    # L4: VPDetection
    vp_result = detect_vp_ratio(reviews)
    if vp_result:
        dimensions.append(vp_result)
    
    # CalculateComprehensiveScore (WeightedAverageSuspiciousDegree，ThenConvert toAuthenticityScore)
    total_weight = sum(d.weight for d in dimensions)
    if total_weight > 0:
        suspicion_score = sum(d.score * d.weight for d in dimensions) / total_weight
    else:
        suspicion_score = 50
    
    authenticity_score = max(0, min(100, 100 - suspicion_score))
    
    # ConfirmRiskGrade
    if authenticity_score >= 70:
        risk_level = RiskLevel.LOW
    elif authenticity_score >= 50:
        risk_level = RiskLevel.MEDIUM
    elif authenticity_score >= 30:
        risk_level = RiskLevel.HIGH
    else:
        risk_level = RiskLevel.CRITICAL
    
    # IdentifySuspiciousReview
    suspicious = identify_suspicious_reviews(reviews, dimensions)
    
    # GenerateSummary
    risk_text = {
        RiskLevel.LOW: ("Low risk - Reviews appear authentic", "Low Risk - ReviewLooks likeReal"),
        RiskLevel.MEDIUM: ("Medium risk - Some concerns detected", " in  etcRisk - FoundSomeConcern"),
        RiskLevel.HIGH: ("High risk - Multiple red flags", "High Risk -  many DangerSignal"),
        RiskLevel.CRITICAL: ("Critical risk - Likely fake reviews", "CriticalRisk - MayExistLarge amountFakeReview"),
    }
    
    summary_en = f"{risk_text[risk_level][0]}. Analyzed {len(reviews)} reviews at {level.value} level."
    summary_zh = f"{risk_text[risk_level][1]}。Analyze  {len(reviews)} itemReview，AnalyzelayerLevel {level.value}。"
    
    return AnalysisResult(
        asin=asin,
        total_reviews=len(reviews),
        analysis_level=level,
        authenticity_score=round(authenticity_score),
        risk_level=risk_level,
        dimensions=dimensions,
        suspicious_reviews=suspicious,
        available_fields=available,
        missing_fields=missing,
        deepening_hints=hints_en,
        deepening_hints_zh=hints_zh,
        summary=summary_en,
        summary_zh=summary_zh
    )


# ============================================================
# OutputFormat
# ============================================================

def format_report(result: AnalysisResult, lang: str = "en") -> str:
    """FormatReport"""
    risk_icons = {
        RiskLevel.LOW: "✅",
        RiskLevel.MEDIUM: "⚠️",
        RiskLevel.HIGH: "🔴",
        RiskLevel.CRITICAL: "💀",
    }
    
    if lang == "zh":
        lines = [
            f"📊 **ReviewAuthenticityAnalyzeReport**",
            f"",
            f"**ASIN**: {result.asin}",
            f"**Review Count**: {result.total_reviews}",
            f"**AnalyzelayerLevel**: {result.analysis_level.value}",
            f"",
            f"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            f"",
            f"## AuthenticityRating: {result.authenticity_score}/100 {risk_icons[result.risk_level]}",
            f"",
            f"{result.summary_zh}",
            f"",
            f"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            f"",
            f"## DetectiondimensionDegree",
            f"",
        ]
        
        for d in result.dimensions:
            lines.append(f"{d.status} **{d.name_zh}**: {d.score:.0f}/100")
            lines.append(f"   {d.detail_zh}")
            lines.append("")
        
        if result.suspicious_reviews:
            lines.append("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
            lines.append("")
            lines.append(f"## High RiskReview (Top {len(result.suspicious_reviews)})")
            lines.append("")
            for i, sr in enumerate(result.suspicious_reviews[:5], 1):
                lines.append(f"**{i}. Risk {sr.risk_score:.0f}%**")
                lines.append(f'   "{sr.content}"')
                lines.append(f"   Reason: {', '.join(sr.reasons_zh)}")
                lines.append("")
        
        if result.deepening_hints_zh:
            lines.append("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
            lines.append("")
            lines.append("🔍 **Want more accurateAnalyze？Supplement with following info:**")
            lines.append("")
            for hint in result.deepening_hints_zh:
                lines.append(f"• {hint}")
    else:
        lines = [
            f"📊 **Review Authenticity Report**",
            f"",
            f"**ASIN**: {result.asin}",
            f"**Reviews**: {result.total_reviews}",
            f"**Analysis Level**: {result.analysis_level.value}",
            f"",
            f"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            f"",
            f"## Authenticity Score: {result.authenticity_score}/100 {risk_icons[result.risk_level]}",
            f"",
            f"{result.summary}",
            f"",
            f"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            f"",
            f"## Detection Dimensions",
            f"",
        ]
        
        for d in result.dimensions:
            lines.append(f"{d.status} **{d.name}**: {d.score:.0f}/100")
            lines.append(f"   {d.detail}")
            lines.append("")
        
        if result.suspicious_reviews:
            lines.append("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
            lines.append("")
            lines.append(f"## Suspicious Reviews (Top {len(result.suspicious_reviews)})")
            lines.append("")
            for i, sr in enumerate(result.suspicious_reviews[:5], 1):
                lines.append(f"**{i}. Risk {sr.risk_score:.0f}%**")
                lines.append(f'   "{sr.content}"')
                lines.append(f"   Reasons: {', '.join(sr.reasons)}")
                lines.append("")
        
        if result.deepening_hints:
            lines.append("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
            lines.append("")
            lines.append("🔍 **Want more accurate analysis? Add the following:**")
            lines.append("")
            for hint in result.deepening_hints:
                lines.append(f"• {hint}")
    
    return "\n".join(lines)


# ============================================================
# Parse
# ============================================================

def parse_simple_reviews(text: str) -> List[Review]:
    """ParseSimpleTextFormatReview"""
    reviews = []
    
    # TrySplit by paragraph
    paragraphs = re.split(r'\n\n+', text.strip())
    
    for para in paragraphs:
        para = para.strip()
        if len(para) > 10:
            review = Review(content=para)
            
            # TryExtract starLevel
            star_match = re.search(r'(\d)\s*(?:star|★|⭐)', para, re.I)
            if star_match:
                review.rating = int(star_match.group(1))
            
            # TryExtractDayPeriod
            date_match = re.search(r'(\d{4}-\d{2}-\d{2}|\w+\s+\d{1,2},?\s+\d{4})', para)
            if date_match:
                review.date = date_match.group(1)
            
            # TryExtract VP
            if 'verified purchase' in para.lower() or 'VP' in para:
                review.verified_purchase = True
            elif 'not verified' in para.lower():
                review.verified_purchase = False
            
            reviews.append(review)
    
    return reviews


# ============================================================
# CLI Entry Point
# ============================================================

def main():
    """CLI Entry Point"""
    # TestData
    test_reviews = [
        Review(content="Great product! Works perfectly. Highly recommend to everyone.", rating=5, verified_purchase=True, date="2024-01-15"),
        Review(content="Amazing! Best purchase ever. Love it!", rating=5, verified_purchase=False, date="2024-01-15"),
        Review(content="Great product! Works perfectly. Must buy!", rating=5, verified_purchase=False, date="2024-01-16"),
        Review(content="Received free product in exchange for honest review. It's good.", rating=5, verified_purchase=False, date="2024-01-16"),
        Review(content="Excellent quality, fast shipping. Very satisfied with purchase.", rating=5, verified_purchase=True, date="2024-01-20"),
        Review(content="Not as described. Cheap quality.", rating=1, verified_purchase=True, date="2024-02-01"),
        Review(content="Perfect!", rating=5, verified_purchase=False, date="2024-01-16"),
        Review(content="Good value for money. Does what it says.", rating=4, verified_purchase=True, date="2024-02-15"),
        Review(content="Five stars! Amazing product!", rating=5, verified_purchase=False, date="2024-01-17"),
        Review(content="Decent product for the price.", rating=3, verified_purchase=True, date="2024-03-01"),
    ]
    
    # If command lineInput
    if len(sys.argv) > 1:
        arg = sys.argv[1]
        if arg == "--demo":
            pass  # UseTestData
        elif arg.startswith('['):
            # JSON group
            try:
                data = json.loads(arg)
                test_reviews = [Review(**r) for r in data]
            except:
                pass
        else:
            # pureText
            test_reviews = parse_simple_reviews(arg)
    
    result = analyze_reviews(test_reviews, asin="B08XXXXX")
    
    # Default ChineseOutput
    lang = "zh" if "--zh" in sys.argv else "en"
    print(format_report(result, lang))


if __name__ == "__main__":
    main()

FILE:scripts/parser.py
#!/usr/bin/env python3
"""
Review Parser - Multi-format Input Parser
ReviewParse -  many FormatInputParse

SupportFormat:
- pureText (Paragraph separator)
- JSON
- CSV
- TSV
- Markdown Table

Version: 1.0.0
"""

import json
import csv
import re
from typing import List, Optional
from dataclasses import dataclass
from io import StringIO


@dataclass
class Review:
    """Single itemReview"""
    content: str
    rating: Optional[int] = None
    date: Optional[str] = None
    reviewer_name: Optional[str] = None
    verified_purchase: Optional[bool] = None
    helpful_votes: Optional[int] = None
    reviewer_reviews_count: Optional[int] = None


class ReviewParser:
    """ many FormatReviewParse"""
    
    @staticmethod
    def detect_format(text: str) -> str:
        """DetectionInputFormat"""
        text = text.strip()
        
        # JSON group
        if text.startswith('[') and text.endswith(']'):
            try:
                json.loads(text)
                return 'json'
            except:
                pass
        
        # JSON Object
        if text.startswith('{'):
            try:
                json.loads(text)
                return 'json_single'
            except:
                pass
        
        # CSV (CheckComma separated with header)
        lines = text.split('\n')
        if len(lines) > 1:
            first_line = lines[0].lower()
            if ',' in first_line and any(h in first_line for h in ['content', 'review', 'rating', 'date', 'text']):
                return 'csv'
        
        # TSV
        if len(lines) > 1 and '\t' in lines[0]:
            return 'tsv'
        
        # Markdown Table
        if '|' in text and '---' in text:
            return 'markdown'
        
        # DefaultpureText
        return 'text'
    
    @staticmethod
    def parse(text: str) -> List[Review]:
        """ParseReview"""
        format_type = ReviewParser.detect_format(text)
        
        parsers = {
            'json': ReviewParser.parse_json,
            'json_single': ReviewParser.parse_json_single,
            'csv': ReviewParser.parse_csv,
            'tsv': ReviewParser.parse_tsv,
            'markdown': ReviewParser.parse_markdown,
            'text': ReviewParser.parse_text,
        }
        
        parser = parsers.get(format_type, ReviewParser.parse_text)
        return parser(text)
    
    @staticmethod
    def parse_json(text: str) -> List[Review]:
        """Parse JSON group"""
        try:
            data = json.loads(text)
            reviews = []
            for item in data:
                review = Review(
                    content=item.get('content', item.get('text', item.get('review', ''))),
                    rating=item.get('rating', item.get('stars', item.get('star'))),
                    date=item.get('date', item.get('review_date')),
                    reviewer_name=item.get('reviewer_name', item.get('author', item.get('name'))),
                    verified_purchase=item.get('verified_purchase', item.get('vp', item.get('verified'))),
                    helpful_votes=item.get('helpful_votes', item.get('helpful')),
                )
                if review.content:
                    reviews.append(review)
            return reviews
        except:
            return []
    
    @staticmethod
    def parse_json_single(text: str) -> List[Review]:
        """ParseSingle JSON Object"""
        try:
            item = json.loads(text)
            review = Review(
                content=item.get('content', item.get('text', item.get('review', ''))),
                rating=item.get('rating', item.get('stars')),
                date=item.get('date'),
                reviewer_name=item.get('reviewer_name', item.get('author')),
                verified_purchase=item.get('verified_purchase', item.get('vp')),
            )
            return [review] if review.content else []
        except:
            return []
    
    @staticmethod
    def parse_csv(text: str) -> List[Review]:
        """Parse CSV"""
        reviews = []
        try:
            reader = csv.DictReader(StringIO(text))
            for row in reader:
                # TryMultipleField name
                content = (
                    row.get('content') or row.get('Content') or
                    row.get('review') or row.get('Review') or
                    row.get('text') or row.get('Text') or
                    row.get('review_text') or row.get('body') or ''
                )
                
                rating_str = (
                    row.get('rating') or row.get('Rating') or
                    row.get('stars') or row.get('Stars') or
                    row.get('star') or ''
                )
                rating = None
                if rating_str:
                    try:
                        rating = int(float(rating_str))
                    except:
                        pass
                
                date = (
                    row.get('date') or row.get('Date') or
                    row.get('review_date') or row.get('created_at') or None
                )
                
                vp_str = (
                    row.get('verified_purchase') or row.get('vp') or
                    row.get('verified') or row.get('VP') or ''
                )
                vp = None
                if vp_str:
                    vp = vp_str.lower() in ['true', 'yes', '1', 'y', 'verified']
                
                reviewer = (
                    row.get('reviewer_name') or row.get('author') or
                    row.get('name') or row.get('reviewer') or None
                )
                
                if content:
                    reviews.append(Review(
                        content=content,
                        rating=rating,
                        date=date,
                        reviewer_name=reviewer,
                        verified_purchase=vp,
                    ))
        except Exception as e:
            print(f"CSV parse error: {e}")
        
        return reviews
    
    @staticmethod
    def parse_tsv(text: str) -> List[Review]:
        """Parse TSV"""
        # Convert to CSV FormatProcess
        csv_text = text.replace('\t', ',')
        return ReviewParser.parse_csv(csv_text)
    
    @staticmethod
    def parse_markdown(text: str) -> List[Review]:
        """Parse Markdown Table"""
        reviews = []
        lines = text.strip().split('\n')
        
        # find to Tablehead
        header_line = None
        data_start = 0
        for i, line in enumerate(lines):
            if '|' in line and '---' not in line:
                header_line = line
                data_start = i + 2  # Skip separator lines
                break
        
        if not header_line:
            return []
        
        # ParseTablehead
        headers = [h.strip().lower() for h in header_line.split('|') if h.strip()]
        
        # ParseDatarow
        for line in lines[data_start:]:
            if '|' not in line:
                continue
            
            cells = [c.strip() for c in line.split('|') if c.strip()]
            if len(cells) < len(headers):
                continue
            
            row = dict(zip(headers, cells))
            
            content = row.get('content', row.get('review', row.get('text', '')))
            rating = None
            rating_str = row.get('rating', row.get('stars', ''))
            if rating_str:
                try:
                    rating = int(float(rating_str.replace('★', '').strip()))
                except:
                    pass
            
            if content:
                reviews.append(Review(
                    content=content,
                    rating=rating,
                    date=row.get('date'),
                    reviewer_name=row.get('author', row.get('reviewer')),
                ))
        
        return reviews
    
    @staticmethod
    def parse_text(text: str) -> List[Review]:
        """ParsepureText"""
        reviews = []
        
        # TrySplit by paragraph
        paragraphs = re.split(r'\n\n+', text.strip())
        
        for para in paragraphs:
            para = para.strip()
            if len(para) < 10:
                continue
            
            review = Review(content=para)
            
            # TryExtract starLevel
            star_patterns = [
                r'(\d)\s*(?:star|stars|★|⭐)',
                r'(?:star|stars|rating)[:\s]*(\d)',
                r'^(\d)★',
                r'^(\d)\s*star',
            ]
            for pattern in star_patterns:
                match = re.search(pattern, para, re.I)
                if match:
                    review.rating = int(match.group(1))
                    break
            
            # TryExtractDayPeriod
            date_patterns = [
                r'(\d{4}-\d{2}-\d{2})',
                r'(\w+\s+\d{1,2},?\s+\d{4})',
                r'(\d{1,2}/\d{1,2}/\d{4})',
            ]
            for pattern in date_patterns:
                match = re.search(pattern, para)
                if match:
                    review.date = match.group(1)
                    break
            
            # TryExtract VP Status
            if re.search(r'verified\s*purchase', para, re.I):
                review.verified_purchase = True
            elif re.search(r'not\s*verified', para, re.I):
                review.verified_purchase = False
            
            reviews.append(review)
        
        return reviews


def parse_reviews(text: str) -> List[Review]:
    """ConvenientFunction"""
    return ReviewParser.parse(text)


# CLI
if __name__ == "__main__":
    import sys
    
    if len(sys.argv) > 1:
        text = sys.argv[1]
    else:
        # TestData
        text = """
content,rating,date,verified_purchase
"Great product!",5,2024-01-15,true
"Not good",2,2024-01-16,false
"Amazing!",5,2024-01-17,true
"""
    
    reviews = parse_reviews(text)
    print(f"Parsed {len(reviews)} reviews:")
    for r in reviews:
        print(f"  - {r.rating}★ | VP:{r.verified_purchase} | {r.content[:50]}...")

FILE:scripts/report_html.py
#!/usr/bin/env python3
"""
Review Analysis HTML Report Generator
ReviewAnalyze HTML ReportGenerate

Features:
- CanViewTable (Chart.js)
- Responsive layout
-  deep colorMaintopic
- InteractiveDataDisplay

Version: 1.0.0
"""

import json
from typing import List, Dict, Any
from datetime import datetime


def generate_html_report(
    asin: str,
    authenticity_score: int,
    risk_level: str,
    dimensions: List[Dict[str, Any]],
    suspicious_reviews: List[Dict[str, Any]],
    total_reviews: int,
    analysis_level: str,
    summary: str,
    output_path: str = "review_analysis_report.html"
) -> str:
    """Generate HTML Report"""
    
    # RiskGradeColor
    risk_colors = {
        "low": "#10b981",      # Green
        "medium": "#f59e0b",   # Yellow
        "high": "#ef4444",     # Red
        "critical": "#7c2d12", #  deep red
    }
    
    risk_color = risk_colors.get(risk_level.lower(), "#6b7280")
    
    # dimensionDegreeData (use at chartTable)
    dimension_labels = json.dumps([d.get('name', d.get('name_zh', '')) for d in dimensions])
    dimension_scores = json.dumps([d.get('score', 0) for d in dimensions])
    
    # SuspiciousReview JSON
    suspicious_json = json.dumps(suspicious_reviews[:10], ensure_ascii=False, default=str)
    
    html = f"""<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Review Analysis Report - {asin}</title>
    <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
    <style>
        * {{
            margin: 0;
            padding: 0;
            box-sizing: border-box;
        }}
        
        body {{
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
            background: linear-gradient(135deg, #1a1a2e 0%, #16213e 100%);
            color: #e4e4e7;
            min-height: 100vh;
            padding: 20px;
        }}
        
        .container {{
            max-width: 1200px;
            margin: 0 auto;
        }}
        
        .header {{
            text-align: center;
            padding: 40px 20px;
            background: rgba(255,255,255,0.05);
            border-radius: 16px;
            margin-bottom: 30px;
        }}
        
        .header h1 {{
            font-size: 2rem;
            background: linear-gradient(90deg, #a78bfa, #818cf8);
            -webkit-background-clip: text;
            -webkit-text-fill-color: transparent;
            margin-bottom: 10px;
        }}
        
        .header .asin {{
            color: #a1a1aa;
            font-size: 1.1rem;
        }}
        
        .score-card {{
            background: rgba(255,255,255,0.08);
            border-radius: 16px;
            padding: 40px;
            text-align: center;
            margin-bottom: 30px;
            border: 1px solid rgba(255,255,255,0.1);
        }}
        
        .score-number {{
            font-size: 5rem;
            font-weight: bold;
            color: {risk_color};
            line-height: 1;
        }}
        
        .score-label {{
            font-size: 1.2rem;
            color: #a1a1aa;
            margin-top: 10px;
        }}
        
        .risk-badge {{
            display: inline-block;
            padding: 8px 20px;
            border-radius: 20px;
            background: {risk_color};
            color: white;
            font-weight: 600;
            margin-top: 15px;
            text-transform: uppercase;
        }}
        
        .grid {{
            display: grid;
            grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
            gap: 20px;
            margin-bottom: 30px;
        }}
        
        .card {{
            background: rgba(255,255,255,0.08);
            border-radius: 12px;
            padding: 24px;
            border: 1px solid rgba(255,255,255,0.1);
        }}
        
        .card h3 {{
            font-size: 1.1rem;
            margin-bottom: 20px;
            color: #a78bfa;
        }}
        
        .stat {{
            display: flex;
            justify-content: space-between;
            padding: 12px 0;
            border-bottom: 1px solid rgba(255,255,255,0.1);
        }}
        
        .stat:last-child {{
            border-bottom: none;
        }}
        
        .stat-label {{
            color: #a1a1aa;
        }}
        
        .stat-value {{
            font-weight: 600;
        }}
        
        .chart-container {{
            position: relative;
            height: 300px;
            width: 100%;
        }}
        
        .dimension-item {{
            display: flex;
            align-items: center;
            padding: 12px 0;
            border-bottom: 1px solid rgba(255,255,255,0.1);
        }}
        
        .dimension-icon {{
            width: 30px;
            font-size: 1.2rem;
        }}
        
        .dimension-name {{
            flex: 1;
        }}
        
        .dimension-score {{
            font-weight: 600;
            width: 80px;
            text-align: right;
        }}
        
        .suspicious-item {{
            background: rgba(239, 68, 68, 0.1);
            border: 1px solid rgba(239, 68, 68, 0.3);
            border-radius: 8px;
            padding: 16px;
            margin-bottom: 12px;
        }}
        
        .suspicious-header {{
            display: flex;
            justify-content: space-between;
            margin-bottom: 8px;
        }}
        
        .suspicious-risk {{
            color: #ef4444;
            font-weight: 600;
        }}
        
        .suspicious-content {{
            color: #d4d4d8;
            font-style: italic;
            margin-bottom: 8px;
        }}
        
        .suspicious-reasons {{
            color: #a1a1aa;
            font-size: 0.9rem;
        }}
        
        .summary {{
            background: rgba(167, 139, 250, 0.1);
            border: 1px solid rgba(167, 139, 250, 0.3);
            border-radius: 12px;
            padding: 20px;
            margin-bottom: 30px;
        }}
        
        .footer {{
            text-align: center;
            padding: 20px;
            color: #71717a;
            font-size: 0.9rem;
        }}
        
        @media (max-width: 768px) {{
            .score-number {{
                font-size: 3rem;
            }}
            .grid {{
                grid-template-columns: 1fr;
            }}
        }}
    </style>
</head>
<body>
    <div class="container">
        <div class="header">
            <h1>📊 Review Authenticity Analysis</h1>
            <div class="asin">ASIN: {asin}</div>
        </div>
        
        <div class="score-card">
            <div class="score-number">{authenticity_score}</div>
            <div class="score-label">Authenticity Score (0-100)</div>
            <div class="risk-badge">{risk_level.upper()} RISK</div>
        </div>
        
        <div class="summary">
            <strong>Summary:</strong> {summary}
        </div>
        
        <div class="grid">
            <div class="card">
                <h3>📈 Overview</h3>
                <div class="stat">
                    <span class="stat-label">Total Reviews</span>
                    <span class="stat-value">{total_reviews}</span>
                </div>
                <div class="stat">
                    <span class="stat-label">Analysis Level</span>
                    <span class="stat-value">{analysis_level}</span>
                </div>
                <div class="stat">
                    <span class="stat-label">Suspicious Reviews</span>
                    <span class="stat-value">{len(suspicious_reviews)}</span>
                </div>
                <div class="stat">
                    <span class="stat-label">Generated</span>
                    <span class="stat-value">{datetime.now().strftime('%Y-%m-%d %H:%M')}</span>
                </div>
            </div>
            
            <div class="card">
                <h3>🎯 Detection Dimensions</h3>
                <div class="chart-container">
                    <canvas id="dimensionChart"></canvas>
                </div>
            </div>
        </div>
        
        <div class="card" style="margin-bottom: 30px;">
            <h3>🔍 Dimension Details</h3>
            {"".join([f'''
            <div class="dimension-item">
                <div class="dimension-icon">{d.get('status', '❓')}</div>
                <div class="dimension-name">{d.get('name', d.get('name_zh', ''))}</div>
                <div class="dimension-score" style="color: {'#10b981' if d.get('score', 0) < 30 else '#f59e0b' if d.get('score', 0) < 60 else '#ef4444'}">{d.get('score', 0):.0f}/100</div>
            </div>
            <div style="color: #a1a1aa; font-size: 0.9rem; padding-left: 30px; padding-bottom: 12px;">{d.get('detail', d.get('detail_zh', ''))}</div>
            ''' for d in dimensions])}
        </div>
        
        <div class="card">
            <h3>⚠️ Suspicious Reviews (Top {min(len(suspicious_reviews), 5)})</h3>
            <div id="suspiciousReviews"></div>
        </div>
        
        <div class="footer">
            <p>Generated by Amazon Review Checker | Nexscope AI</p>
            <p>This analysis is for reference only. Results may not be 100% accurate.</p>
        </div>
    </div>
    
    <script>
        // dimensionDegreeRadar chart
        const ctx = document.getElementById('dimensionChart').getContext('2d');
        new Chart(ctx, {{
            type: 'radar',
            data: {{
                labels: {dimension_labels},
                datasets: [{{
                    label: 'Suspicion Score',
                    data: {dimension_scores},
                    backgroundColor: 'rgba(167, 139, 250, 0.2)',
                    borderColor: 'rgba(167, 139, 250, 1)',
                    borderWidth: 2,
                    pointBackgroundColor: 'rgba(167, 139, 250, 1)',
                }}]
            }},
            options: {{
                responsive: true,
                maintainAspectRatio: false,
                scales: {{
                    r: {{
                        beginAtZero: true,
                        max: 100,
                        ticks: {{
                            color: '#a1a1aa',
                            backdropColor: 'transparent'
                        }},
                        grid: {{
                            color: 'rgba(255,255,255,0.1)'
                        }},
                        pointLabels: {{
                            color: '#e4e4e7',
                            font: {{ size: 11 }}
                        }}
                    }}
                }},
                plugins: {{
                    legend: {{
                        display: false
                    }}
                }}
            }}
        }});
        
        // SuspiciousReview
        const suspicious = {suspicious_json};
        const container = document.getElementById('suspiciousReviews');
        
        if (suspicious.length === 0) {{
            container.innerHTML = '<p style="color: #10b981;">No highly suspicious reviews detected.</p>';
        }} else {{
            suspicious.slice(0, 5).forEach((review, index) => {{
                container.innerHTML += `
                    <div class="suspicious-item">
                        <div class="suspicious-header">
                            <span>#{index + 1}</span>
                            <span class="suspicious-risk">Risk: {review.risk_score?.toFixed(0) || 'N/A'}%</span>
                        </div>
                        <div class="suspicious-content">"{review.content}"</div>
                        <div class="suspicious-reasons">Reasons: {(review.reasons || review.reasons_zh || []).join(', ')}</div>
                    </div>
                `;
            }});
        }}
    </script>
</body>
</html>
"""
    
    # SaveFile
    with open(output_path, 'w', encoding='utf-8') as f:
        f.write(html)
    
    print(f"✅ HTML report saved to: {output_path}")
    return output_path


# CLI
if __name__ == "__main__":
    # TestData
    generate_html_report(
        asin="B08XXXXX",
        authenticity_score=66,
        risk_level="medium",
        dimensions=[
            {"name": "Content Similarity", "name_zh": "Similar contentDegree", "score": 24, "status": "✅", "detail": "Found 0 similar review pairs"},
            {"name": "Time Clustering", "name_zh": "TimeAggregate", "score": 70, "status": "🔴", "detail": "6 reviews in 48h window"},
            {"name": "Rating Distribution", "name_zh": "Rating Distribution", "score": 0, "status": "✅", "detail": "Normal distribution"},
            {"name": "VP Ratio", "name_zh": "VPRatio", "score": 30, "status": "⚠️", "detail": "50% verified purchase"},
            {"name": "Review Length", "name_zh": "ReviewDegree", "score": 0, "status": "✅", "detail": "Normal length distribution"},
            {"name": "Suspicious Keywords", "name_zh": "SuspiciousKeywords", "score": 80, "status": "🔴", "detail": "4 reviews contain suspicious keywords"},
        ],
        suspicious_reviews=[
            {"content": "Perfect!", "risk_score": 75, "reasons": ["Very short", "Not VP", "Generic template"]},
            {"content": "Five stars! Amazing product!", "risk_score": 75, "reasons": ["Very short", "Not VP", "Generic template"]},
            {"content": "Received free product in exchange for honest review...", "risk_score": 60, "reasons": ["Not VP", "Incentivized review"]},
        ],
        total_reviews=10,
        analysis_level="L4",
        summary="Medium risk - Some concerns detected. Analyzed 10 reviews at L4 level.",
        output_path="review_analysis_report.html"
    )

ClawHub Backend Testing+2

Profit Margin Calculator Walmart

Skill

Walmart profit margin calculator for sellers. Calculate cost breakdowns including WFS fulfillment, storage fees, and referral fees. Includes comparison with...

---
name: profit-margin-calculator-walmart
version: 1.0.0
description: "Walmart profit margin calculator for sellers. Calculate cost breakdowns including WFS fulfillment, storage fees, and referral fees. Includes comparison with Amazon FBA and lower competition advantage analysis. No API key required."
metadata: {"nexscope":{"emoji":"💰","category":"ecommerce"}}
---

# Profit Margin Calculator — Walmart 💰

Calculate product profitability for Walmart Marketplace sellers — cost breakdowns, profit margins, and WFS fee analysis.

## Installation

```bash
npx skills add nexscope-ai/eCommerce-Skills --skill profit-margin-calculator-walmart -g
```

## Cost Components

| Cost Item | Description |
|-----------|-------------|
| Product Cost | FOB purchase price |
| Inbound Shipping | Sea/air freight to WFS |
| WFS Fulfillment | Walmart Fulfillment Services |
| WFS Storage | Monthly storage fee |
| Referral Fee | Platform commission (8-15%) |
| Advertising | Walmart Connect ads |
| Return Cost | Return processing loss |

## Walmart vs Amazon

| Item | Walmart | Amazon |
|------|---------|--------|
| Fulfillment | WFS | FBA |
| Referral fee | Lower | Higher |
| Monthly storage | No fee | Yes |
| Competition | Lower | High |

## Usage

```bash
python3 scripts/calculator.py

python3 scripts/calculator.py '{"selling_price": 24.99, "product_cost": 6, "wfs_fee": 4.95}'
```

## Output Example

```
💰 **Walmart Profit Analysis Report**

Selling Price         $24.99   100.0%
────────────────────────────────────────
Product Cost          -$6.00    24.0%
WFS Fulfillment       -$4.95    19.8%
Referral Fee          -$3.75    15.0%
...
────────────────────────────────────────
Net Profit            $6.19    24.8%
```

## Walmart Advantages

| Advantage | Benefit |
|-----------|---------|
| **No long-term storage** | Better for slow movers |
| **Lower referral fees** | 6-15% vs 8-15% |
| **Less competition** | Easier ranking |
| **Growing marketplace** | More opportunities |

## Referral Fee Rates

| Category | Rate |
|----------|------|
| Electronics | 8% |
| Apparel | 15% |
| Home & Kitchen | 15% |
| Most categories | 8-15% |

---

**Part of [Nexscope AI](https://www.nexscope.ai/) — AI tools for e-commerce sellers.**

FILE:scripts/calculator.py
#!/usr/bin/env python3
"""
Amazon Profit Calculator - Core Engine

Features:
- Cost breakdown calculation
- Profit margin calculation (gross/net)
- Break-even analysis
- Pricing recommendations
- Batch calculation support

Version: 1.0.0
"""

import json
import csv
from dataclasses import dataclass, field
from typing import List, Dict, Optional
from enum import Enum
import sys


class ProfitStatus(Enum):
    HEALTHY = "healthy"      # >20% net margin
    WARNING = "warning"      # 5-20% net margin
    DANGER = "danger"        # <5% net margin
    LOSS = "loss"            # Negative margin


# ============================================================
# Amazon Referral Fee Rates (by category)
# ============================================================

REFERRAL_FEE_RATES = {
    # Category: Rate
    "default": 0.15,
    "electronics": 0.08,
    "computers": 0.08,
    "camera": 0.08,
    "video_games": 0.15,
    "books": 0.15,
    "clothing": 0.17,
    "shoes": 0.15,
    "jewelry": 0.20,
    "watches": 0.15,
    "furniture": 0.15,
    "home": 0.15,
    "kitchen": 0.15,
    "beauty": 0.15,
    "health": 0.15,
    "grocery": 0.15,
    "pet": 0.15,
    "toys": 0.15,
    "baby": 0.15,
    "sports": 0.15,
    "outdoors": 0.15,
    "automotive": 0.12,
    "industrial": 0.12,
    "office": 0.15,
}

# FBA Fulfillment Fee Reference (simplified, based on size tier)
FBA_FULFILLMENT_FEES = {
    "small_standard": 3.22,      # Small standard (<1lb)
    "large_standard_1lb": 4.75,  # Large standard (<1lb)
    "large_standard_2lb": 5.40,  # Large standard (1-2lb)
    "large_standard_3lb": 6.10,  # Large standard (2-3lb)
    "small_oversize": 9.73,      # Small oversize
    "medium_oversize": 19.05,    # Medium oversize
    "large_oversize": 89.98,     # Large oversize
}

# Profit margin thresholds
PROFIT_THRESHOLDS = {
    "healthy": 0.20,    # >20%
    "warning": 0.05,    # 5-20%
    "danger": 0.00,     # 0-5%
}


# ============================================================
# Data Structures
# ============================================================

@dataclass
class ProductInput:
    """Single product input data"""
    sku: str = "SKU001"
    name: str = "Product"
    
    # Selling price
    selling_price: float = 0.0
    
    # Cost items
    product_cost: float = 0.0           # Product cost (FOB)
    shipping_cost: float = 0.0          # Inbound shipping
    fba_fulfillment_fee: float = 0.0    # FBA fulfillment fee
    fba_storage_fee: float = 0.0        # FBA storage fee (monthly avg)
    
    # Optional costs
    ad_spend_ratio: float = 0.0         # Ad spend ratio (0-1)
    return_rate: float = 0.0            # Return rate (0-1)
    return_processing_fee: float = 0.0  # Return processing fee per unit
    other_fees: float = 0.0             # Other fees
    
    # Platform related
    category: str = "default"           # Category (for Referral Fee)
    referral_fee_rate: Optional[float] = None  # Custom commission rate
    
    # For batch calculation
    monthly_sales: int = 0              # Monthly sales (for fixed cost allocation)
    fixed_costs: float = 0.0            # Fixed costs (for break-even)


@dataclass
class CostBreakdown:
    """Cost breakdown"""
    selling_price: float
    product_cost: float
    shipping_cost: float
    fba_fulfillment_fee: float
    fba_storage_fee: float
    referral_fee: float
    ad_cost: float
    return_cost: float
    other_fees: float
    
    total_cost: float = 0.0
    gross_profit: float = 0.0
    net_profit: float = 0.0
    gross_margin: float = 0.0
    net_margin: float = 0.0
    
    def __post_init__(self):
        self.total_cost = (
            self.product_cost +
            self.shipping_cost +
            self.fba_fulfillment_fee +
            self.fba_storage_fee +
            self.referral_fee +
            self.ad_cost +
            self.return_cost +
            self.other_fees
        )
        self.gross_profit = self.selling_price - self.product_cost - self.shipping_cost - self.fba_fulfillment_fee - self.referral_fee
        self.net_profit = self.selling_price - self.total_cost
        self.gross_margin = self.gross_profit / self.selling_price if self.selling_price > 0 else 0
        self.net_margin = self.net_profit / self.selling_price if self.selling_price > 0 else 0


@dataclass
class BreakEvenAnalysis:
    """Break-even analysis"""
    min_price: float              # Minimum price (break-even)
    break_even_units: int         # Break-even units
    safety_margin: float          # Safety margin
    current_margin_above_min: float  # Current price above minimum


@dataclass
class PricingSuggestion:
    """Pricing recommendation"""
    target_margin: float          # Target profit margin
    suggested_price: float        # Suggested price
    profit_per_unit: float        # Profit per unit


@dataclass
class AnalysisResult:
    """Complete analysis result"""
    product: ProductInput
    cost_breakdown: CostBreakdown
    break_even: BreakEvenAnalysis
    pricing_suggestions: List[PricingSuggestion]
    status: ProfitStatus
    summary: str


# ============================================================
# Core Calculation Functions
# ============================================================

def get_referral_fee_rate(category: str, custom_rate: Optional[float] = None) -> float:
    """Get Referral Fee rate"""
    if custom_rate is not None:
        return custom_rate
    return REFERRAL_FEE_RATES.get(category.lower(), REFERRAL_FEE_RATES["default"])


def calculate_costs(product: ProductInput) -> CostBreakdown:
    """Calculate cost breakdown"""
    # Referral Fee
    referral_rate = get_referral_fee_rate(product.category, product.referral_fee_rate)
    referral_fee = product.selling_price * referral_rate
    
    # Ad cost
    ad_cost = product.selling_price * product.ad_spend_ratio
    
    # Return cost = return rate × (processing fee + product cost loss ratio)
    return_cost = product.return_rate * (product.return_processing_fee + product.product_cost * 0.5)
    
    return CostBreakdown(
        selling_price=product.selling_price,
        product_cost=product.product_cost,
        shipping_cost=product.shipping_cost,
        fba_fulfillment_fee=product.fba_fulfillment_fee,
        fba_storage_fee=product.fba_storage_fee,
        referral_fee=round(referral_fee, 2),
        ad_cost=round(ad_cost, 2),
        return_cost=round(return_cost, 2),
        other_fees=product.other_fees
    )


def calculate_break_even(product: ProductInput, costs: CostBreakdown) -> BreakEvenAnalysis:
    """Calculate break-even point"""
    # Variable cost (per unit)
    variable_cost = (
        product.product_cost +
        product.shipping_cost +
        product.fba_fulfillment_fee +
        product.fba_storage_fee +
        costs.referral_fee +
        costs.return_cost +
        product.other_fees
    )
    
    # Minimum price (cover variable cost + ad spend)
    # Ad ratio unchanged: min_price - variable_cost - min_price * ad_ratio = 0
    # min_price * (1 - ad_ratio) = variable_cost
    if product.ad_spend_ratio < 1:
        min_price = variable_cost / (1 - product.ad_spend_ratio)
    else:
        min_price = variable_cost * 2  # Abnormal case
    
    # Break-even units (if fixed costs exist)
    if product.fixed_costs > 0 and costs.net_profit > 0:
        break_even_units = int(product.fixed_costs / costs.net_profit) + 1
    else:
        break_even_units = 0
    
    # Safety margin
    safety_margin = (product.selling_price - min_price) / product.selling_price if product.selling_price > 0 else 0
    margin_above_min = (product.selling_price - min_price) / min_price if min_price > 0 else 0
    
    return BreakEvenAnalysis(
        min_price=round(min_price, 2),
        break_even_units=break_even_units,
        safety_margin=round(safety_margin, 4),
        current_margin_above_min=round(margin_above_min, 4)
    )


def calculate_pricing_suggestions(product: ProductInput, target_margins: List[float] = None) -> List[PricingSuggestion]:
    """Calculate pricing recommendations"""
    if target_margins is None:
        target_margins = [0.15, 0.20, 0.25, 0.30]
    
    suggestions = []
    
    # Base cost (excluding Referral Fee and ad cost as they're % of price)
    base_cost = (
        product.product_cost +
        product.shipping_cost +
        product.fba_fulfillment_fee +
        product.fba_storage_fee +
        product.other_fees +
        product.return_rate * product.return_processing_fee
    )
    
    referral_rate = get_referral_fee_rate(product.category, product.referral_fee_rate)
    
    for target_margin in target_margins:
        # Target: net_profit / selling_price = target_margin
        # net_profit = selling_price - base_cost - selling_price * referral_rate - selling_price * ad_ratio
        # selling_price * target_margin = selling_price - base_cost - selling_price * (referral_rate + ad_ratio)
        # selling_price * (target_margin + referral_rate + ad_ratio - 1) = -base_cost
        # selling_price = base_cost / (1 - target_margin - referral_rate - ad_ratio)
        
        denominator = 1 - target_margin - referral_rate - product.ad_spend_ratio
        if denominator > 0:
            suggested_price = base_cost / denominator
            profit_per_unit = suggested_price * target_margin
            
            suggestions.append(PricingSuggestion(
                target_margin=target_margin,
                suggested_price=round(suggested_price, 2),
                profit_per_unit=round(profit_per_unit, 2)
            ))
    
    return suggestions


def evaluate_profit_status(net_margin: float) -> ProfitStatus:
    """Evaluate profit status"""
    if net_margin < 0:
        return ProfitStatus.LOSS
    elif net_margin < PROFIT_THRESHOLDS["warning"]:
        return ProfitStatus.DANGER
    elif net_margin < PROFIT_THRESHOLDS["healthy"]:
        return ProfitStatus.WARNING
    else:
        return ProfitStatus.HEALTHY


def analyze_product(product: ProductInput, target_margins: List[float] = None) -> AnalysisResult:
    """Analyze single product"""
    costs = calculate_costs(product)
    break_even = calculate_break_even(product, costs)
    pricing = calculate_pricing_suggestions(product, target_margins)
    status = evaluate_profit_status(costs.net_margin)
    
    # Generate summary
    status_text = {
        ProfitStatus.HEALTHY: "✅ Healthy",
        ProfitStatus.WARNING: "⚠️ Warning",
        ProfitStatus.DANGER: "🔴 Danger",
        ProfitStatus.LOSS: "💀 Loss",
    }
    summary = f"{status_text[status]} | Net Margin {costs.net_margin*100:.1f}% | Profit/Unit .2f"
    
    return AnalysisResult(
        product=product,
        cost_breakdown=costs,
        break_even=break_even,
        pricing_suggestions=pricing,
        status=status,
        summary=summary
    )


def analyze_batch(products: List[ProductInput], target_margins: List[float] = None) -> List[AnalysisResult]:
    """Batch analysis"""
    return [analyze_product(p, target_margins) for p in products]


# ============================================================
# Output Formatting
# ============================================================

def format_cost_breakdown(costs: CostBreakdown) -> str:
    """Format cost breakdown"""
    def pct(val):
        return f"{val/costs.selling_price*100:.1f}%" if costs.selling_price > 0 else "0%"
    
    lines = [
        f"Selling Price         .2f   100%",
        "─" * 40,
        f"Product Cost          -.2f    {pct(costs.product_cost)}",
        f"Inbound Shipping      -.2f    {pct(costs.shipping_cost)}",
        f"FBA Fulfillment       -.2f    {pct(costs.fba_fulfillment_fee)}",
        f"FBA Storage           -.2f    {pct(costs.fba_storage_fee)}",
        f"Referral Fee          -.2f    {pct(costs.referral_fee)}",
        f"Advertising           -.2f    {pct(costs.ad_cost)}",
        f"Returns               -.2f    {pct(costs.return_cost)}",
        f"Other Fees            -.2f    {pct(costs.other_fees)}",
        "─" * 40,
        f"Total Cost            .2f    {pct(costs.total_cost)}",
        f"Net Profit            .2f    {costs.net_margin*100:.1f}%",
    ]
    return "\n".join(lines)


def format_break_even(be: BreakEvenAnalysis, current_price: float) -> str:
    """Format break-even analysis"""
    lines = [
        f"Break-even Price: .2f",
        f"├── Below this price = Loss",
        f"",
        f"Current Price: .2f",
        f"├── {be.current_margin_above_min*100:.1f}% above break-even",
        f"",
        f"Safety Margin: {be.safety_margin*100:.1f}%",
        f"├── Room for price reduction",
    ]
    if be.break_even_units > 0:
        lines.extend([
            f"",
            f"Break-even Units: {be.break_even_units}",
            f"├── Units needed to cover fixed costs",
        ])
    return "\n".join(lines)


def format_pricing_suggestions(suggestions: List[PricingSuggestion], current_price: float, current_margin: float) -> str:
    """Format pricing recommendations"""
    lines = [
        "| Target Margin | Recommended Price | Profit/Unit |",
        "|---------------|-------------------|-------------|",
    ]
    for s in suggestions:
        lines.append(f"| {s.target_margin*100:.0f}% | .2f | .2f |")
    
    lines.append(f"\nCurrent Price .2f → Net Margin {current_margin*100:.1f}%")
    return "\n".join(lines)


def format_full_report(result: AnalysisResult) -> str:
    """Generate full report"""
    status_icons = {
        ProfitStatus.HEALTHY: "✅",
        ProfitStatus.WARNING: "⚠️",
        ProfitStatus.DANGER: "🔴",
        ProfitStatus.LOSS: "💀",
    }
    
    report = f"""
💰 **Amazon Profit Analysis Report**

**Product**: {result.product.name} ({result.product.sku})
**Status**: {status_icons[result.status]} {result.summary}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 **Cost Breakdown**

```
{format_cost_breakdown(result.cost_breakdown)}
```

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📈 **Break-Even Analysis**

{format_break_even(result.break_even, result.product.selling_price)}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💡 **Pricing Recommendations**

{format_pricing_suggestions(result.pricing_suggestions, result.product.selling_price, result.cost_breakdown.net_margin)}

"""
    return report


def format_batch_summary(results: List[AnalysisResult]) -> str:
    """Format batch analysis summary"""
    status_icons = {
        ProfitStatus.HEALTHY: "✅",
        ProfitStatus.WARNING: "⚠️",
        ProfitStatus.DANGER: "🔴",
        ProfitStatus.LOSS: "💀",
    }
    
    lines = [
        "📊 **Batch Analysis Summary**",
        "",
        "| SKU | Price | Total Cost | Net Profit | Margin | Status |",
        "|-----|-------|------------|------------|--------|--------|",
    ]
    
    total_profit = 0
    for r in results:
        c = r.cost_breakdown
        icon = status_icons[r.status]
        lines.append(f"| {r.product.sku} | .2f | .2f | .2f | {c.net_margin*100:.1f}% | {icon} |")
        total_profit += c.net_profit
    
    lines.append("")
    lines.append(f"**Total**: {len(results)} SKUs | Avg Profit/Unit .2f")
    
    # Statistics
    healthy = sum(1 for r in results if r.status == ProfitStatus.HEALTHY)
    warning = sum(1 for r in results if r.status == ProfitStatus.WARNING)
    danger = sum(1 for r in results if r.status == ProfitStatus.DANGER)
    loss = sum(1 for r in results if r.status == ProfitStatus.LOSS)
    
    lines.append(f"**Status Distribution**: ✅ {healthy} | ⚠️ {warning} | 🔴 {danger} | 💀 {loss}")
    
    return "\n".join(lines)


# ============================================================
# CSV Batch Processing
# ============================================================

def parse_csv(csv_content: str) -> List[ProductInput]:
    """Parse CSV content"""
    products = []
    reader = csv.DictReader(csv_content.strip().split('\n'))
    
    for row in reader:
        product = ProductInput(
            sku=row.get('sku', 'SKU'),
            name=row.get('name', 'Product'),
            selling_price=float(row.get('selling_price', 0)),
            product_cost=float(row.get('product_cost', 0)),
            shipping_cost=float(row.get('shipping_cost', 0)),
            fba_fulfillment_fee=float(row.get('fba_fee', 0)),
            fba_storage_fee=float(row.get('storage_fee', 0)),
            ad_spend_ratio=float(row.get('ad_ratio', 0)),
            return_rate=float(row.get('return_rate', 0)),
            return_processing_fee=float(row.get('return_fee', 0)),
            other_fees=float(row.get('other_fees', 0)),
            category=row.get('category', 'default'),
        )
        products.append(product)
    
    return products


# ============================================================
# CLI Entry Point
# ============================================================

def main():
    """Command line entry"""
    # Default test data
    test_product = ProductInput(
        sku="TEST001",
        name="Kitchen Gadget",
        selling_price=29.99,
        product_cost=6.00,
        shipping_cost=1.50,
        fba_fulfillment_fee=5.50,
        fba_storage_fee=0.30,
        ad_spend_ratio=0.10,
        return_rate=0.03,
        return_processing_fee=2.00,
        other_fees=0.50,
        category="kitchen",
    )
    
    # If JSON input provided
    if len(sys.argv) > 1:
        try:
            input_data = json.loads(sys.argv[1])
            if isinstance(input_data, list):
                # Batch mode
                products = [ProductInput(**p) for p in input_data]
                results = analyze_batch(products)
                print(format_batch_summary(results))
                return
            else:
                test_product = ProductInput(**input_data)
        except Exception as e:
            print(f"Error: {e}")
            sys.exit(1)
    
    # Single product analysis
    result = analyze_product(test_product)
    print(format_full_report(result))


if __name__ == "__main__":
    main()

Profit Margin Calculator Tiktok

Skill

TikTok Shop profit margin calculator for sellers. Calculate cost breakdowns including affiliate commissions, platform fees, and FBT costs. Includes return ra...

---
name: profit-margin-calculator-tiktok
version: 1.0.0
description: "TikTok Shop profit margin calculator for sellers. Calculate cost breakdowns including affiliate commissions, platform fees, and FBT costs. Includes return rate analysis for impulse buying patterns. No API key required."
metadata: {"nexscope":{"emoji":"💰","category":"ecommerce"}}
---

# Profit Margin Calculator — TikTok Shop 💰

Calculate product profitability for TikTok Shop sellers — cost breakdowns, profit margins, and affiliate commission analysis.

## Installation

```bash
npx skills add nexscope-ai/eCommerce-Skills --skill profit-margin-calculator-tiktok -g
```

## Cost Components

| Cost Item | Description | Notes |
|-----------|-------------|-------|
| Product Cost | FOB purchase price | - |
| Inbound Shipping | To FBT warehouse | - |
| FBT Fulfillment | Fulfillment by TikTok | Optional |
| **Platform Fee** | 5% | Lower ✅ |
| **Affiliate Commission** | 10-30% | Main cost ⚠️ |
| Advertising | TikTok Ads | - |
| Return Cost | Higher return rate | 5-15% |

## TikTok Characteristics

- **Low platform fee**: Only 5%
- **High affiliate commission**: 10-30%, main cost driver
- **High return rate**: Impulse buying, 5-15% returns
- **Short viral cycle**: Need fast inventory turnover

## Usage

```bash
python3 scripts/calculator.py

python3 scripts/calculator.py '{"selling_price": 19.99, "creator_commission_rate": 0.15, "product_cost": 5}'
```

## Output Example

```
💰 **TikTok Shop Profit Analysis Report**

Selling Price         $19.99   100.0%
────────────────────────────────────────
Product Cost          -$5.00    25.0%
FBT Fulfillment       -$3.50    17.5%
Platform Fee (5%)     -$1.00     5.0%
Affiliate Commission  -$3.00    15.0%  ⬅️ Main cost
...
────────────────────────────────────────
Net Profit            $4.54    22.7%
```

## TikTok Fee Structure

| Fee Type | Rate | Notes |
|----------|------|-------|
| Platform Fee | 5% | Lower than Amazon |
| Affiliate Commission | 10-30% | Varies by influencer tier |
| FBT Fulfillment | ~$3-5/order | Similar to FBA |
| Return Processing | ~$2-3/return | Higher return rate |

## Key Considerations

1. **Affiliate costs are variable** — Top influencers demand higher rates
2. **Plan for returns** — Budget 5-15% return rate
3. **Fast turnover needed** — Viral products have short cycles
4. **Lower platform fees** — 5% vs Amazon's 8-15%

## vs Amazon

| Item | Amazon | TikTok |
|------|--------|--------|
| Platform fee | 8-15% | 5% |
| Affiliate | N/A | 10-30% |
| Return rate | 5-10% | 5-15% |
| Traffic | Search | Content |

---

**Part of [Nexscope AI](https://www.nexscope.ai/) — AI tools for e-commerce sellers.**

FILE:scripts/calculator.py
#!/usr/bin/env python3
"""
Amazon Profit Calculator - Core Engine

Features:
- Cost breakdown calculation
- Profit margin calculation (gross/net)
- Break-even analysis
- Pricing recommendations
- Batch calculation support

Version: 1.0.0
"""

import json
import csv
from dataclasses import dataclass, field
from typing import List, Dict, Optional
from enum import Enum
import sys


class ProfitStatus(Enum):
    HEALTHY = "healthy"      # >20% net margin
    WARNING = "warning"      # 5-20% net margin
    DANGER = "danger"        # <5% net margin
    LOSS = "loss"            # Negative margin


# ============================================================
# Amazon Referral Fee Rates (by category)
# ============================================================

REFERRAL_FEE_RATES = {
    # Category: Rate
    "default": 0.15,
    "electronics": 0.08,
    "computers": 0.08,
    "camera": 0.08,
    "video_games": 0.15,
    "books": 0.15,
    "clothing": 0.17,
    "shoes": 0.15,
    "jewelry": 0.20,
    "watches": 0.15,
    "furniture": 0.15,
    "home": 0.15,
    "kitchen": 0.15,
    "beauty": 0.15,
    "health": 0.15,
    "grocery": 0.15,
    "pet": 0.15,
    "toys": 0.15,
    "baby": 0.15,
    "sports": 0.15,
    "outdoors": 0.15,
    "automotive": 0.12,
    "industrial": 0.12,
    "office": 0.15,
}

# FBA Fulfillment Fee Reference (simplified, based on size tier)
FBA_FULFILLMENT_FEES = {
    "small_standard": 3.22,      # Small standard (<1lb)
    "large_standard_1lb": 4.75,  # Large standard (<1lb)
    "large_standard_2lb": 5.40,  # Large standard (1-2lb)
    "large_standard_3lb": 6.10,  # Large standard (2-3lb)
    "small_oversize": 9.73,      # Small oversize
    "medium_oversize": 19.05,    # Medium oversize
    "large_oversize": 89.98,     # Large oversize
}

# Profit margin thresholds
PROFIT_THRESHOLDS = {
    "healthy": 0.20,    # >20%
    "warning": 0.05,    # 5-20%
    "danger": 0.00,     # 0-5%
}


# ============================================================
# Data Structures
# ============================================================

@dataclass
class ProductInput:
    """Single product input data"""
    sku: str = "SKU001"
    name: str = "Product"
    
    # Selling price
    selling_price: float = 0.0
    
    # Cost items
    product_cost: float = 0.0           # Product cost (FOB)
    shipping_cost: float = 0.0          # Inbound shipping
    fba_fulfillment_fee: float = 0.0    # FBA fulfillment fee
    fba_storage_fee: float = 0.0        # FBA storage fee (monthly avg)
    
    # Optional costs
    ad_spend_ratio: float = 0.0         # Ad spend ratio (0-1)
    return_rate: float = 0.0            # Return rate (0-1)
    return_processing_fee: float = 0.0  # Return processing fee per unit
    other_fees: float = 0.0             # Other fees
    
    # Platform related
    category: str = "default"           # Category (for Referral Fee)
    referral_fee_rate: Optional[float] = None  # Custom commission rate
    
    # For batch calculation
    monthly_sales: int = 0              # Monthly sales (for fixed cost allocation)
    fixed_costs: float = 0.0            # Fixed costs (for break-even)


@dataclass
class CostBreakdown:
    """Cost breakdown"""
    selling_price: float
    product_cost: float
    shipping_cost: float
    fba_fulfillment_fee: float
    fba_storage_fee: float
    referral_fee: float
    ad_cost: float
    return_cost: float
    other_fees: float
    
    total_cost: float = 0.0
    gross_profit: float = 0.0
    net_profit: float = 0.0
    gross_margin: float = 0.0
    net_margin: float = 0.0
    
    def __post_init__(self):
        self.total_cost = (
            self.product_cost +
            self.shipping_cost +
            self.fba_fulfillment_fee +
            self.fba_storage_fee +
            self.referral_fee +
            self.ad_cost +
            self.return_cost +
            self.other_fees
        )
        self.gross_profit = self.selling_price - self.product_cost - self.shipping_cost - self.fba_fulfillment_fee - self.referral_fee
        self.net_profit = self.selling_price - self.total_cost
        self.gross_margin = self.gross_profit / self.selling_price if self.selling_price > 0 else 0
        self.net_margin = self.net_profit / self.selling_price if self.selling_price > 0 else 0


@dataclass
class BreakEvenAnalysis:
    """Break-even analysis"""
    min_price: float              # Minimum price (break-even)
    break_even_units: int         # Break-even units
    safety_margin: float          # Safety margin
    current_margin_above_min: float  # Current price above minimum


@dataclass
class PricingSuggestion:
    """Pricing recommendation"""
    target_margin: float          # Target profit margin
    suggested_price: float        # Suggested price
    profit_per_unit: float        # Profit per unit


@dataclass
class AnalysisResult:
    """Complete analysis result"""
    product: ProductInput
    cost_breakdown: CostBreakdown
    break_even: BreakEvenAnalysis
    pricing_suggestions: List[PricingSuggestion]
    status: ProfitStatus
    summary: str


# ============================================================
# Core Calculation Functions
# ============================================================

def get_referral_fee_rate(category: str, custom_rate: Optional[float] = None) -> float:
    """Get Referral Fee rate"""
    if custom_rate is not None:
        return custom_rate
    return REFERRAL_FEE_RATES.get(category.lower(), REFERRAL_FEE_RATES["default"])


def calculate_costs(product: ProductInput) -> CostBreakdown:
    """Calculate cost breakdown"""
    # Referral Fee
    referral_rate = get_referral_fee_rate(product.category, product.referral_fee_rate)
    referral_fee = product.selling_price * referral_rate
    
    # Ad cost
    ad_cost = product.selling_price * product.ad_spend_ratio
    
    # Return cost = return rate × (processing fee + product cost loss ratio)
    return_cost = product.return_rate * (product.return_processing_fee + product.product_cost * 0.5)
    
    return CostBreakdown(
        selling_price=product.selling_price,
        product_cost=product.product_cost,
        shipping_cost=product.shipping_cost,
        fba_fulfillment_fee=product.fba_fulfillment_fee,
        fba_storage_fee=product.fba_storage_fee,
        referral_fee=round(referral_fee, 2),
        ad_cost=round(ad_cost, 2),
        return_cost=round(return_cost, 2),
        other_fees=product.other_fees
    )


def calculate_break_even(product: ProductInput, costs: CostBreakdown) -> BreakEvenAnalysis:
    """Calculate break-even point"""
    # Variable cost (per unit)
    variable_cost = (
        product.product_cost +
        product.shipping_cost +
        product.fba_fulfillment_fee +
        product.fba_storage_fee +
        costs.referral_fee +
        costs.return_cost +
        product.other_fees
    )
    
    # Minimum price (cover variable cost + ad spend)
    # Ad ratio unchanged: min_price - variable_cost - min_price * ad_ratio = 0
    # min_price * (1 - ad_ratio) = variable_cost
    if product.ad_spend_ratio < 1:
        min_price = variable_cost / (1 - product.ad_spend_ratio)
    else:
        min_price = variable_cost * 2  # Abnormal case
    
    # Break-even units (if fixed costs exist)
    if product.fixed_costs > 0 and costs.net_profit > 0:
        break_even_units = int(product.fixed_costs / costs.net_profit) + 1
    else:
        break_even_units = 0
    
    # Safety margin
    safety_margin = (product.selling_price - min_price) / product.selling_price if product.selling_price > 0 else 0
    margin_above_min = (product.selling_price - min_price) / min_price if min_price > 0 else 0
    
    return BreakEvenAnalysis(
        min_price=round(min_price, 2),
        break_even_units=break_even_units,
        safety_margin=round(safety_margin, 4),
        current_margin_above_min=round(margin_above_min, 4)
    )


def calculate_pricing_suggestions(product: ProductInput, target_margins: List[float] = None) -> List[PricingSuggestion]:
    """Calculate pricing recommendations"""
    if target_margins is None:
        target_margins = [0.15, 0.20, 0.25, 0.30]
    
    suggestions = []
    
    # Base cost (excluding Referral Fee and ad cost as they're % of price)
    base_cost = (
        product.product_cost +
        product.shipping_cost +
        product.fba_fulfillment_fee +
        product.fba_storage_fee +
        product.other_fees +
        product.return_rate * product.return_processing_fee
    )
    
    referral_rate = get_referral_fee_rate(product.category, product.referral_fee_rate)
    
    for target_margin in target_margins:
        # Target: net_profit / selling_price = target_margin
        # net_profit = selling_price - base_cost - selling_price * referral_rate - selling_price * ad_ratio
        # selling_price * target_margin = selling_price - base_cost - selling_price * (referral_rate + ad_ratio)
        # selling_price * (target_margin + referral_rate + ad_ratio - 1) = -base_cost
        # selling_price = base_cost / (1 - target_margin - referral_rate - ad_ratio)
        
        denominator = 1 - target_margin - referral_rate - product.ad_spend_ratio
        if denominator > 0:
            suggested_price = base_cost / denominator
            profit_per_unit = suggested_price * target_margin
            
            suggestions.append(PricingSuggestion(
                target_margin=target_margin,
                suggested_price=round(suggested_price, 2),
                profit_per_unit=round(profit_per_unit, 2)
            ))
    
    return suggestions


def evaluate_profit_status(net_margin: float) -> ProfitStatus:
    """Evaluate profit status"""
    if net_margin < 0:
        return ProfitStatus.LOSS
    elif net_margin < PROFIT_THRESHOLDS["warning"]:
        return ProfitStatus.DANGER
    elif net_margin < PROFIT_THRESHOLDS["healthy"]:
        return ProfitStatus.WARNING
    else:
        return ProfitStatus.HEALTHY


def analyze_product(product: ProductInput, target_margins: List[float] = None) -> AnalysisResult:
    """Analyze single product"""
    costs = calculate_costs(product)
    break_even = calculate_break_even(product, costs)
    pricing = calculate_pricing_suggestions(product, target_margins)
    status = evaluate_profit_status(costs.net_margin)
    
    # Generate summary
    status_text = {
        ProfitStatus.HEALTHY: "✅ Healthy",
        ProfitStatus.WARNING: "⚠️ Warning",
        ProfitStatus.DANGER: "🔴 Danger",
        ProfitStatus.LOSS: "💀 Loss",
    }
    summary = f"{status_text[status]} | Net Margin {costs.net_margin*100:.1f}% | Profit/Unit .2f"
    
    return AnalysisResult(
        product=product,
        cost_breakdown=costs,
        break_even=break_even,
        pricing_suggestions=pricing,
        status=status,
        summary=summary
    )


def analyze_batch(products: List[ProductInput], target_margins: List[float] = None) -> List[AnalysisResult]:
    """Batch analysis"""
    return [analyze_product(p, target_margins) for p in products]


# ============================================================
# Output Formatting
# ============================================================

def format_cost_breakdown(costs: CostBreakdown) -> str:
    """Format cost breakdown"""
    def pct(val):
        return f"{val/costs.selling_price*100:.1f}%" if costs.selling_price > 0 else "0%"
    
    lines = [
        f"Selling Price         .2f   100%",
        "─" * 40,
        f"Product Cost          -.2f    {pct(costs.product_cost)}",
        f"Inbound Shipping      -.2f    {pct(costs.shipping_cost)}",
        f"FBA Fulfillment       -.2f    {pct(costs.fba_fulfillment_fee)}",
        f"FBA Storage           -.2f    {pct(costs.fba_storage_fee)}",
        f"Referral Fee          -.2f    {pct(costs.referral_fee)}",
        f"Advertising           -.2f    {pct(costs.ad_cost)}",
        f"Returns               -.2f    {pct(costs.return_cost)}",
        f"Other Fees            -.2f    {pct(costs.other_fees)}",
        "─" * 40,
        f"Total Cost            .2f    {pct(costs.total_cost)}",
        f"Net Profit            .2f    {costs.net_margin*100:.1f}%",
    ]
    return "\n".join(lines)


def format_break_even(be: BreakEvenAnalysis, current_price: float) -> str:
    """Format break-even analysis"""
    lines = [
        f"Break-even Price: .2f",
        f"├── Below this price = Loss",
        f"",
        f"Current Price: .2f",
        f"├── {be.current_margin_above_min*100:.1f}% above break-even",
        f"",
        f"Safety Margin: {be.safety_margin*100:.1f}%",
        f"├── Room for price reduction",
    ]
    if be.break_even_units > 0:
        lines.extend([
            f"",
            f"Break-even Units: {be.break_even_units}",
            f"├── Units needed to cover fixed costs",
        ])
    return "\n".join(lines)


def format_pricing_suggestions(suggestions: List[PricingSuggestion], current_price: float, current_margin: float) -> str:
    """Format pricing recommendations"""
    lines = [
        "| Target Margin | Recommended Price | Profit/Unit |",
        "|---------------|-------------------|-------------|",
    ]
    for s in suggestions:
        lines.append(f"| {s.target_margin*100:.0f}% | .2f | .2f |")
    
    lines.append(f"\nCurrent Price .2f → Net Margin {current_margin*100:.1f}%")
    return "\n".join(lines)


def format_full_report(result: AnalysisResult) -> str:
    """Generate full report"""
    status_icons = {
        ProfitStatus.HEALTHY: "✅",
        ProfitStatus.WARNING: "⚠️",
        ProfitStatus.DANGER: "🔴",
        ProfitStatus.LOSS: "💀",
    }
    
    report = f"""
💰 **Amazon Profit Analysis Report**

**Product**: {result.product.name} ({result.product.sku})
**Status**: {status_icons[result.status]} {result.summary}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 **Cost Breakdown**

```
{format_cost_breakdown(result.cost_breakdown)}
```

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📈 **Break-Even Analysis**

{format_break_even(result.break_even, result.product.selling_price)}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💡 **Pricing Recommendations**

{format_pricing_suggestions(result.pricing_suggestions, result.product.selling_price, result.cost_breakdown.net_margin)}

"""
    return report


def format_batch_summary(results: List[AnalysisResult]) -> str:
    """Format batch analysis summary"""
    status_icons = {
        ProfitStatus.HEALTHY: "✅",
        ProfitStatus.WARNING: "⚠️",
        ProfitStatus.DANGER: "🔴",
        ProfitStatus.LOSS: "💀",
    }
    
    lines = [
        "📊 **Batch Analysis Summary**",
        "",
        "| SKU | Price | Total Cost | Net Profit | Margin | Status |",
        "|-----|-------|------------|------------|--------|--------|",
    ]
    
    total_profit = 0
    for r in results:
        c = r.cost_breakdown
        icon = status_icons[r.status]
        lines.append(f"| {r.product.sku} | .2f | .2f | .2f | {c.net_margin*100:.1f}% | {icon} |")
        total_profit += c.net_profit
    
    lines.append("")
    lines.append(f"**Total**: {len(results)} SKUs | Avg Profit/Unit .2f")
    
    # Statistics
    healthy = sum(1 for r in results if r.status == ProfitStatus.HEALTHY)
    warning = sum(1 for r in results if r.status == ProfitStatus.WARNING)
    danger = sum(1 for r in results if r.status == ProfitStatus.DANGER)
    loss = sum(1 for r in results if r.status == ProfitStatus.LOSS)
    
    lines.append(f"**Status Distribution**: ✅ {healthy} | ⚠️ {warning} | 🔴 {danger} | 💀 {loss}")
    
    return "\n".join(lines)


# ============================================================
# CSV Batch Processing
# ============================================================

def parse_csv(csv_content: str) -> List[ProductInput]:
    """Parse CSV content"""
    products = []
    reader = csv.DictReader(csv_content.strip().split('\n'))
    
    for row in reader:
        product = ProductInput(
            sku=row.get('sku', 'SKU'),
            name=row.get('name', 'Product'),
            selling_price=float(row.get('selling_price', 0)),
            product_cost=float(row.get('product_cost', 0)),
            shipping_cost=float(row.get('shipping_cost', 0)),
            fba_fulfillment_fee=float(row.get('fba_fee', 0)),
            fba_storage_fee=float(row.get('storage_fee', 0)),
            ad_spend_ratio=float(row.get('ad_ratio', 0)),
            return_rate=float(row.get('return_rate', 0)),
            return_processing_fee=float(row.get('return_fee', 0)),
            other_fees=float(row.get('other_fees', 0)),
            category=row.get('category', 'default'),
        )
        products.append(product)
    
    return products


# ============================================================
# CLI Entry Point
# ============================================================

def main():
    """Command line entry"""
    # Default test data
    test_product = ProductInput(
        sku="TEST001",
        name="Kitchen Gadget",
        selling_price=29.99,
        product_cost=6.00,
        shipping_cost=1.50,
        fba_fulfillment_fee=5.50,
        fba_storage_fee=0.30,
        ad_spend_ratio=0.10,
        return_rate=0.03,
        return_processing_fee=2.00,
        other_fees=0.50,
        category="kitchen",
    )
    
    # If JSON input provided
    if len(sys.argv) > 1:
        try:
            input_data = json.loads(sys.argv[1])
            if isinstance(input_data, list):
                # Batch mode
                products = [ProductInput(**p) for p in input_data]
                results = analyze_batch(products)
                print(format_batch_summary(results))
                return
            else:
                test_product = ProductInput(**input_data)
        except Exception as e:
            print(f"Error: {e}")
            sys.exit(1)
    
    # Single product analysis
    result = analyze_product(test_product)
    print(format_full_report(result))


if __name__ == "__main__":
    main()

Profit Margin Calculator Shopify

Skill

Shopify/DTC profit margin calculator for sellers. Calculate cost breakdowns including ad spend, CAC, payment processing fees, and 3PL costs. Includes LTV/CAC...

---
name: profit-margin-calculator-shopify
version: 1.0.0
description: "Shopify/DTC profit margin calculator for sellers. Calculate cost breakdowns including ad spend, CAC, payment processing fees, and 3PL costs. Includes LTV/CAC analysis and DTC-specific benchmarks. No API key required."
metadata: {"nexscope":{"emoji":"💰","category":"ecommerce"}}
---

# Profit Margin Calculator — Shopify/DTC 💰

Calculate product profitability for Shopify and DTC stores — cost breakdowns, profit margins, and CAC/LTV analysis.

## Installation

```bash
npx skills add nexscope-ai/eCommerce-Skills --skill profit-margin-calculator-shopify -g
```

## Cost Components

| Cost Item | Description | Notes |
|-----------|-------------|-------|
| Product Cost | FOB purchase price | - |
| Inbound Shipping | To 3PL warehouse | - |
| 3PL Fulfillment | ShipBob/Deliverr etc. | - |
| **Payment Processing** | 2.9% + $0.30 | Shopify Payments |
| **Advertising** | 20-40% | Main cost ⚠️ |
| Return Cost | Return processing | - |
| Customer Shipping | If free shipping offered | Optional |

## DTC Characteristics

- **No platform commission**: Only payment processing fees
- **High ad spend ratio**: 20-40%, main cost driver
- **Requires high margins**: 60%+ gross margin to support ads
- **Focus on LTV/CAC**: Recommended >3

## Key Metrics

| Metric | Recommended |
|--------|-------------|
| Gross Margin | >60% |
| Net Margin | >20% |
| LTV/CAC | >3 |
| Repeat Rate | Higher = better |

## Usage

```bash
python3 scripts/calculator.py

python3 scripts/calculator.py '{"selling_price": 49.99, "ad_spend_ratio": 0.20, "product_cost": 12}'
```

## Output Example

```
💰 **Shopify/DTC Profit Analysis Report**

Selling Price         $49.99   100.0%
────────────────────────────────────────
Product Cost          -$12.00    24.0%
3PL Fulfillment       -$4.50     9.0%
Payment Processing    -$1.75     3.5%
Advertising           -$10.00    20.0%  ⬅️ Main cost
...
────────────────────────────────────────
Net Profit            $18.59    37.2%

💡 Max Affordable CAC: $10.00
```

## DTC Golden Ratios

```
DTC Health Formula:
├── Gross Margin > 60%
├── Ad Spend < 30%
├── Fulfillment < 15%
├── Net Margin > 15%
└── LTV/CAC > 3
```

## vs Amazon

| Item | Amazon | Shopify/DTC |
|------|--------|-------------|
| Platform fee | 8-15% | 0% |
| Payment fee | Included | 2.9% + $0.30 |
| Ad spend | 10-20% | 20-40% |
| Margin need | 40%+ | 60%+ |
| Traffic | Platform | Self-built |

---

**Part of [Nexscope AI](https://www.nexscope.ai/) — AI tools for e-commerce sellers.**


FILE:scripts/calculator.py
#!/usr/bin/env python3
"""
Amazon Profit Calculator - Core Engine

Features:
- Cost breakdown calculation
- Profit margin calculation (gross/net)
- Break-even analysis
- Pricing recommendations
- Batch calculation support

Version: 1.0.0
"""

import json
import csv
from dataclasses import dataclass, field
from typing import List, Dict, Optional
from enum import Enum
import sys


class ProfitStatus(Enum):
    HEALTHY = "healthy"      # >20% net margin
    WARNING = "warning"      # 5-20% net margin
    DANGER = "danger"        # <5% net margin
    LOSS = "loss"            # Negative margin


# ============================================================
# Amazon Referral Fee Rates (by category)
# ============================================================

REFERRAL_FEE_RATES = {
    # Category: Rate
    "default": 0.15,
    "electronics": 0.08,
    "computers": 0.08,
    "camera": 0.08,
    "video_games": 0.15,
    "books": 0.15,
    "clothing": 0.17,
    "shoes": 0.15,
    "jewelry": 0.20,
    "watches": 0.15,
    "furniture": 0.15,
    "home": 0.15,
    "kitchen": 0.15,
    "beauty": 0.15,
    "health": 0.15,
    "grocery": 0.15,
    "pet": 0.15,
    "toys": 0.15,
    "baby": 0.15,
    "sports": 0.15,
    "outdoors": 0.15,
    "automotive": 0.12,
    "industrial": 0.12,
    "office": 0.15,
}

# FBA Fulfillment Fee Reference (simplified, based on size tier)
FBA_FULFILLMENT_FEES = {
    "small_standard": 3.22,      # Small standard (<1lb)
    "large_standard_1lb": 4.75,  # Large standard (<1lb)
    "large_standard_2lb": 5.40,  # Large standard (1-2lb)
    "large_standard_3lb": 6.10,  # Large standard (2-3lb)
    "small_oversize": 9.73,      # Small oversize
    "medium_oversize": 19.05,    # Medium oversize
    "large_oversize": 89.98,     # Large oversize
}

# Profit margin thresholds
PROFIT_THRESHOLDS = {
    "healthy": 0.20,    # >20%
    "warning": 0.05,    # 5-20%
    "danger": 0.00,     # 0-5%
}


# ============================================================
# Data Structures
# ============================================================

@dataclass
class ProductInput:
    """Single product input data"""
    sku: str = "SKU001"
    name: str = "Product"
    
    # Selling price
    selling_price: float = 0.0
    
    # Cost items
    product_cost: float = 0.0           # Product cost (FOB)
    shipping_cost: float = 0.0          # Inbound shipping
    fba_fulfillment_fee: float = 0.0    # FBA fulfillment fee
    fba_storage_fee: float = 0.0        # FBA storage fee (monthly avg)
    
    # Optional costs
    ad_spend_ratio: float = 0.0         # Ad spend ratio (0-1)
    return_rate: float = 0.0            # Return rate (0-1)
    return_processing_fee: float = 0.0  # Return processing fee per unit
    other_fees: float = 0.0             # Other fees
    
    # Platform related
    category: str = "default"           # Category (for Referral Fee)
    referral_fee_rate: Optional[float] = None  # Custom commission rate
    
    # For batch calculation
    monthly_sales: int = 0              # Monthly sales (for fixed cost allocation)
    fixed_costs: float = 0.0            # Fixed costs (for break-even)


@dataclass
class CostBreakdown:
    """Cost breakdown"""
    selling_price: float
    product_cost: float
    shipping_cost: float
    fba_fulfillment_fee: float
    fba_storage_fee: float
    referral_fee: float
    ad_cost: float
    return_cost: float
    other_fees: float
    
    total_cost: float = 0.0
    gross_profit: float = 0.0
    net_profit: float = 0.0
    gross_margin: float = 0.0
    net_margin: float = 0.0
    
    def __post_init__(self):
        self.total_cost = (
            self.product_cost +
            self.shipping_cost +
            self.fba_fulfillment_fee +
            self.fba_storage_fee +
            self.referral_fee +
            self.ad_cost +
            self.return_cost +
            self.other_fees
        )
        self.gross_profit = self.selling_price - self.product_cost - self.shipping_cost - self.fba_fulfillment_fee - self.referral_fee
        self.net_profit = self.selling_price - self.total_cost
        self.gross_margin = self.gross_profit / self.selling_price if self.selling_price > 0 else 0
        self.net_margin = self.net_profit / self.selling_price if self.selling_price > 0 else 0


@dataclass
class BreakEvenAnalysis:
    """Break-even analysis"""
    min_price: float              # Minimum price (break-even)
    break_even_units: int         # Break-even units
    safety_margin: float          # Safety margin
    current_margin_above_min: float  # Current price above minimum


@dataclass
class PricingSuggestion:
    """Pricing recommendation"""
    target_margin: float          # Target profit margin
    suggested_price: float        # Suggested price
    profit_per_unit: float        # Profit per unit


@dataclass
class AnalysisResult:
    """Complete analysis result"""
    product: ProductInput
    cost_breakdown: CostBreakdown
    break_even: BreakEvenAnalysis
    pricing_suggestions: List[PricingSuggestion]
    status: ProfitStatus
    summary: str


# ============================================================
# Core Calculation Functions
# ============================================================

def get_referral_fee_rate(category: str, custom_rate: Optional[float] = None) -> float:
    """Get Referral Fee rate"""
    if custom_rate is not None:
        return custom_rate
    return REFERRAL_FEE_RATES.get(category.lower(), REFERRAL_FEE_RATES["default"])


def calculate_costs(product: ProductInput) -> CostBreakdown:
    """Calculate cost breakdown"""
    # Referral Fee
    referral_rate = get_referral_fee_rate(product.category, product.referral_fee_rate)
    referral_fee = product.selling_price * referral_rate
    
    # Ad cost
    ad_cost = product.selling_price * product.ad_spend_ratio
    
    # Return cost = return rate × (processing fee + product cost loss ratio)
    return_cost = product.return_rate * (product.return_processing_fee + product.product_cost * 0.5)
    
    return CostBreakdown(
        selling_price=product.selling_price,
        product_cost=product.product_cost,
        shipping_cost=product.shipping_cost,
        fba_fulfillment_fee=product.fba_fulfillment_fee,
        fba_storage_fee=product.fba_storage_fee,
        referral_fee=round(referral_fee, 2),
        ad_cost=round(ad_cost, 2),
        return_cost=round(return_cost, 2),
        other_fees=product.other_fees
    )


def calculate_break_even(product: ProductInput, costs: CostBreakdown) -> BreakEvenAnalysis:
    """Calculate break-even point"""
    # Variable cost (per unit)
    variable_cost = (
        product.product_cost +
        product.shipping_cost +
        product.fba_fulfillment_fee +
        product.fba_storage_fee +
        costs.referral_fee +
        costs.return_cost +
        product.other_fees
    )
    
    # Minimum price (cover variable cost + ad spend)
    # Ad ratio unchanged: min_price - variable_cost - min_price * ad_ratio = 0
    # min_price * (1 - ad_ratio) = variable_cost
    if product.ad_spend_ratio < 1:
        min_price = variable_cost / (1 - product.ad_spend_ratio)
    else:
        min_price = variable_cost * 2  # Abnormal case
    
    # Break-even units (if fixed costs exist)
    if product.fixed_costs > 0 and costs.net_profit > 0:
        break_even_units = int(product.fixed_costs / costs.net_profit) + 1
    else:
        break_even_units = 0
    
    # Safety margin
    safety_margin = (product.selling_price - min_price) / product.selling_price if product.selling_price > 0 else 0
    margin_above_min = (product.selling_price - min_price) / min_price if min_price > 0 else 0
    
    return BreakEvenAnalysis(
        min_price=round(min_price, 2),
        break_even_units=break_even_units,
        safety_margin=round(safety_margin, 4),
        current_margin_above_min=round(margin_above_min, 4)
    )


def calculate_pricing_suggestions(product: ProductInput, target_margins: List[float] = None) -> List[PricingSuggestion]:
    """Calculate pricing recommendations"""
    if target_margins is None:
        target_margins = [0.15, 0.20, 0.25, 0.30]
    
    suggestions = []
    
    # Base cost (excluding Referral Fee and ad cost as they're % of price)
    base_cost = (
        product.product_cost +
        product.shipping_cost +
        product.fba_fulfillment_fee +
        product.fba_storage_fee +
        product.other_fees +
        product.return_rate * product.return_processing_fee
    )
    
    referral_rate = get_referral_fee_rate(product.category, product.referral_fee_rate)
    
    for target_margin in target_margins:
        # Target: net_profit / selling_price = target_margin
        # net_profit = selling_price - base_cost - selling_price * referral_rate - selling_price * ad_ratio
        # selling_price * target_margin = selling_price - base_cost - selling_price * (referral_rate + ad_ratio)
        # selling_price * (target_margin + referral_rate + ad_ratio - 1) = -base_cost
        # selling_price = base_cost / (1 - target_margin - referral_rate - ad_ratio)
        
        denominator = 1 - target_margin - referral_rate - product.ad_spend_ratio
        if denominator > 0:
            suggested_price = base_cost / denominator
            profit_per_unit = suggested_price * target_margin
            
            suggestions.append(PricingSuggestion(
                target_margin=target_margin,
                suggested_price=round(suggested_price, 2),
                profit_per_unit=round(profit_per_unit, 2)
            ))
    
    return suggestions


def evaluate_profit_status(net_margin: float) -> ProfitStatus:
    """Evaluate profit status"""
    if net_margin < 0:
        return ProfitStatus.LOSS
    elif net_margin < PROFIT_THRESHOLDS["warning"]:
        return ProfitStatus.DANGER
    elif net_margin < PROFIT_THRESHOLDS["healthy"]:
        return ProfitStatus.WARNING
    else:
        return ProfitStatus.HEALTHY


def analyze_product(product: ProductInput, target_margins: List[float] = None) -> AnalysisResult:
    """Analyze single product"""
    costs = calculate_costs(product)
    break_even = calculate_break_even(product, costs)
    pricing = calculate_pricing_suggestions(product, target_margins)
    status = evaluate_profit_status(costs.net_margin)
    
    # Generate summary
    status_text = {
        ProfitStatus.HEALTHY: "✅ Healthy",
        ProfitStatus.WARNING: "⚠️ Warning",
        ProfitStatus.DANGER: "🔴 Danger",
        ProfitStatus.LOSS: "💀 Loss",
    }
    summary = f"{status_text[status]} | Net Margin {costs.net_margin*100:.1f}% | Profit/Unit .2f"
    
    return AnalysisResult(
        product=product,
        cost_breakdown=costs,
        break_even=break_even,
        pricing_suggestions=pricing,
        status=status,
        summary=summary
    )


def analyze_batch(products: List[ProductInput], target_margins: List[float] = None) -> List[AnalysisResult]:
    """Batch analysis"""
    return [analyze_product(p, target_margins) for p in products]


# ============================================================
# Output Formatting
# ============================================================

def format_cost_breakdown(costs: CostBreakdown) -> str:
    """Format cost breakdown"""
    def pct(val):
        return f"{val/costs.selling_price*100:.1f}%" if costs.selling_price > 0 else "0%"
    
    lines = [
        f"Selling Price         .2f   100%",
        "─" * 40,
        f"Product Cost          -.2f    {pct(costs.product_cost)}",
        f"Inbound Shipping      -.2f    {pct(costs.shipping_cost)}",
        f"FBA Fulfillment       -.2f    {pct(costs.fba_fulfillment_fee)}",
        f"FBA Storage           -.2f    {pct(costs.fba_storage_fee)}",
        f"Referral Fee          -.2f    {pct(costs.referral_fee)}",
        f"Advertising           -.2f    {pct(costs.ad_cost)}",
        f"Returns               -.2f    {pct(costs.return_cost)}",
        f"Other Fees            -.2f    {pct(costs.other_fees)}",
        "─" * 40,
        f"Total Cost            .2f    {pct(costs.total_cost)}",
        f"Net Profit            .2f    {costs.net_margin*100:.1f}%",
    ]
    return "\n".join(lines)


def format_break_even(be: BreakEvenAnalysis, current_price: float) -> str:
    """Format break-even analysis"""
    lines = [
        f"Break-even Price: .2f",
        f"├── Below this price = Loss",
        f"",
        f"Current Price: .2f",
        f"├── {be.current_margin_above_min*100:.1f}% above break-even",
        f"",
        f"Safety Margin: {be.safety_margin*100:.1f}%",
        f"├── Room for price reduction",
    ]
    if be.break_even_units > 0:
        lines.extend([
            f"",
            f"Break-even Units: {be.break_even_units}",
            f"├── Units needed to cover fixed costs",
        ])
    return "\n".join(lines)


def format_pricing_suggestions(suggestions: List[PricingSuggestion], current_price: float, current_margin: float) -> str:
    """Format pricing recommendations"""
    lines = [
        "| Target Margin | Recommended Price | Profit/Unit |",
        "|---------------|-------------------|-------------|",
    ]
    for s in suggestions:
        lines.append(f"| {s.target_margin*100:.0f}% | .2f | .2f |")
    
    lines.append(f"\nCurrent Price .2f → Net Margin {current_margin*100:.1f}%")
    return "\n".join(lines)


def format_full_report(result: AnalysisResult) -> str:
    """Generate full report"""
    status_icons = {
        ProfitStatus.HEALTHY: "✅",
        ProfitStatus.WARNING: "⚠️",
        ProfitStatus.DANGER: "🔴",
        ProfitStatus.LOSS: "💀",
    }
    
    report = f"""
💰 **Amazon Profit Analysis Report**

**Product**: {result.product.name} ({result.product.sku})
**Status**: {status_icons[result.status]} {result.summary}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 **Cost Breakdown**

```
{format_cost_breakdown(result.cost_breakdown)}
```

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📈 **Break-Even Analysis**

{format_break_even(result.break_even, result.product.selling_price)}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💡 **Pricing Recommendations**

{format_pricing_suggestions(result.pricing_suggestions, result.product.selling_price, result.cost_breakdown.net_margin)}

"""
    return report


def format_batch_summary(results: List[AnalysisResult]) -> str:
    """Format batch analysis summary"""
    status_icons = {
        ProfitStatus.HEALTHY: "✅",
        ProfitStatus.WARNING: "⚠️",
        ProfitStatus.DANGER: "🔴",
        ProfitStatus.LOSS: "💀",
    }
    
    lines = [
        "📊 **Batch Analysis Summary**",
        "",
        "| SKU | Price | Total Cost | Net Profit | Margin | Status |",
        "|-----|-------|------------|------------|--------|--------|",
    ]
    
    total_profit = 0
    for r in results:
        c = r.cost_breakdown
        icon = status_icons[r.status]
        lines.append(f"| {r.product.sku} | .2f | .2f | .2f | {c.net_margin*100:.1f}% | {icon} |")
        total_profit += c.net_profit
    
    lines.append("")
    lines.append(f"**Total**: {len(results)} SKUs | Avg Profit/Unit .2f")
    
    # Statistics
    healthy = sum(1 for r in results if r.status == ProfitStatus.HEALTHY)
    warning = sum(1 for r in results if r.status == ProfitStatus.WARNING)
    danger = sum(1 for r in results if r.status == ProfitStatus.DANGER)
    loss = sum(1 for r in results if r.status == ProfitStatus.LOSS)
    
    lines.append(f"**Status Distribution**: ✅ {healthy} | ⚠️ {warning} | 🔴 {danger} | 💀 {loss}")
    
    return "\n".join(lines)


# ============================================================
# CSV Batch Processing
# ============================================================

def parse_csv(csv_content: str) -> List[ProductInput]:
    """Parse CSV content"""
    products = []
    reader = csv.DictReader(csv_content.strip().split('\n'))
    
    for row in reader:
        product = ProductInput(
            sku=row.get('sku', 'SKU'),
            name=row.get('name', 'Product'),
            selling_price=float(row.get('selling_price', 0)),
            product_cost=float(row.get('product_cost', 0)),
            shipping_cost=float(row.get('shipping_cost', 0)),
            fba_fulfillment_fee=float(row.get('fba_fee', 0)),
            fba_storage_fee=float(row.get('storage_fee', 0)),
            ad_spend_ratio=float(row.get('ad_ratio', 0)),
            return_rate=float(row.get('return_rate', 0)),
            return_processing_fee=float(row.get('return_fee', 0)),
            other_fees=float(row.get('other_fees', 0)),
            category=row.get('category', 'default'),
        )
        products.append(product)
    
    return products


# ============================================================
# CLI Entry Point
# ============================================================

def main():
    """Command line entry"""
    # Default test data
    test_product = ProductInput(
        sku="TEST001",
        name="Kitchen Gadget",
        selling_price=29.99,
        product_cost=6.00,
        shipping_cost=1.50,
        fba_fulfillment_fee=5.50,
        fba_storage_fee=0.30,
        ad_spend_ratio=0.10,
        return_rate=0.03,
        return_processing_fee=2.00,
        other_fees=0.50,
        category="kitchen",
    )
    
    # If JSON input provided
    if len(sys.argv) > 1:
        try:
            input_data = json.loads(sys.argv[1])
            if isinstance(input_data, list):
                # Batch mode
                products = [ProductInput(**p) for p in input_data]
                results = analyze_batch(products)
                print(format_batch_summary(results))
                return
            else:
                test_product = ProductInput(**input_data)
        except Exception as e:
            print(f"Error: {e}")
            sys.exit(1)
    
    # Single product analysis
    result = analyze_product(test_product)
    print(format_full_report(result))


if __name__ == "__main__":
    main()

Profit Margin Calculator Amazon

Skill

Amazon profit margin calculator for sellers. Calculate cost breakdowns, profit margins, break-even points, and get pricing recommendations. Supports single p...

---
name: profit-margin-calculator-amazon
description: "Amazon profit margin calculator for sellers. Calculate cost breakdowns, profit margins, break-even points, and get pricing recommendations. Supports single product analysis and batch calculations. Input product cost, shipping, FBA fees, and get instant profitability analysis. No API key required. Use when: (1) evaluating new product profitability before sourcing, (2) diagnosing existing product margins, (3) adjusting pricing strategy, (4) analyzing multiple SKUs at once."
metadata: {"nexscope":{"emoji":"💰","category":"ecommerce"}}
---

# Profit Margin Calculator — Amazon 💰

Calculate product profitability for Amazon FBA sellers — cost breakdowns, profit margins, break-even analysis, and pricing recommendations. No API key required.

## Installation

```bash
npx skills add nexscope-ai/eCommerce-Skills --skill profit-margin-calculator-amazon -g
```

## Use Cases

| Scenario | What You'll Get |
|----------|-----------------|
| **New product evaluation** | Profitability forecast before sourcing |
| **Existing product diagnosis** | Margin analysis with cost breakdown |
| **Pricing adjustment** | Recommended prices for target margins |
| **Batch SKU analysis** | Multi-product comparison table |

## Usage Examples

### Single Product Analysis

```
Calculate profit for my Amazon product:
- Selling price: $29.99
- Product cost: $6
- Shipping to FBA: $1.50
- FBA fulfillment fee: $5.50
- FBA storage: $0.30/month
- Ad spend: 10% of sales
- Category: Kitchen
```

### Quick Analysis

```
Is this product profitable?
Price $19.99, cost $5, FBA fee $4.50, shipping $1
```

### Batch Analysis

```
Analyze these SKUs:
A001, Yoga Mat, $29.99, cost $6, shipping $1.5, FBA $5.5
A002, Resistance Bands, $19.99, cost $3, shipping $0.8, FBA $4
A003, Foam Roller, $24.99, cost $8, shipping $2, FBA $6
```

---

## Input Parameters

### Required

| Parameter | Description | Example |
|-----------|-------------|---------|
| `selling_price` | Amazon listing price | $29.99 |
| `product_cost` | FOB/sourcing cost per unit | $6.00 |
| `fba_fee` | FBA fulfillment fee | $5.50 |

### Recommended

| Parameter | Description | Default |
|-----------|-------------|---------|
| `shipping_cost` | Inbound shipping per unit | $0 |
| `storage_fee` | Monthly FBA storage per unit | $0.30 |
| `ad_ratio` | PPC spend as % of sales | 10% |
| `category` | Product category for referral fee | default (15%) |

### Optional

| Parameter | Description | Default |
|-----------|-------------|---------|
| `return_rate` | Expected return rate | 3% |
| `other_fees` | Packaging, labels, etc. | $0 |

---

## Cost Components

| Cost Item | Description | Calculation |
|-----------|-------------|-------------|
| **Product Cost** | FOB purchase price | User input |
| **Inbound Shipping** | Sea/air freight to FBA | User input |
| **FBA Fulfillment** | Amazon pick, pack, ship | User input |
| **FBA Storage** | Monthly warehouse fee | User input |
| **Referral Fee** | Amazon commission (8-20%) | Auto × category rate |
| **Advertising** | PPC spend | Price × ad ratio |
| **Returns** | Return processing loss | Return rate × handling |
| **Other Fees** | Packaging, labels, prep | User input |

---

## Referral Fee Rates by Category

| Category | Rate |
|----------|------|
| Electronics / Computers | 8% |
| Camera / Photo | 8% |
| Automotive / Industrial | 12% |
| **Most Categories (default)** | **15%** |
| Clothing / Apparel | 17% |
| Jewelry | 20% |

---

## Output Format

### Cost Breakdown

```
Selling Price         $29.99   100.0%
───────────────────────────────────────
Product Cost          -$6.00    20.0%
Inbound Shipping      -$1.50     5.0%
FBA Fulfillment       -$5.50    18.3%
FBA Storage           -$0.30     1.0%
Referral Fee (15%)    -$4.50    15.0%
Advertising (10%)     -$3.00    10.0%
Returns (3%)          -$0.15     0.5%
Other Fees            -$0.50     1.7%
───────────────────────────────────────
Total Cost            $21.45    71.5%
Net Profit            $8.54     28.5%
```

### Break-Even Analysis

```
Break-even Price:     $20.50
Current Margin:       +46.3% above break-even
Safety Margin:        31.6%
```

### Pricing Recommendations

```
| Target Margin | Recommended Price | Profit/Unit |
|---------------|-------------------|-------------|
| 15%           | $23.10            | $3.47       |
| 20%           | $25.20            | $5.04       |
| 25%           | $27.72            | $6.93       |
| 30%           | $30.80            | $9.24       |
```

---

## Profitability Status

| Net Margin | Status | Recommendation |
|------------|--------|----------------|
| >20% | ✅ **Healthy** | Maintain current strategy |
| 5-20% | ⚠️ **Warning** | Optimize costs or raise price |
| 0-5% | 🔴 **Danger** | Needs adjustment |
| <0% | 💀 **Loss** | Stop or restructure |

---

## Batch Input Format

### CSV

```csv
sku,name,selling_price,product_cost,shipping_cost,fba_fee,storage_fee,ad_ratio,category
A001,Yoga Mat,29.99,6,1.5,5.5,0.3,0.1,sports
A002,Resistance Bands,19.99,3,0.8,4,0.2,0.12,sports
A003,Foam Roller,24.99,8,2,6,0.3,0.1,sports
```

### Natural Language

```
Batch calculate:
SKU A001: Yoga Mat, $29.99, cost $6, shipping $1.5, FBA $5.5
SKU A002: Bands, $19.99, cost $3, shipping $0.8, FBA $4
```

---

## Script Usage

```bash
# Default demo
python3 scripts/calculator.py

# Custom input
python3 scripts/calculator.py '{"selling_price": 29.99, "product_cost": 6, "fba_fee": 5.5}'

# Batch analysis
python3 scripts/calculator.py '[{"sku": "A001", ...}, {"sku": "A002", ...}]'
```

---

## Handling Incomplete Input

If user doesn't provide enough info, ask:

```
To calculate your profit margin, I need:

**Required:**
- Selling price
- Product cost (FOB)
- FBA fulfillment fee

**Recommended (more accurate):**
- Inbound shipping cost per unit
- FBA storage fee per unit/month
- Ad spend ratio (% of sales)
- Product category (for referral fee)

Example:
"Price $25, cost $5, FBA $4.50, shipping $1, ads 10%, category: kitchen"
```

---

## Integration with Other Skills

Looking for more e-commerce tools? Check out our other skill collections:

- **[Amazon Skills](https://github.com/nexscope-ai/Amazon-Skills)** — Specialized tools for Amazon sellers: keyword research, listing optimization, PPC campaigns
- **[eCommerce Skills](https://github.com/nexscope-ai/eCommerce-Skills)** — Cross-platform tools for all e-commerce businesses

---

## Limitations

This skill calculates margins based on user-provided costs. For real-time FBA fee lookups, exact category rates, and advanced analytics, check out **[Nexscope](https://nexscope.ai)**.

---

**Part of [Nexscope AI](https://www.nexscope.ai/) — AI tools for e-commerce sellers.**


FILE:scripts/calculator.py
#!/usr/bin/env python3
"""
Amazon Profit Calculator - Core Engine

Features:
- Cost breakdown calculation
- Profit margin calculation (gross/net)
- Break-even analysis
- Pricing recommendations
- Batch calculation support

Version: 1.0.0
"""

import json
import csv
from dataclasses import dataclass, field
from typing import List, Dict, Optional
from enum import Enum
import sys


class ProfitStatus(Enum):
    HEALTHY = "healthy"      # >20% net margin
    WARNING = "warning"      # 5-20% net margin
    DANGER = "danger"        # <5% net margin
    LOSS = "loss"            # Negative margin


# ============================================================
# Amazon Referral Fee Rates (by category)
# ============================================================

REFERRAL_FEE_RATES = {
    # Category: Rate
    "default": 0.15,
    "electronics": 0.08,
    "computers": 0.08,
    "camera": 0.08,
    "video_games": 0.15,
    "books": 0.15,
    "clothing": 0.17,
    "shoes": 0.15,
    "jewelry": 0.20,
    "watches": 0.15,
    "furniture": 0.15,
    "home": 0.15,
    "kitchen": 0.15,
    "beauty": 0.15,
    "health": 0.15,
    "grocery": 0.15,
    "pet": 0.15,
    "toys": 0.15,
    "baby": 0.15,
    "sports": 0.15,
    "outdoors": 0.15,
    "automotive": 0.12,
    "industrial": 0.12,
    "office": 0.15,
}

# FBA Fulfillment Fee Reference (simplified, based on size tier)
FBA_FULFILLMENT_FEES = {
    "small_standard": 3.22,      # Small standard (<1lb)
    "large_standard_1lb": 4.75,  # Large standard (<1lb)
    "large_standard_2lb": 5.40,  # Large standard (1-2lb)
    "large_standard_3lb": 6.10,  # Large standard (2-3lb)
    "small_oversize": 9.73,      # Small oversize
    "medium_oversize": 19.05,    # Medium oversize
    "large_oversize": 89.98,     # Large oversize
}

# Profit margin thresholds
PROFIT_THRESHOLDS = {
    "healthy": 0.20,    # >20%
    "warning": 0.05,    # 5-20%
    "danger": 0.00,     # 0-5%
}


# ============================================================
# Data Structures
# ============================================================

@dataclass
class ProductInput:
    """Single product input data"""
    sku: str = "SKU001"
    name: str = "Product"
    
    # Selling price
    selling_price: float = 0.0
    
    # Cost items
    product_cost: float = 0.0           # Product cost (FOB)
    shipping_cost: float = 0.0          # Inbound shipping
    fba_fulfillment_fee: float = 0.0    # FBA fulfillment fee
    fba_storage_fee: float = 0.0        # FBA storage fee (monthly avg)
    
    # Optional costs
    ad_spend_ratio: float = 0.0         # Ad spend ratio (0-1)
    return_rate: float = 0.0            # Return rate (0-1)
    return_processing_fee: float = 0.0  # Return processing fee per unit
    other_fees: float = 0.0             # Other fees
    
    # Platform related
    category: str = "default"           # Category (for Referral Fee)
    referral_fee_rate: Optional[float] = None  # Custom commission rate
    
    # For batch calculation
    monthly_sales: int = 0              # Monthly sales (for fixed cost allocation)
    fixed_costs: float = 0.0            # Fixed costs (for break-even)


@dataclass
class CostBreakdown:
    """Cost breakdown"""
    selling_price: float
    product_cost: float
    shipping_cost: float
    fba_fulfillment_fee: float
    fba_storage_fee: float
    referral_fee: float
    ad_cost: float
    return_cost: float
    other_fees: float
    
    total_cost: float = 0.0
    gross_profit: float = 0.0
    net_profit: float = 0.0
    gross_margin: float = 0.0
    net_margin: float = 0.0
    
    def __post_init__(self):
        self.total_cost = (
            self.product_cost +
            self.shipping_cost +
            self.fba_fulfillment_fee +
            self.fba_storage_fee +
            self.referral_fee +
            self.ad_cost +
            self.return_cost +
            self.other_fees
        )
        self.gross_profit = self.selling_price - self.product_cost - self.shipping_cost - self.fba_fulfillment_fee - self.referral_fee
        self.net_profit = self.selling_price - self.total_cost
        self.gross_margin = self.gross_profit / self.selling_price if self.selling_price > 0 else 0
        self.net_margin = self.net_profit / self.selling_price if self.selling_price > 0 else 0


@dataclass
class BreakEvenAnalysis:
    """Break-even analysis"""
    min_price: float              # Minimum price (break-even)
    break_even_units: int         # Break-even units
    safety_margin: float          # Safety margin
    current_margin_above_min: float  # Current price above minimum


@dataclass
class PricingSuggestion:
    """Pricing recommendation"""
    target_margin: float          # Target profit margin
    suggested_price: float        # Suggested price
    profit_per_unit: float        # Profit per unit


@dataclass
class AnalysisResult:
    """Complete analysis result"""
    product: ProductInput
    cost_breakdown: CostBreakdown
    break_even: BreakEvenAnalysis
    pricing_suggestions: List[PricingSuggestion]
    status: ProfitStatus
    summary: str


# ============================================================
# Core Calculation Functions
# ============================================================

def get_referral_fee_rate(category: str, custom_rate: Optional[float] = None) -> float:
    """Get Referral Fee rate"""
    if custom_rate is not None:
        return custom_rate
    return REFERRAL_FEE_RATES.get(category.lower(), REFERRAL_FEE_RATES["default"])


def calculate_costs(product: ProductInput) -> CostBreakdown:
    """Calculate cost breakdown"""
    # Referral Fee
    referral_rate = get_referral_fee_rate(product.category, product.referral_fee_rate)
    referral_fee = product.selling_price * referral_rate
    
    # Ad cost
    ad_cost = product.selling_price * product.ad_spend_ratio
    
    # Return cost = return rate × (processing fee + product cost loss ratio)
    return_cost = product.return_rate * (product.return_processing_fee + product.product_cost * 0.5)
    
    return CostBreakdown(
        selling_price=product.selling_price,
        product_cost=product.product_cost,
        shipping_cost=product.shipping_cost,
        fba_fulfillment_fee=product.fba_fulfillment_fee,
        fba_storage_fee=product.fba_storage_fee,
        referral_fee=round(referral_fee, 2),
        ad_cost=round(ad_cost, 2),
        return_cost=round(return_cost, 2),
        other_fees=product.other_fees
    )


def calculate_break_even(product: ProductInput, costs: CostBreakdown) -> BreakEvenAnalysis:
    """Calculate break-even point"""
    # Variable cost (per unit)
    variable_cost = (
        product.product_cost +
        product.shipping_cost +
        product.fba_fulfillment_fee +
        product.fba_storage_fee +
        costs.referral_fee +
        costs.return_cost +
        product.other_fees
    )
    
    # Minimum price (cover variable cost + ad spend)
    # Ad ratio unchanged: min_price - variable_cost - min_price * ad_ratio = 0
    # min_price * (1 - ad_ratio) = variable_cost
    if product.ad_spend_ratio < 1:
        min_price = variable_cost / (1 - product.ad_spend_ratio)
    else:
        min_price = variable_cost * 2  # Abnormal case
    
    # Break-even units (if fixed costs exist)
    if product.fixed_costs > 0 and costs.net_profit > 0:
        break_even_units = int(product.fixed_costs / costs.net_profit) + 1
    else:
        break_even_units = 0
    
    # Safety margin
    safety_margin = (product.selling_price - min_price) / product.selling_price if product.selling_price > 0 else 0
    margin_above_min = (product.selling_price - min_price) / min_price if min_price > 0 else 0
    
    return BreakEvenAnalysis(
        min_price=round(min_price, 2),
        break_even_units=break_even_units,
        safety_margin=round(safety_margin, 4),
        current_margin_above_min=round(margin_above_min, 4)
    )


def calculate_pricing_suggestions(product: ProductInput, target_margins: List[float] = None) -> List[PricingSuggestion]:
    """Calculate pricing recommendations"""
    if target_margins is None:
        target_margins = [0.15, 0.20, 0.25, 0.30]
    
    suggestions = []
    
    # Base cost (excluding Referral Fee and ad cost as they're % of price)
    base_cost = (
        product.product_cost +
        product.shipping_cost +
        product.fba_fulfillment_fee +
        product.fba_storage_fee +
        product.other_fees +
        product.return_rate * product.return_processing_fee
    )
    
    referral_rate = get_referral_fee_rate(product.category, product.referral_fee_rate)
    
    for target_margin in target_margins:
        # Target: net_profit / selling_price = target_margin
        # net_profit = selling_price - base_cost - selling_price * referral_rate - selling_price * ad_ratio
        # selling_price * target_margin = selling_price - base_cost - selling_price * (referral_rate + ad_ratio)
        # selling_price * (target_margin + referral_rate + ad_ratio - 1) = -base_cost
        # selling_price = base_cost / (1 - target_margin - referral_rate - ad_ratio)
        
        denominator = 1 - target_margin - referral_rate - product.ad_spend_ratio
        if denominator > 0:
            suggested_price = base_cost / denominator
            profit_per_unit = suggested_price * target_margin
            
            suggestions.append(PricingSuggestion(
                target_margin=target_margin,
                suggested_price=round(suggested_price, 2),
                profit_per_unit=round(profit_per_unit, 2)
            ))
    
    return suggestions


def evaluate_profit_status(net_margin: float) -> ProfitStatus:
    """Evaluate profit status"""
    if net_margin < 0:
        return ProfitStatus.LOSS
    elif net_margin < PROFIT_THRESHOLDS["warning"]:
        return ProfitStatus.DANGER
    elif net_margin < PROFIT_THRESHOLDS["healthy"]:
        return ProfitStatus.WARNING
    else:
        return ProfitStatus.HEALTHY


def analyze_product(product: ProductInput, target_margins: List[float] = None) -> AnalysisResult:
    """Analyze single product"""
    costs = calculate_costs(product)
    break_even = calculate_break_even(product, costs)
    pricing = calculate_pricing_suggestions(product, target_margins)
    status = evaluate_profit_status(costs.net_margin)
    
    # Generate summary
    status_text = {
        ProfitStatus.HEALTHY: "✅ Healthy",
        ProfitStatus.WARNING: "⚠️ Warning",
        ProfitStatus.DANGER: "🔴 Danger",
        ProfitStatus.LOSS: "💀 Loss",
    }
    summary = f"{status_text[status]} | Net Margin {costs.net_margin*100:.1f}% | Profit/Unit .2f"
    
    return AnalysisResult(
        product=product,
        cost_breakdown=costs,
        break_even=break_even,
        pricing_suggestions=pricing,
        status=status,
        summary=summary
    )


def analyze_batch(products: List[ProductInput], target_margins: List[float] = None) -> List[AnalysisResult]:
    """Batch analysis"""
    return [analyze_product(p, target_margins) for p in products]


# ============================================================
# Output Formatting
# ============================================================

def format_cost_breakdown(costs: CostBreakdown) -> str:
    """Format cost breakdown"""
    def pct(val):
        return f"{val/costs.selling_price*100:.1f}%" if costs.selling_price > 0 else "0%"
    
    lines = [
        f"Selling Price         .2f   100%",
        "─" * 40,
        f"Product Cost          -.2f    {pct(costs.product_cost)}",
        f"Inbound Shipping      -.2f    {pct(costs.shipping_cost)}",
        f"FBA Fulfillment       -.2f    {pct(costs.fba_fulfillment_fee)}",
        f"FBA Storage           -.2f    {pct(costs.fba_storage_fee)}",
        f"Referral Fee          -.2f    {pct(costs.referral_fee)}",
        f"Advertising           -.2f    {pct(costs.ad_cost)}",
        f"Returns               -.2f    {pct(costs.return_cost)}",
        f"Other Fees            -.2f    {pct(costs.other_fees)}",
        "─" * 40,
        f"Total Cost            .2f    {pct(costs.total_cost)}",
        f"Net Profit            .2f    {costs.net_margin*100:.1f}%",
    ]
    return "\n".join(lines)


def format_break_even(be: BreakEvenAnalysis, current_price: float) -> str:
    """Format break-even analysis"""
    lines = [
        f"Break-even Price: .2f",
        f"├── Below this price = Loss",
        f"",
        f"Current Price: .2f",
        f"├── {be.current_margin_above_min*100:.1f}% above break-even",
        f"",
        f"Safety Margin: {be.safety_margin*100:.1f}%",
        f"├── Room for price reduction",
    ]
    if be.break_even_units > 0:
        lines.extend([
            f"",
            f"Break-even Units: {be.break_even_units}",
            f"├── Units needed to cover fixed costs",
        ])
    return "\n".join(lines)


def format_pricing_suggestions(suggestions: List[PricingSuggestion], current_price: float, current_margin: float) -> str:
    """Format pricing recommendations"""
    lines = [
        "| Target Margin | Recommended Price | Profit/Unit |",
        "|---------------|-------------------|-------------|",
    ]
    for s in suggestions:
        lines.append(f"| {s.target_margin*100:.0f}% | .2f | .2f |")
    
    lines.append(f"\nCurrent Price .2f → Net Margin {current_margin*100:.1f}%")
    return "\n".join(lines)


def format_full_report(result: AnalysisResult) -> str:
    """Generate full report"""
    status_icons = {
        ProfitStatus.HEALTHY: "✅",
        ProfitStatus.WARNING: "⚠️",
        ProfitStatus.DANGER: "🔴",
        ProfitStatus.LOSS: "💀",
    }
    
    report = f"""
💰 **Amazon Profit Analysis Report**

**Product**: {result.product.name} ({result.product.sku})
**Status**: {status_icons[result.status]} {result.summary}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 **Cost Breakdown**

```
{format_cost_breakdown(result.cost_breakdown)}
```

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📈 **Break-Even Analysis**

{format_break_even(result.break_even, result.product.selling_price)}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💡 **Pricing Recommendations**

{format_pricing_suggestions(result.pricing_suggestions, result.product.selling_price, result.cost_breakdown.net_margin)}

"""
    return report


def format_batch_summary(results: List[AnalysisResult]) -> str:
    """Format batch analysis summary"""
    status_icons = {
        ProfitStatus.HEALTHY: "✅",
        ProfitStatus.WARNING: "⚠️",
        ProfitStatus.DANGER: "🔴",
        ProfitStatus.LOSS: "💀",
    }
    
    lines = [
        "📊 **Batch Analysis Summary**",
        "",
        "| SKU | Price | Total Cost | Net Profit | Margin | Status |",
        "|-----|-------|------------|------------|--------|--------|",
    ]
    
    total_profit = 0
    for r in results:
        c = r.cost_breakdown
        icon = status_icons[r.status]
        lines.append(f"| {r.product.sku} | .2f | .2f | .2f | {c.net_margin*100:.1f}% | {icon} |")
        total_profit += c.net_profit
    
    lines.append("")
    lines.append(f"**Total**: {len(results)} SKUs | Avg Profit/Unit .2f")
    
    # Statistics
    healthy = sum(1 for r in results if r.status == ProfitStatus.HEALTHY)
    warning = sum(1 for r in results if r.status == ProfitStatus.WARNING)
    danger = sum(1 for r in results if r.status == ProfitStatus.DANGER)
    loss = sum(1 for r in results if r.status == ProfitStatus.LOSS)
    
    lines.append(f"**Status Distribution**: ✅ {healthy} | ⚠️ {warning} | 🔴 {danger} | 💀 {loss}")
    
    return "\n".join(lines)


# ============================================================
# CSV Batch Processing
# ============================================================

def parse_csv(csv_content: str) -> List[ProductInput]:
    """Parse CSV content"""
    products = []
    reader = csv.DictReader(csv_content.strip().split('\n'))
    
    for row in reader:
        product = ProductInput(
            sku=row.get('sku', 'SKU'),
            name=row.get('name', 'Product'),
            selling_price=float(row.get('selling_price', 0)),
            product_cost=float(row.get('product_cost', 0)),
            shipping_cost=float(row.get('shipping_cost', 0)),
            fba_fulfillment_fee=float(row.get('fba_fee', 0)),
            fba_storage_fee=float(row.get('storage_fee', 0)),
            ad_spend_ratio=float(row.get('ad_ratio', 0)),
            return_rate=float(row.get('return_rate', 0)),
            return_processing_fee=float(row.get('return_fee', 0)),
            other_fees=float(row.get('other_fees', 0)),
            category=row.get('category', 'default'),
        )
        products.append(product)
    
    return products


# ============================================================
# CLI Entry Point
# ============================================================

def main():
    """Command line entry"""
    # Default test data
    test_product = ProductInput(
        sku="TEST001",
        name="Kitchen Gadget",
        selling_price=29.99,
        product_cost=6.00,
        shipping_cost=1.50,
        fba_fulfillment_fee=5.50,
        fba_storage_fee=0.30,
        ad_spend_ratio=0.10,
        return_rate=0.03,
        return_processing_fee=2.00,
        other_fees=0.50,
        category="kitchen",
    )
    
    # If JSON input provided
    if len(sys.argv) > 1:
        try:
            input_data = json.loads(sys.argv[1])
            if isinstance(input_data, list):
                # Batch mode
                products = [ProductInput(**p) for p in input_data]
                results = analyze_batch(products)
                print(format_batch_summary(results))
                return
            else:
                test_product = ProductInput(**input_data)
        except Exception as e:
            print(f"Error: {e}")
            sys.exit(1)
    
    # Single product analysis
    result = analyze_product(test_product)
    print(format_full_report(result))


if __name__ == "__main__":
    main()

Product Differentiation Tiktok

Skill

TikTok Shop product differentiation strategy tool. Analyze viral product trends, competitor affiliate strategies, content performance, and identify different...

---
name: product-differentiation-tiktok
version: 1.0.0
author: Nexscope AI
description: "TikTok Shop product differentiation strategy tool. Analyze viral product trends, competitor affiliate strategies, content performance, and identify differentiation opportunities. Includes TikTok-specific metrics like engagement rate, viral potential, and creator collaboration insights. No API key required."
metadata: {"nexscope":{"emoji":"🎯","category":"ecommerce"}}
---

# Product Differentiation — TikTok Shop 🎯

Develop winning product differentiation strategies for TikTok Shop.

## Installation

```bash
npx skills add nexscope-ai/eCommerce-Skills --skill product-differentiation-tiktok -g
```

## Features

- **Competitor Matrix** — Side-by-side product comparison
- **Viral Analysis** — Trending product patterns
- **Pain Point Mining** — Extract issues from reviews/comments
- **USP Extraction** — Identify unique selling points
- **Creator Strategy** — Affiliate collaboration insights
- **Action Plan** — Prioritized improvement roadmap

## TikTok-Specific Analysis

| Dimension | Method | Output |
|-----------|--------|--------|
| Viral Potential | Trend analysis | Virality score |
| Content Style | Video analysis | Hook patterns |
| Creator Fit | Niche matching | Ideal creators |
| Price Sweet Spot | Impulse buy analysis | Optimal pricing |
| Comment Sentiment | Comment NLP | Pain points |

## Progressive Analysis Levels

| Level | Required Data | Unlocked Analysis |
|-------|---------------|-------------------|
| **L1 Basic** | Product info | Basic comparison |
| **L2 Viral** | + Competitor content | Viral pattern analysis |
| **L3 Engagement** | + Comments/reviews | Sentiment analysis |
| **L4 Complete** | + Sales data | Full strategy & action plan |

## Usage

### Interactive Mode

```bash
python3 scripts/analyzer.py
```

### With Parameters

```bash
python3 scripts/analyzer.py '{
  "your_product": "Wireless Earbuds",
  "competitors": ["shop_id_1", "shop_id_2"],
  "category": "Electronics"
}'
```

## Output Example

```
🎯 TikTok Shop Differentiation Report

Product: Wireless Earbuds
Category: Electronics
Competitors Analyzed: 3

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 COMPETITOR COMPARISON

Attribute       | You  | Comp A | Comp B | Comp C
─────────────────────────────────────────────────
Price           | $25  | $20    | $30    | $18
Affiliate Rate  | 15%  | 20%    | 10%    | 25%
Avg Views       | 50K  | 200K   | 30K    | 150K
Engagement      | 5%   | 8%     | 3%     | 7%
Review Score    | 4.5  | 4.2    | 4.6    | 4.0

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔥 VIRAL PATTERNS (top performers)

1. Unboxing ASMR hooks
2. "You need this" format
3. Before/after demos
4. Creator authenticity

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

😤 TOP PAIN POINTS (from comments)

1. 🔴 Battery not as claimed (mentioned 45x)
2. 🔴 Sound quality issues (mentioned 32x)
3. 🟡 Shipping delays (mentioned 28x)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✨ DIFFERENTIATION OPPORTUNITIES

1. ⭐ Honest battery claims (build trust)
2. ⭐ Sound demo in content
3. ⭐ Fast shipping highlight
4. ⭐ Higher affiliate rate for top creators

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 ACTION PLAN

Priority | Action                    | Impact
─────────────────────────────────────────────
HIGH     | Create ASMR unboxing      | +50% views
HIGH     | Partner with nano-creators | +30% sales
MEDIUM   | Increase affiliate rate   | +20% reach
LOW      | Add comparison content    | +10% CVR
```

## TikTok Strategy Framework

```
Competitor Product Analysis
      ↓
Viral Content Pattern Mining
      ↓
Comment/Review Sentiment
      ↓
Creator Strategy Development
      ↓
Content Differentiation Plan
      ↓
Action Plan
```

---

**Part of [Nexscope AI](https://www.nexscope.ai/) — AI tools for e-commerce sellers.**

FILE:scripts/analyzer.py
#!/usr/bin/env python3
"""
Product Differentiation Analyzer - Core Engine
ProductDifferenceAnalyze - Core Engine

Features:
- CompetitorFeatureComparisonMatrix
- CompetitorNegative ReviewPain pointMining
- Positive ReviewSelling point extraction
- Difference angleDegreeIdentify
- MarketPositioningStrategy
- PricingStrategyRecommendation
- MarketingSelling pointRecommendation
- ProductImproveRecommendation

SupportProgressiveAnalyze:
L1: BasicComparison (ProductInformation)
L2: Pain pointAnalyze (+ CompetitorNegative Review)
L3: Selling point extraction (+ SelfPositive Review)
L4: CompleteStrategy (+ MarketData)

Version: 1.0.0
"""

import json
from dataclasses import dataclass, field
from typing import List, Dict, Optional, Tuple
from enum import Enum
from datetime import datetime
import sys
import re
from collections import Counter


class AnalysisLevel(Enum):
    """AnalyzelayerLevel"""
    L1 = "L1"  # BasicComparison
    L2 = "L2"  # Pain pointAnalyze
    L3 = "L3"  # Selling point extraction
    L4 = "L4"  # CompleteStrategy


class DiffAngle(Enum):
    """Difference angleDegree"""
    FUNCTION = "function"       # FeatureDifference
    QUALITY = "quality"         # QualityDifference
    DESIGN = "design"           # Design difference
    PRICE = "price"             # PriceDifference
    SERVICE = "service"         # Service difference
    AUDIENCE = "audience"       # Audience difference
    SCENARIO = "scenario"       # Scenario difference
    BRAND = "brand"             # BrandDifference


# ============================================================
# Pain pointKeywordsLibrary
# ============================================================

PAIN_POINT_KEYWORDS = {
    "quality": {
        "en": ["cheap", "broke", "broken", "flimsy", "poor quality", "fell apart", "defective", "doesn't last", "stopped working"],
        "zh": ["Poor quality", " bad  ", "Fragile", "Poor workmanship", "Not durable", "StopWork"],
    },
    "function": {
        "en": ["doesn't work", "not working", "malfunction", "missing feature", "can't", "won't", "failed", "useless"],
        "zh": ["notWork", "Fault", "FeatureMissing", "Cannot", "Failed", "Useless"],
    },
    "design": {
        "en": ["ugly", "looks cheap", "bulky", "heavy", "uncomfortable", "awkward", "hard to use", "confusing"],
        "zh": ["ugly", "Looks cheap", "clumsy heavy ", " heavy ", "Uncomfortable", "Hard to use", "Complex"],
    },
    "size": {
        "en": ["too small", "too big", "wrong size", "doesn't fit", "smaller than expected", "bigger than"],
        "zh": [" too  small ", " too  big ", "Sizenot for ", "Not suitable"],
    },
    "shipping": {
        "en": ["late", "damaged", "wrong item", "missing parts", "packaging"],
        "zh": ["late to ", "loss bad ", "Sent wrong", "Missing parts", "Packaging"],
    },
    "value": {
        "en": ["overpriced", "not worth", "waste of money", "rip off", "too expensive"],
        "zh": [" too expensive", "notValue", "Waste money", "trap"],
    },
}

SELLING_POINT_KEYWORDS = {
    "quality": {
        "en": ["solid", "sturdy", "durable", "well made", "high quality", "premium", "excellent", "perfect"],
        "zh": ["Sturdy", "Durable", "Workmanship good ", "HighQuality", "Quality", "Perfect"],
    },
    "function": {
        "en": ["works great", "works perfectly", "easy to use", "convenient", "efficient", "powerful", "fast"],
        "zh": [" good use", "Convenient", "Higheffect", "strong big ", " fast "],
    },
    "design": {
        "en": ["beautiful", "sleek", "stylish", "modern", "compact", "lightweight", "elegant"],
        "zh": ["Beautiful", "Timeyet", "Modern", " small clever", " light easy", "Elegant"],
    },
    "value": {
        "en": ["great value", "worth it", "good price", "affordable", "best purchase", "recommend"],
        "zh": ["Value ", "Value for money", "Recommended", "Worth it"],
    },
    "service": {
        "en": ["great service", "fast shipping", "well packaged", "responsive seller"],
        "zh": ["Service good ", "Shipping fast ", "Packaging good ", "SellerResponse fast "],
    },
}


# ============================================================
# Data Structures
# ============================================================

@dataclass
class ProductInfo:
    """ProductInformation"""
    name: str = ""
    asin: str = ""
    price: float = 0.0
    rating: float = 0.0
    review_count: int = 0
    features: List[str] = field(default_factory=list)
    bullet_points: List[str] = field(default_factory=list)
    category: str = ""
    brand: str = ""
    is_mine: bool = False


@dataclass
class ReviewData:
    """Review Countdata"""
    positive: List[str] = field(default_factory=list)  # Positive Review
    negative: List[str] = field(default_factory=list)  # Negative Review
    neutral: List[str] = field(default_factory=list)   # Neutral review


@dataclass
class PainPoint:
    """Pain point"""
    category: str
    description: str
    description_zh: str
    frequency: int
    severity: str  # high/medium/low
    example_reviews: List[str] = field(default_factory=list)


@dataclass
class SellingPoint:
    """Selling point"""
    category: str
    description: str
    description_zh: str
    frequency: int
    strength: str  # strong/medium/weak
    example_reviews: List[str] = field(default_factory=list)


@dataclass
class DiffOpportunity:
    """Differentiation Opportunities"""
    angle: DiffAngle
    opportunity: str
    opportunity_zh: str
    priority: str  # high/medium/low
    action: str
    action_zh: str
    potential_impact: str


@dataclass
class PositioningStrategy:
    """PositioningStrategy"""
    position_type: str  # premium/value/niche/innovation
    target_audience: str
    target_audience_zh: str
    price_strategy: str
    price_strategy_zh: str
    key_message: str
    key_message_zh: str
    marketing_angles: List[str] = field(default_factory=list)


@dataclass
class AnalysisResult:
    """AnalyzeResult"""
    level: AnalysisLevel
    my_product: ProductInfo
    competitors: List[ProductInfo]
    comparison_matrix: Dict
    pain_points: List[PainPoint]
    selling_points: List[SellingPoint]
    diff_opportunities: List[DiffOpportunity]
    positioning: Optional[PositioningStrategy]
    action_items: List[Dict]
    next_level_hint: str
    next_level_hint_zh: str
    summary: str
    summary_zh: str


# ============================================================
# AnalyzeFunction
# ============================================================

def extract_pain_points(reviews: List[str], lang: str = "en") -> List[PainPoint]:
    """ from Negative Review in ExtractPain point"""
    pain_points = []
    category_counts = Counter()
    category_examples = {}
    
    for review in reviews:
        review_lower = review.lower()
        for category, keywords in PAIN_POINT_KEYWORDS.items():
            for keyword in keywords.get(lang, []) + keywords.get("en", []):
                if keyword.lower() in review_lower:
                    category_counts[category] += 1
                    if category not in category_examples:
                        category_examples[category] = []
                    if len(category_examples[category]) < 3:
                        category_examples[category].append(review[:100])
                    break
    
    category_names = {
        "quality": ("Quality Issues", "QualityIssue"),
        "function": ("Functionality Problems", "FeatureIssue"),
        "design": ("Design Flaws", "Design defect"),
        "size": ("Size/Fit Issues", "SizeIssue"),
        "shipping": ("Shipping/Packaging", "LogisticsPackaging"),
        "value": ("Value Concerns", "Value for money"),
    }
    
    for category, count in category_counts.most_common():
        if count >= 1:
            severity = "high" if count >= 5 else "medium" if count >= 2 else "low"
            names = category_names.get(category, (category.title(), category))
            pain_points.append(PainPoint(
                category=category,
                description=names[0],
                description_zh=names[1],
                frequency=count,
                severity=severity,
                example_reviews=category_examples.get(category, []),
            ))
    
    return pain_points


def extract_selling_points(reviews: List[str], lang: str = "en") -> List[SellingPoint]:
    """ from Positive ReviewExtract selling points from"""
    selling_points = []
    category_counts = Counter()
    category_examples = {}
    
    for review in reviews:
        review_lower = review.lower()
        for category, keywords in SELLING_POINT_KEYWORDS.items():
            for keyword in keywords.get(lang, []) + keywords.get("en", []):
                if keyword.lower() in review_lower:
                    category_counts[category] += 1
                    if category not in category_examples:
                        category_examples[category] = []
                    if len(category_examples[category]) < 3:
                        category_examples[category].append(review[:100])
                    break
    
    category_names = {
        "quality": ("Build Quality", "WorkmanshipQuality"),
        "function": ("Functionality", "Featurenature"),
        "design": ("Design & Aesthetics", "Beautiful design"),
        "value": ("Value for Money", "Value for money"),
        "service": ("Service & Shipping", "ServiceLogistics"),
    }
    
    for category, count in category_counts.most_common():
        if count >= 1:
            strength = "strong" if count >= 5 else "medium" if count >= 2 else "weak"
            names = category_names.get(category, (category.title(), category))
            selling_points.append(SellingPoint(
                category=category,
                description=names[0],
                description_zh=names[1],
                frequency=count,
                strength=strength,
                example_reviews=category_examples.get(category, []),
            ))
    
    return selling_points


def build_comparison_matrix(my_product: ProductInfo, competitors: List[ProductInfo]) -> Dict:
    """BuildComparisonMatrix"""
    matrix = {
        "products": [my_product.name] + [c.name for c in competitors],
        "prices": [my_product.price] + [c.price for c in competitors],
        "ratings": [my_product.rating] + [c.rating for c in competitors],
        "review_counts": [my_product.review_count] + [c.review_count for c in competitors],
    }
    
    # PricePositioning
    all_prices = [p for p in matrix["prices"] if p > 0]
    if all_prices:
        avg_price = sum(all_prices) / len(all_prices)
        matrix["price_position"] = "above_avg" if my_product.price > avg_price else "below_avg"
        matrix["avg_price"] = avg_price
    
    # RatingPositioning
    all_ratings = [r for r in matrix["ratings"] if r > 0]
    if all_ratings:
        avg_rating = sum(all_ratings) / len(all_ratings)
        matrix["rating_position"] = "above_avg" if my_product.rating > avg_rating else "below_avg"
        matrix["avg_rating"] = avg_rating
    
    return matrix


def identify_opportunities(
    my_product: ProductInfo,
    competitors: List[ProductInfo],
    pain_points: List[PainPoint],
    selling_points: List[SellingPoint],
    matrix: Dict
) -> List[DiffOpportunity]:
    """IdentifyDifferentiation Opportunities"""
    opportunities = []
    
    # 1. Based onCompetitorPain pointOpportunity
    for pain in pain_points:
        if pain.severity == "high":
            opp = DiffOpportunity(
                angle=DiffAngle.FUNCTION if pain.category == "function" else DiffAngle.QUALITY,
                opportunity=f"Address competitor weakness: {pain.description}",
                opportunity_zh=f"SolveCompetitorWeakness: {pain.description_zh}",
                priority="high",
                action=f"Improve {pain.category} and highlight in marketing",
                action_zh=f"Improve{pain.description_zh}and in Marketing in Highlight",
                potential_impact="High - directly addresses customer pain",
            )
            opportunities.append(opp)
    
    # 2. Based onPriceOpportunity
    if matrix.get("price_position") == "below_avg":
        opportunities.append(DiffOpportunity(
            angle=DiffAngle.PRICE,
            opportunity="Value positioning - lower price than competitors",
            opportunity_zh="Value for moneyPositioning - Price low  at Competitor",
            priority="medium",
            action="Emphasize value proposition in marketing",
            action_zh=" in Marketing in EmphasizeValue for money",
            potential_impact="Medium - price-sensitive customers",
        ))
    elif matrix.get("price_position") == "above_avg":
        opportunities.append(DiffOpportunity(
            angle=DiffAngle.PRICE,
            opportunity="Premium positioning - justify higher price",
            opportunity_zh="PremiumPositioning - ProofHigherPriceReasonable",
            priority="high",
            action="Highlight premium features and quality",
            action_zh="HighlightPremiumFeatureAndQuality",
            potential_impact="High - must justify price premium",
        ))
    
    # 3. Based onRatingOpportunity
    if matrix.get("rating_position") == "above_avg":
        opportunities.append(DiffOpportunity(
            angle=DiffAngle.QUALITY,
            opportunity="Quality leader - leverage higher rating",
            opportunity_zh="Qualitylead first  - UtilizeHigherRating",
            priority="high",
            action="Display rating prominently, collect more reviews",
            action_zh="HighlightDisplayRating，Collect more  many Review",
            potential_impact="High - social proof advantage",
        ))
    
    # 4. SegmentMarketOpportunity
    opportunities.append(DiffOpportunity(
        angle=DiffAngle.AUDIENCE,
        opportunity="Niche targeting - focus on specific user segment",
        opportunity_zh="SegmentPositioning - Focus on specificUserGroup",
        priority="medium",
        action="Identify underserved segment and tailor product/marketing",
        action_zh="IdentifyUnmetSegmentMarket，CustomProduct/Marketing",
        potential_impact="Medium - reduced competition in niche",
    ))
    
    return opportunities


def generate_positioning(
    my_product: ProductInfo,
    matrix: Dict,
    opportunities: List[DiffOpportunity]
) -> PositioningStrategy:
    """GeneratePositioningStrategy"""
    
    # ConfirmPositioningCategoryType
    price_pos = matrix.get("price_position", "below_avg")
    rating_pos = matrix.get("rating_position", "below_avg")
    
    if price_pos == "above_avg" and rating_pos == "above_avg":
        position_type = "premium"
        target = "Quality-conscious buyers willing to pay more"
        target_zh = "Willing for QualityPayPremiumUser"
        price_strategy = "Maintain premium pricing, bundle with extras"
        price_strategy_zh = "MaintainPremiumPricing，Bundle increaseValueService"
        key_message = "The premium choice for discerning customers"
        key_message_zh = "PremiumUserSmart choice"
    elif price_pos == "below_avg":
        position_type = "value"
        target = "Price-sensitive buyers seeking good deals"
        target_zh = "FindHighValue for moneyPriceSensitiveUser"
        price_strategy = "Competitive pricing, volume-focused"
        price_strategy_zh = "CompetitivePricing，Pursue sales volume"
        key_message = "Same quality, better price"
        key_message_zh = "same etcQuality， more excellentPrice"
    else:
        position_type = "balanced"
        target = "Mainstream buyers seeking reliable products"
        target_zh = "FindCanrelyProductMainflowUser"
        price_strategy = "Market-aligned pricing"
        price_strategy_zh = "MarketPricing"
        key_message = "The trusted choice"
        key_message_zh = "ValueTrustedChoice"
    
    marketing_angles = [
        f"[{opp.angle.value.upper()}] {opp.opportunity}" 
        for opp in opportunities[:3] if opp.priority == "high"
    ]
    
    return PositioningStrategy(
        position_type=position_type,
        target_audience=target,
        target_audience_zh=target_zh,
        price_strategy=price_strategy,
        price_strategy_zh=price_strategy_zh,
        key_message=key_message,
        key_message_zh=key_message_zh,
        marketing_angles=marketing_angles,
    )


def generate_action_items(
    opportunities: List[DiffOpportunity],
    pain_points: List[PainPoint],
    positioning: PositioningStrategy
) -> List[Dict]:
    """GenerateActionRecommendation"""
    actions = []
    
    # ProductImprove
    for pain in pain_points[:2]:
        if pain.severity in ["high", "medium"]:
            actions.append({
                "category": "Product",
                "category_zh": "Product",
                "action": f"Address {pain.description}",
                "action_zh": f"Solve{pain.description_zh}",
                "priority": "P1" if pain.severity == "high" else "P2",
                "timeline": "1-3 months",
            })
    
    # MarketingImprove
    for opp in opportunities[:2]:
        if opp.priority == "high":
            actions.append({
                "category": "Marketing",
                "category_zh": "Marketing",
                "action": opp.action,
                "action_zh": opp.action_zh,
                "priority": "P1",
                "timeline": "Immediate",
            })
    
    # PositioningRelated
    actions.append({
        "category": "Positioning",
        "category_zh": "Positioning",
        "action": f"Adopt {positioning.position_type} positioning strategy",
        "action_zh": f"Adopt{positioning.position_type}PositioningStrategy",
        "priority": "P1",
        "timeline": "Ongoing",
    })
    
    return actions


def determine_level(
    my_product: ProductInfo,
    competitors: List[ProductInfo],
    competitor_reviews: ReviewData,
    my_reviews: ReviewData
) -> AnalysisLevel:
    """ConfirmAnalyzelayerLevel"""
    has_products = my_product.name and len(competitors) > 0
    has_competitor_reviews = len(competitor_reviews.negative) > 0
    has_my_reviews = len(my_reviews.positive) > 0
    has_market_data = my_product.price > 0 and my_product.rating > 0
    
    if has_products and has_competitor_reviews and has_my_reviews and has_market_data:
        return AnalysisLevel.L4
    elif has_products and has_competitor_reviews and has_my_reviews:
        return AnalysisLevel.L3
    elif has_products and has_competitor_reviews:
        return AnalysisLevel.L2
    else:
        return AnalysisLevel.L1


def analyze(
    my_product: ProductInfo,
    competitors: List[ProductInfo],
    competitor_reviews: ReviewData = None,
    my_reviews: ReviewData = None,
) -> AnalysisResult:
    """MainAnalyzeFunction"""
    
    if competitor_reviews is None:
        competitor_reviews = ReviewData()
    if my_reviews is None:
        my_reviews = ReviewData()
    
    # ConfirmAnalyzelayerLevel
    level = determine_level(my_product, competitors, competitor_reviews, my_reviews)
    
    # BuildComparisonMatrix
    matrix = build_comparison_matrix(my_product, competitors)
    
    # ExtractPain point (L2+)
    pain_points = []
    if level.value >= AnalysisLevel.L2.value:
        pain_points = extract_pain_points(competitor_reviews.negative)
    
    # Extract selling points (L3+)
    selling_points = []
    if level.value >= AnalysisLevel.L3.value:
        selling_points = extract_selling_points(my_reviews.positive)
    
    # IdentifyDifferentiation Opportunities
    opportunities = identify_opportunities(my_product, competitors, pain_points, selling_points, matrix)
    
    # GeneratePositioningStrategy (L4)
    positioning = None
    if level == AnalysisLevel.L4:
        positioning = generate_positioning(my_product, matrix, opportunities)
    
    # GenerateActionRecommendation
    action_items = generate_action_items(opportunities, pain_points, positioning or PositioningStrategy(
        position_type="balanced", target_audience="", target_audience_zh="",
        price_strategy="", price_strategy_zh="", key_message="", key_message_zh=""
    ))
    
    #  below oneLevelHint
    hints = {
        AnalysisLevel.L1: ("Add competitor negative reviews for pain point analysis", "AddCompetitorNegative Review to ProceedPain pointAnalyze"),
        AnalysisLevel.L2: ("Add your product's positive reviews for selling point extraction", "AddyouProductPositive ReviewTo extract selling points"),
        AnalysisLevel.L3: ("Add price and rating data for complete positioning strategy", "AddPriceAndRatingDataTo obtainCompletePositioningStrategy"),
        AnalysisLevel.L4: ("Full analysis complete!", "CompleteAnalyze already Complete！"),
    }
    next_hint, next_hint_zh = hints[level]
    
    # Summary
    summary = f"Level {level.value} Analysis | {len(opportunities)} opportunities | {len(pain_points)} pain points identified"
    summary_zh = f"{level.value} LevelAnalyze | {len(opportunities)} Differentiation Opportunities | {len(pain_points)} Pain pointIdentify"
    
    return AnalysisResult(
        level=level,
        my_product=my_product,
        competitors=competitors,
        comparison_matrix=matrix,
        pain_points=pain_points,
        selling_points=selling_points,
        diff_opportunities=opportunities,
        positioning=positioning,
        action_items=action_items,
        next_level_hint=next_hint,
        next_level_hint_zh=next_hint_zh,
        summary=summary,
        summary_zh=summary_zh,
    )


# ============================================================
# OutputFormat
# ============================================================

def format_report(result: AnalysisResult, lang: str = "en") -> str:
    """FormatReport"""
    
    if lang == "zh":
        lines = [
            "🎯 **ProductDifferenceAnalyzeReport**",
            "",
            f"**AnalyzelayerLevel**: {result.level.value}",
            f"**IProduct**: {result.my_product.name}",
            f"**CompetitorQuantity**: {len(result.competitors)}",
            "",
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            "## 📊 CompetitorComparisonMatrix",
            "",
        ]
        
        # ComparisonTable
        lines.append("| Product | Price | Rating | Review Count |")
        lines.append("|------|------|------|--------|")
        lines.append(f"| **{result.my_product.name}** (I) | .2f | {result.my_product.rating} | {result.my_product.review_count} |")
        for c in result.competitors:
            lines.append(f"| {c.name} | .2f | {c.rating} | {c.review_count} |")
        
        if result.pain_points:
            lines.extend([
                "",
                "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
                "",
                "## 😤 CompetitorPain point (Differentiation Opportunities)",
                "",
            ])
            for i, pain in enumerate(result.pain_points, 1):
                severity_icon = "🔴" if pain.severity == "high" else "🟡" if pain.severity == "medium" else "🟢"
                lines.append(f"**{i}. {pain.description_zh}** {severity_icon}")
                lines.append(f"   Occurrence frequency: {pain.frequency} | CriticalprocessDegree: {pain.severity}")
                if pain.example_reviews:
                    lines.append(f"   Example: \"{pain.example_reviews[0][:50]}...\"")
                lines.append("")
        
        if result.selling_points:
            lines.extend([
                "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
                "",
                "## ✨ My selling point",
                "",
            ])
            for i, sp in enumerate(result.selling_points, 1):
                strength_icon = "💪" if sp.strength == "strong" else "👍" if sp.strength == "medium" else "👌"
                lines.append(f"**{i}. {sp.description_zh}** {strength_icon}")
                lines.append(f"   Occurrence frequency: {sp.frequency}")
                lines.append("")
        
        lines.extend([
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            "## 💡 Differentiation Opportunities",
            "",
        ])
        for i, opp in enumerate(result.diff_opportunities[:5], 1):
            priority_icon = "🔴" if opp.priority == "high" else "🟡"
            lines.append(f"**{i}. [{opp.angle.value.upper()}] {opp.opportunity_zh}** {priority_icon}")
            lines.append(f"   Action: {opp.action_zh}")
            lines.append("")
        
        if result.positioning:
            lines.extend([
                "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
                "",
                "## 🎯 PositioningStrategy",
                "",
                f"**PositioningCategoryType**: {result.positioning.position_type.upper()}",
                f"**Target audience**: {result.positioning.target_audience_zh}",
                f"**PriceStrategy**: {result.positioning.price_strategy_zh}",
                f"**CoreInformation**: {result.positioning.key_message_zh}",
                "",
            ])
        
        lines.extend([
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            "## 📋 Action Plan",
            "",
        ])
        for action in result.action_items[:5]:
            lines.append(f"**[{action['priority']}] [{action['category_zh']}]** {action['action_zh']}")
            lines.append(f"   Timeline: {action['timeline']}")
            lines.append("")
        
        if result.level != AnalysisLevel.L4:
            lines.extend([
                "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
                "",
                f"🔍 **Want to go deeperAnalyze？** {result.next_level_hint_zh}",
            ])
        
        lines.extend([
            "",
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            result.summary_zh,
        ])
    else:
        # English version (similar structure)
        lines = [
            "🎯 **Product Differentiation Analysis Report**",
            "",
            f"**Analysis Level**: {result.level.value}",
            f"**My Product**: {result.my_product.name}",
            f"**Competitors**: {len(result.competitors)}",
            "",
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            "## 📊 Comparison Matrix",
            "",
            "| Product | Price | Rating | Reviews |",
            "|---------|-------|--------|---------|",
            f"| **{result.my_product.name}** (Mine) | .2f | {result.my_product.rating} | {result.my_product.review_count} |",
        ]
        for c in result.competitors:
            lines.append(f"| {c.name} | .2f | {c.rating} | {c.review_count} |")
        
        if result.pain_points:
            lines.extend(["", "## 😤 Competitor Pain Points", ""])
            for i, pain in enumerate(result.pain_points, 1):
                lines.append(f"**{i}. {pain.description}** (Frequency: {pain.frequency})")
        
        if result.diff_opportunities:
            lines.extend(["", "## 💡 Differentiation Opportunities", ""])
            for i, opp in enumerate(result.diff_opportunities[:5], 1):
                lines.append(f"**{i}. [{opp.angle.value}]** {opp.opportunity}")
                lines.append(f"   Action: {opp.action}")
        
        if result.level != AnalysisLevel.L4:
            lines.extend(["", f"🔍 **Want deeper analysis?** {result.next_level_hint}"])
        
        lines.extend(["", result.summary])
    
    return "\n".join(lines)


# ============================================================
# CLI
# ============================================================

def main():
    lang = "zh" if "--zh" in sys.argv else "en"
    
    # DemoData
    my_product = ProductInfo(
        name="My Wireless Earbuds Pro",
        asin="B08MYASIN1",
        price=49.99,
        rating=4.3,
        review_count=150,
        features=["ANC", "30h battery", "Waterproof"],
        is_mine=True,
    )
    
    competitors = [
        ProductInfo(name="Competitor A Earbuds", asin="B08COMP1", price=59.99, rating=4.1, review_count=500),
        ProductInfo(name="Competitor B Earbuds", asin="B08COMP2", price=39.99, rating=4.5, review_count=1200),
        ProductInfo(name="Competitor C Earbuds", asin="B08COMP3", price=45.99, rating=3.9, review_count=300),
    ]
    
    competitor_reviews = ReviewData(
        negative=[
            "The quality is poor, broke after 2 weeks",
            "Sound quality is bad, very cheap feeling",
            "Doesn't fit well, keeps falling out",
            "Battery life is terrible, only lasts 2 hours",
            "Charging case stopped working after a month",
            "Too expensive for this quality",
            "Bluetooth keeps disconnecting",
        ]
    )
    
    my_reviews = ReviewData(
        positive=[
            "Great sound quality, very clear!",
            "Battery lasts forever, love it",
            "Perfect fit, stays in my ears during workout",
            "Excellent value for money, recommend!",
            "Fast shipping, well packaged",
        ]
    )
    
    result = analyze(my_product, competitors, competitor_reviews, my_reviews)
    print(format_report(result, lang))


if __name__ == "__main__":
    main()

ClawHub Marketing Product+2

Product Differentiation Shopify

Skill

Shopify/DTC product differentiation strategy tool. Analyze competitor stores, extract pain points from reviews, identify brand positioning opportunities, and...

---
name: product-differentiation-shopify
version: 1.0.0
author: Nexscope AI
description: "Shopify/DTC product differentiation strategy tool. Analyze competitor stores, extract pain points from reviews, identify brand positioning opportunities, and generate actionable differentiation strategies. Includes DTC-specific metrics like CAC, LTV, and brand story analysis. No API key required."
metadata: {"nexscope":{"emoji":"🎯","category":"ecommerce"}}
---

# Product Differentiation — Shopify/DTC 🎯

Develop winning product differentiation strategies for Shopify and DTC brands.

## Installation

```bash
npx skills add nexscope-ai/eCommerce-Skills --skill product-differentiation-shopify -g
```

## Features

- **Competitor Matrix** — Side-by-side store comparison
- **Pain Point Mining** — Extract issues from competitor reviews
- **USP Extraction** — Identify brand differentiators
- **Brand Positioning** — Market positioning strategy
- **Value Proposition** — Unique value messaging
- **Action Plan** — Prioritized improvement roadmap

## DTC-Specific Analysis

| Dimension | Method | Output |
|-----------|--------|--------|
| Brand Story | Narrative analysis | Story gaps |
| Price Position | Price-value mapping | Positioning quadrant |
| Visual Identity | Design comparison | Differentiation opportunities |
| Social Proof | Review/UGC analysis | Trust signals |
| Ad Creative | Ad copy analysis | Messaging gaps |

## Progressive Analysis Levels

| Level | Required Data | Unlocked Analysis |
|-------|---------------|-------------------|
| **L1 Basic** | Store info | Basic comparison matrix |
| **L2 Pain Points** | + Competitor reviews | Pain point analysis |
| **L3 USP** | + Your reviews | Selling point extraction |
| **L4 Complete** | + Ad/social data | Full strategy & action plan |

## Usage

### Interactive Mode

```bash
python3 scripts/analyzer.py
```

### With Parameters

```bash
python3 scripts/analyzer.py '{
  "your_store": "yourbrand.com",
  "competitors": ["competitor1.com", "competitor2.com"],
  "category": "Skincare"
}'
```

## Output Example

```
🎯 Shopify/DTC Differentiation Report

Brand: YourBrand
Category: Skincare
Competitors Analyzed: 3

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 COMPETITOR COMPARISON

Attribute       | You  | Comp A | Comp B | Comp C
─────────────────────────────────────────────────
Price Point     | $$   | $$$    | $      | $$
Brand Story     | ⭐⭐  | ⭐⭐⭐  | ⭐     | ⭐⭐
Social Proof    | 500  | 2000   | 100    | 800
Free Shipping   | $50+ | $75+   | $25+   | None
Subscription    | ✅   | ✅     | ❌     | ✅

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

😤 TOP PAIN POINTS (competitor reviews)

1. 🔴 Expensive shipping (mentioned 42x)
2. 🔴 Slow delivery (mentioned 35x)
3. 🟡 Inconsistent quality (mentioned 22x)
4. 🟡 Poor customer service (mentioned 18x)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✨ DIFFERENTIATION OPPORTUNITIES

1. ⭐ Lower free shipping threshold
2. ⭐ Stronger brand story/mission
3. ⭐ Better customer service messaging
4. ⭐ Quality guarantee program

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 ACTION PLAN

Priority | Action                    | Impact
─────────────────────────────────────────────
HIGH     | Revamp brand story page   | +20% CVR
HIGH     | Add quality guarantee     | +15% trust
MEDIUM   | Lower free ship threshold | +10% AOV
LOW      | Launch referral program   | +5% LTV
```

## DTC Strategy Framework

```
Competitor Store Analysis
      ↓
Review & UGC Mining
      ↓
Brand Story Gap Analysis
      ↓
Value Proposition Development
      ↓
Positioning Strategy
      ↓
Action Plan
```

---

**Part of [Nexscope AI](https://www.nexscope.ai/) — AI tools for e-commerce sellers.**

FILE:scripts/analyzer.py
#!/usr/bin/env python3
"""
Product Differentiation Analyzer - Core Engine
ProductDifferenceAnalyze - Core Engine

Features:
- CompetitorFeatureComparisonMatrix
- CompetitorNegative ReviewPain pointMining
- Positive ReviewSelling point extraction
- Difference angleDegreeIdentify
- MarketPositioningStrategy
- PricingStrategyRecommendation
- MarketingSelling pointRecommendation
- ProductImproveRecommendation

SupportProgressiveAnalyze:
L1: BasicComparison (ProductInformation)
L2: Pain pointAnalyze (+ CompetitorNegative Review)
L3: Selling point extraction (+ SelfPositive Review)
L4: CompleteStrategy (+ MarketData)

Version: 1.0.0
"""

import json
from dataclasses import dataclass, field
from typing import List, Dict, Optional, Tuple
from enum import Enum
from datetime import datetime
import sys
import re
from collections import Counter


class AnalysisLevel(Enum):
    """AnalyzelayerLevel"""
    L1 = "L1"  # BasicComparison
    L2 = "L2"  # Pain pointAnalyze
    L3 = "L3"  # Selling point extraction
    L4 = "L4"  # CompleteStrategy


class DiffAngle(Enum):
    """Difference angleDegree"""
    FUNCTION = "function"       # FeatureDifference
    QUALITY = "quality"         # QualityDifference
    DESIGN = "design"           # Design difference
    PRICE = "price"             # PriceDifference
    SERVICE = "service"         # Service difference
    AUDIENCE = "audience"       # Audience difference
    SCENARIO = "scenario"       # Scenario difference
    BRAND = "brand"             # BrandDifference


# ============================================================
# Pain pointKeywordsLibrary
# ============================================================

PAIN_POINT_KEYWORDS = {
    "quality": {
        "en": ["cheap", "broke", "broken", "flimsy", "poor quality", "fell apart", "defective", "doesn't last", "stopped working"],
        "zh": ["Poor quality", " bad  ", "Fragile", "Poor workmanship", "Not durable", "StopWork"],
    },
    "function": {
        "en": ["doesn't work", "not working", "malfunction", "missing feature", "can't", "won't", "failed", "useless"],
        "zh": ["notWork", "Fault", "FeatureMissing", "Cannot", "Failed", "Useless"],
    },
    "design": {
        "en": ["ugly", "looks cheap", "bulky", "heavy", "uncomfortable", "awkward", "hard to use", "confusing"],
        "zh": ["ugly", "Looks cheap", "clumsy heavy ", " heavy ", "Uncomfortable", "Hard to use", "Complex"],
    },
    "size": {
        "en": ["too small", "too big", "wrong size", "doesn't fit", "smaller than expected", "bigger than"],
        "zh": [" too  small ", " too  big ", "Sizenot for ", "Not suitable"],
    },
    "shipping": {
        "en": ["late", "damaged", "wrong item", "missing parts", "packaging"],
        "zh": ["late to ", "loss bad ", "Sent wrong", "Missing parts", "Packaging"],
    },
    "value": {
        "en": ["overpriced", "not worth", "waste of money", "rip off", "too expensive"],
        "zh": [" too expensive", "notValue", "Waste money", "trap"],
    },
}

SELLING_POINT_KEYWORDS = {
    "quality": {
        "en": ["solid", "sturdy", "durable", "well made", "high quality", "premium", "excellent", "perfect"],
        "zh": ["Sturdy", "Durable", "Workmanship good ", "HighQuality", "Quality", "Perfect"],
    },
    "function": {
        "en": ["works great", "works perfectly", "easy to use", "convenient", "efficient", "powerful", "fast"],
        "zh": [" good use", "Convenient", "Higheffect", "strong big ", " fast "],
    },
    "design": {
        "en": ["beautiful", "sleek", "stylish", "modern", "compact", "lightweight", "elegant"],
        "zh": ["Beautiful", "Timeyet", "Modern", " small clever", " light easy", "Elegant"],
    },
    "value": {
        "en": ["great value", "worth it", "good price", "affordable", "best purchase", "recommend"],
        "zh": ["Value ", "Value for money", "Recommended", "Worth it"],
    },
    "service": {
        "en": ["great service", "fast shipping", "well packaged", "responsive seller"],
        "zh": ["Service good ", "Shipping fast ", "Packaging good ", "SellerResponse fast "],
    },
}


# ============================================================
# Data Structures
# ============================================================

@dataclass
class ProductInfo:
    """ProductInformation"""
    name: str = ""
    asin: str = ""
    price: float = 0.0
    rating: float = 0.0
    review_count: int = 0
    features: List[str] = field(default_factory=list)
    bullet_points: List[str] = field(default_factory=list)
    category: str = ""
    brand: str = ""
    is_mine: bool = False


@dataclass
class ReviewData:
    """Review Countdata"""
    positive: List[str] = field(default_factory=list)  # Positive Review
    negative: List[str] = field(default_factory=list)  # Negative Review
    neutral: List[str] = field(default_factory=list)   # Neutral review


@dataclass
class PainPoint:
    """Pain point"""
    category: str
    description: str
    description_zh: str
    frequency: int
    severity: str  # high/medium/low
    example_reviews: List[str] = field(default_factory=list)


@dataclass
class SellingPoint:
    """Selling point"""
    category: str
    description: str
    description_zh: str
    frequency: int
    strength: str  # strong/medium/weak
    example_reviews: List[str] = field(default_factory=list)


@dataclass
class DiffOpportunity:
    """Differentiation Opportunities"""
    angle: DiffAngle
    opportunity: str
    opportunity_zh: str
    priority: str  # high/medium/low
    action: str
    action_zh: str
    potential_impact: str


@dataclass
class PositioningStrategy:
    """PositioningStrategy"""
    position_type: str  # premium/value/niche/innovation
    target_audience: str
    target_audience_zh: str
    price_strategy: str
    price_strategy_zh: str
    key_message: str
    key_message_zh: str
    marketing_angles: List[str] = field(default_factory=list)


@dataclass
class AnalysisResult:
    """AnalyzeResult"""
    level: AnalysisLevel
    my_product: ProductInfo
    competitors: List[ProductInfo]
    comparison_matrix: Dict
    pain_points: List[PainPoint]
    selling_points: List[SellingPoint]
    diff_opportunities: List[DiffOpportunity]
    positioning: Optional[PositioningStrategy]
    action_items: List[Dict]
    next_level_hint: str
    next_level_hint_zh: str
    summary: str
    summary_zh: str


# ============================================================
# AnalyzeFunction
# ============================================================

def extract_pain_points(reviews: List[str], lang: str = "en") -> List[PainPoint]:
    """ from Negative Review in ExtractPain point"""
    pain_points = []
    category_counts = Counter()
    category_examples = {}
    
    for review in reviews:
        review_lower = review.lower()
        for category, keywords in PAIN_POINT_KEYWORDS.items():
            for keyword in keywords.get(lang, []) + keywords.get("en", []):
                if keyword.lower() in review_lower:
                    category_counts[category] += 1
                    if category not in category_examples:
                        category_examples[category] = []
                    if len(category_examples[category]) < 3:
                        category_examples[category].append(review[:100])
                    break
    
    category_names = {
        "quality": ("Quality Issues", "QualityIssue"),
        "function": ("Functionality Problems", "FeatureIssue"),
        "design": ("Design Flaws", "Design defect"),
        "size": ("Size/Fit Issues", "SizeIssue"),
        "shipping": ("Shipping/Packaging", "LogisticsPackaging"),
        "value": ("Value Concerns", "Value for money"),
    }
    
    for category, count in category_counts.most_common():
        if count >= 1:
            severity = "high" if count >= 5 else "medium" if count >= 2 else "low"
            names = category_names.get(category, (category.title(), category))
            pain_points.append(PainPoint(
                category=category,
                description=names[0],
                description_zh=names[1],
                frequency=count,
                severity=severity,
                example_reviews=category_examples.get(category, []),
            ))
    
    return pain_points


def extract_selling_points(reviews: List[str], lang: str = "en") -> List[SellingPoint]:
    """ from Positive ReviewExtract selling points from"""
    selling_points = []
    category_counts = Counter()
    category_examples = {}
    
    for review in reviews:
        review_lower = review.lower()
        for category, keywords in SELLING_POINT_KEYWORDS.items():
            for keyword in keywords.get(lang, []) + keywords.get("en", []):
                if keyword.lower() in review_lower:
                    category_counts[category] += 1
                    if category not in category_examples:
                        category_examples[category] = []
                    if len(category_examples[category]) < 3:
                        category_examples[category].append(review[:100])
                    break
    
    category_names = {
        "quality": ("Build Quality", "WorkmanshipQuality"),
        "function": ("Functionality", "Featurenature"),
        "design": ("Design & Aesthetics", "Beautiful design"),
        "value": ("Value for Money", "Value for money"),
        "service": ("Service & Shipping", "ServiceLogistics"),
    }
    
    for category, count in category_counts.most_common():
        if count >= 1:
            strength = "strong" if count >= 5 else "medium" if count >= 2 else "weak"
            names = category_names.get(category, (category.title(), category))
            selling_points.append(SellingPoint(
                category=category,
                description=names[0],
                description_zh=names[1],
                frequency=count,
                strength=strength,
                example_reviews=category_examples.get(category, []),
            ))
    
    return selling_points


def build_comparison_matrix(my_product: ProductInfo, competitors: List[ProductInfo]) -> Dict:
    """BuildComparisonMatrix"""
    matrix = {
        "products": [my_product.name] + [c.name for c in competitors],
        "prices": [my_product.price] + [c.price for c in competitors],
        "ratings": [my_product.rating] + [c.rating for c in competitors],
        "review_counts": [my_product.review_count] + [c.review_count for c in competitors],
    }
    
    # PricePositioning
    all_prices = [p for p in matrix["prices"] if p > 0]
    if all_prices:
        avg_price = sum(all_prices) / len(all_prices)
        matrix["price_position"] = "above_avg" if my_product.price > avg_price else "below_avg"
        matrix["avg_price"] = avg_price
    
    # RatingPositioning
    all_ratings = [r for r in matrix["ratings"] if r > 0]
    if all_ratings:
        avg_rating = sum(all_ratings) / len(all_ratings)
        matrix["rating_position"] = "above_avg" if my_product.rating > avg_rating else "below_avg"
        matrix["avg_rating"] = avg_rating
    
    return matrix


def identify_opportunities(
    my_product: ProductInfo,
    competitors: List[ProductInfo],
    pain_points: List[PainPoint],
    selling_points: List[SellingPoint],
    matrix: Dict
) -> List[DiffOpportunity]:
    """IdentifyDifferentiation Opportunities"""
    opportunities = []
    
    # 1. Based onCompetitorPain pointOpportunity
    for pain in pain_points:
        if pain.severity == "high":
            opp = DiffOpportunity(
                angle=DiffAngle.FUNCTION if pain.category == "function" else DiffAngle.QUALITY,
                opportunity=f"Address competitor weakness: {pain.description}",
                opportunity_zh=f"SolveCompetitorWeakness: {pain.description_zh}",
                priority="high",
                action=f"Improve {pain.category} and highlight in marketing",
                action_zh=f"Improve{pain.description_zh}and in Marketing in Highlight",
                potential_impact="High - directly addresses customer pain",
            )
            opportunities.append(opp)
    
    # 2. Based onPriceOpportunity
    if matrix.get("price_position") == "below_avg":
        opportunities.append(DiffOpportunity(
            angle=DiffAngle.PRICE,
            opportunity="Value positioning - lower price than competitors",
            opportunity_zh="Value for moneyPositioning - Price low  at Competitor",
            priority="medium",
            action="Emphasize value proposition in marketing",
            action_zh=" in Marketing in EmphasizeValue for money",
            potential_impact="Medium - price-sensitive customers",
        ))
    elif matrix.get("price_position") == "above_avg":
        opportunities.append(DiffOpportunity(
            angle=DiffAngle.PRICE,
            opportunity="Premium positioning - justify higher price",
            opportunity_zh="PremiumPositioning - ProofHigherPriceReasonable",
            priority="high",
            action="Highlight premium features and quality",
            action_zh="HighlightPremiumFeatureAndQuality",
            potential_impact="High - must justify price premium",
        ))
    
    # 3. Based onRatingOpportunity
    if matrix.get("rating_position") == "above_avg":
        opportunities.append(DiffOpportunity(
            angle=DiffAngle.QUALITY,
            opportunity="Quality leader - leverage higher rating",
            opportunity_zh="Qualitylead first  - UtilizeHigherRating",
            priority="high",
            action="Display rating prominently, collect more reviews",
            action_zh="HighlightDisplayRating，Collect more  many Review",
            potential_impact="High - social proof advantage",
        ))
    
    # 4. SegmentMarketOpportunity
    opportunities.append(DiffOpportunity(
        angle=DiffAngle.AUDIENCE,
        opportunity="Niche targeting - focus on specific user segment",
        opportunity_zh="SegmentPositioning - Focus on specificUserGroup",
        priority="medium",
        action="Identify underserved segment and tailor product/marketing",
        action_zh="IdentifyUnmetSegmentMarket，CustomProduct/Marketing",
        potential_impact="Medium - reduced competition in niche",
    ))
    
    return opportunities


def generate_positioning(
    my_product: ProductInfo,
    matrix: Dict,
    opportunities: List[DiffOpportunity]
) -> PositioningStrategy:
    """GeneratePositioningStrategy"""
    
    # ConfirmPositioningCategoryType
    price_pos = matrix.get("price_position", "below_avg")
    rating_pos = matrix.get("rating_position", "below_avg")
    
    if price_pos == "above_avg" and rating_pos == "above_avg":
        position_type = "premium"
        target = "Quality-conscious buyers willing to pay more"
        target_zh = "Willing for QualityPayPremiumUser"
        price_strategy = "Maintain premium pricing, bundle with extras"
        price_strategy_zh = "MaintainPremiumPricing，Bundle increaseValueService"
        key_message = "The premium choice for discerning customers"
        key_message_zh = "PremiumUserSmart choice"
    elif price_pos == "below_avg":
        position_type = "value"
        target = "Price-sensitive buyers seeking good deals"
        target_zh = "FindHighValue for moneyPriceSensitiveUser"
        price_strategy = "Competitive pricing, volume-focused"
        price_strategy_zh = "CompetitivePricing，Pursue sales volume"
        key_message = "Same quality, better price"
        key_message_zh = "same etcQuality， more excellentPrice"
    else:
        position_type = "balanced"
        target = "Mainstream buyers seeking reliable products"
        target_zh = "FindCanrelyProductMainflowUser"
        price_strategy = "Market-aligned pricing"
        price_strategy_zh = "MarketPricing"
        key_message = "The trusted choice"
        key_message_zh = "ValueTrustedChoice"
    
    marketing_angles = [
        f"[{opp.angle.value.upper()}] {opp.opportunity}" 
        for opp in opportunities[:3] if opp.priority == "high"
    ]
    
    return PositioningStrategy(
        position_type=position_type,
        target_audience=target,
        target_audience_zh=target_zh,
        price_strategy=price_strategy,
        price_strategy_zh=price_strategy_zh,
        key_message=key_message,
        key_message_zh=key_message_zh,
        marketing_angles=marketing_angles,
    )


def generate_action_items(
    opportunities: List[DiffOpportunity],
    pain_points: List[PainPoint],
    positioning: PositioningStrategy
) -> List[Dict]:
    """GenerateActionRecommendation"""
    actions = []
    
    # ProductImprove
    for pain in pain_points[:2]:
        if pain.severity in ["high", "medium"]:
            actions.append({
                "category": "Product",
                "category_zh": "Product",
                "action": f"Address {pain.description}",
                "action_zh": f"Solve{pain.description_zh}",
                "priority": "P1" if pain.severity == "high" else "P2",
                "timeline": "1-3 months",
            })
    
    # MarketingImprove
    for opp in opportunities[:2]:
        if opp.priority == "high":
            actions.append({
                "category": "Marketing",
                "category_zh": "Marketing",
                "action": opp.action,
                "action_zh": opp.action_zh,
                "priority": "P1",
                "timeline": "Immediate",
            })
    
    # PositioningRelated
    actions.append({
        "category": "Positioning",
        "category_zh": "Positioning",
        "action": f"Adopt {positioning.position_type} positioning strategy",
        "action_zh": f"Adopt{positioning.position_type}PositioningStrategy",
        "priority": "P1",
        "timeline": "Ongoing",
    })
    
    return actions


def determine_level(
    my_product: ProductInfo,
    competitors: List[ProductInfo],
    competitor_reviews: ReviewData,
    my_reviews: ReviewData
) -> AnalysisLevel:
    """ConfirmAnalyzelayerLevel"""
    has_products = my_product.name and len(competitors) > 0
    has_competitor_reviews = len(competitor_reviews.negative) > 0
    has_my_reviews = len(my_reviews.positive) > 0
    has_market_data = my_product.price > 0 and my_product.rating > 0
    
    if has_products and has_competitor_reviews and has_my_reviews and has_market_data:
        return AnalysisLevel.L4
    elif has_products and has_competitor_reviews and has_my_reviews:
        return AnalysisLevel.L3
    elif has_products and has_competitor_reviews:
        return AnalysisLevel.L2
    else:
        return AnalysisLevel.L1


def analyze(
    my_product: ProductInfo,
    competitors: List[ProductInfo],
    competitor_reviews: ReviewData = None,
    my_reviews: ReviewData = None,
) -> AnalysisResult:
    """MainAnalyzeFunction"""
    
    if competitor_reviews is None:
        competitor_reviews = ReviewData()
    if my_reviews is None:
        my_reviews = ReviewData()
    
    # ConfirmAnalyzelayerLevel
    level = determine_level(my_product, competitors, competitor_reviews, my_reviews)
    
    # BuildComparisonMatrix
    matrix = build_comparison_matrix(my_product, competitors)
    
    # ExtractPain point (L2+)
    pain_points = []
    if level.value >= AnalysisLevel.L2.value:
        pain_points = extract_pain_points(competitor_reviews.negative)
    
    # Extract selling points (L3+)
    selling_points = []
    if level.value >= AnalysisLevel.L3.value:
        selling_points = extract_selling_points(my_reviews.positive)
    
    # IdentifyDifferentiation Opportunities
    opportunities = identify_opportunities(my_product, competitors, pain_points, selling_points, matrix)
    
    # GeneratePositioningStrategy (L4)
    positioning = None
    if level == AnalysisLevel.L4:
        positioning = generate_positioning(my_product, matrix, opportunities)
    
    # GenerateActionRecommendation
    action_items = generate_action_items(opportunities, pain_points, positioning or PositioningStrategy(
        position_type="balanced", target_audience="", target_audience_zh="",
        price_strategy="", price_strategy_zh="", key_message="", key_message_zh=""
    ))
    
    #  below oneLevelHint
    hints = {
        AnalysisLevel.L1: ("Add competitor negative reviews for pain point analysis", "AddCompetitorNegative Review to ProceedPain pointAnalyze"),
        AnalysisLevel.L2: ("Add your product's positive reviews for selling point extraction", "AddyouProductPositive ReviewTo extract selling points"),
        AnalysisLevel.L3: ("Add price and rating data for complete positioning strategy", "AddPriceAndRatingDataTo obtainCompletePositioningStrategy"),
        AnalysisLevel.L4: ("Full analysis complete!", "CompleteAnalyze already Complete！"),
    }
    next_hint, next_hint_zh = hints[level]
    
    # Summary
    summary = f"Level {level.value} Analysis | {len(opportunities)} opportunities | {len(pain_points)} pain points identified"
    summary_zh = f"{level.value} LevelAnalyze | {len(opportunities)} Differentiation Opportunities | {len(pain_points)} Pain pointIdentify"
    
    return AnalysisResult(
        level=level,
        my_product=my_product,
        competitors=competitors,
        comparison_matrix=matrix,
        pain_points=pain_points,
        selling_points=selling_points,
        diff_opportunities=opportunities,
        positioning=positioning,
        action_items=action_items,
        next_level_hint=next_hint,
        next_level_hint_zh=next_hint_zh,
        summary=summary,
        summary_zh=summary_zh,
    )


# ============================================================
# OutputFormat
# ============================================================

def format_report(result: AnalysisResult, lang: str = "en") -> str:
    """FormatReport"""
    
    if lang == "zh":
        lines = [
            "🎯 **ProductDifferenceAnalyzeReport**",
            "",
            f"**AnalyzelayerLevel**: {result.level.value}",
            f"**IProduct**: {result.my_product.name}",
            f"**CompetitorQuantity**: {len(result.competitors)}",
            "",
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            "## 📊 CompetitorComparisonMatrix",
            "",
        ]
        
        # ComparisonTable
        lines.append("| Product | Price | Rating | Review Count |")
        lines.append("|------|------|------|--------|")
        lines.append(f"| **{result.my_product.name}** (I) | .2f | {result.my_product.rating} | {result.my_product.review_count} |")
        for c in result.competitors:
            lines.append(f"| {c.name} | .2f | {c.rating} | {c.review_count} |")
        
        if result.pain_points:
            lines.extend([
                "",
                "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
                "",
                "## 😤 CompetitorPain point (Differentiation Opportunities)",
                "",
            ])
            for i, pain in enumerate(result.pain_points, 1):
                severity_icon = "🔴" if pain.severity == "high" else "🟡" if pain.severity == "medium" else "🟢"
                lines.append(f"**{i}. {pain.description_zh}** {severity_icon}")
                lines.append(f"   Occurrence frequency: {pain.frequency} | CriticalprocessDegree: {pain.severity}")
                if pain.example_reviews:
                    lines.append(f"   Example: \"{pain.example_reviews[0][:50]}...\"")
                lines.append("")
        
        if result.selling_points:
            lines.extend([
                "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
                "",
                "## ✨ My selling point",
                "",
            ])
            for i, sp in enumerate(result.selling_points, 1):
                strength_icon = "💪" if sp.strength == "strong" else "👍" if sp.strength == "medium" else "👌"
                lines.append(f"**{i}. {sp.description_zh}** {strength_icon}")
                lines.append(f"   Occurrence frequency: {sp.frequency}")
                lines.append("")
        
        lines.extend([
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            "## 💡 Differentiation Opportunities",
            "",
        ])
        for i, opp in enumerate(result.diff_opportunities[:5], 1):
            priority_icon = "🔴" if opp.priority == "high" else "🟡"
            lines.append(f"**{i}. [{opp.angle.value.upper()}] {opp.opportunity_zh}** {priority_icon}")
            lines.append(f"   Action: {opp.action_zh}")
            lines.append("")
        
        if result.positioning:
            lines.extend([
                "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
                "",
                "## 🎯 PositioningStrategy",
                "",
                f"**PositioningCategoryType**: {result.positioning.position_type.upper()}",
                f"**Target audience**: {result.positioning.target_audience_zh}",
                f"**PriceStrategy**: {result.positioning.price_strategy_zh}",
                f"**CoreInformation**: {result.positioning.key_message_zh}",
                "",
            ])
        
        lines.extend([
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            "## 📋 Action Plan",
            "",
        ])
        for action in result.action_items[:5]:
            lines.append(f"**[{action['priority']}] [{action['category_zh']}]** {action['action_zh']}")
            lines.append(f"   Timeline: {action['timeline']}")
            lines.append("")
        
        if result.level != AnalysisLevel.L4:
            lines.extend([
                "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
                "",
                f"🔍 **Want to go deeperAnalyze？** {result.next_level_hint_zh}",
            ])
        
        lines.extend([
            "",
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            result.summary_zh,
        ])
    else:
        # English version (similar structure)
        lines = [
            "🎯 **Product Differentiation Analysis Report**",
            "",
            f"**Analysis Level**: {result.level.value}",
            f"**My Product**: {result.my_product.name}",
            f"**Competitors**: {len(result.competitors)}",
            "",
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            "## 📊 Comparison Matrix",
            "",
            "| Product | Price | Rating | Reviews |",
            "|---------|-------|--------|---------|",
            f"| **{result.my_product.name}** (Mine) | .2f | {result.my_product.rating} | {result.my_product.review_count} |",
        ]
        for c in result.competitors:
            lines.append(f"| {c.name} | .2f | {c.rating} | {c.review_count} |")
        
        if result.pain_points:
            lines.extend(["", "## 😤 Competitor Pain Points", ""])
            for i, pain in enumerate(result.pain_points, 1):
                lines.append(f"**{i}. {pain.description}** (Frequency: {pain.frequency})")
        
        if result.diff_opportunities:
            lines.extend(["", "## 💡 Differentiation Opportunities", ""])
            for i, opp in enumerate(result.diff_opportunities[:5], 1):
                lines.append(f"**{i}. [{opp.angle.value}]** {opp.opportunity}")
                lines.append(f"   Action: {opp.action}")
        
        if result.level != AnalysisLevel.L4:
            lines.extend(["", f"🔍 **Want deeper analysis?** {result.next_level_hint}"])
        
        lines.extend(["", result.summary])
    
    return "\n".join(lines)


# ============================================================
# CLI
# ============================================================

def main():
    lang = "zh" if "--zh" in sys.argv else "en"
    
    # DemoData
    my_product = ProductInfo(
        name="My Wireless Earbuds Pro",
        asin="B08MYASIN1",
        price=49.99,
        rating=4.3,
        review_count=150,
        features=["ANC", "30h battery", "Waterproof"],
        is_mine=True,
    )
    
    competitors = [
        ProductInfo(name="Competitor A Earbuds", asin="B08COMP1", price=59.99, rating=4.1, review_count=500),
        ProductInfo(name="Competitor B Earbuds", asin="B08COMP2", price=39.99, rating=4.5, review_count=1200),
        ProductInfo(name="Competitor C Earbuds", asin="B08COMP3", price=45.99, rating=3.9, review_count=300),
    ]
    
    competitor_reviews = ReviewData(
        negative=[
            "The quality is poor, broke after 2 weeks",
            "Sound quality is bad, very cheap feeling",
            "Doesn't fit well, keeps falling out",
            "Battery life is terrible, only lasts 2 hours",
            "Charging case stopped working after a month",
            "Too expensive for this quality",
            "Bluetooth keeps disconnecting",
        ]
    )
    
    my_reviews = ReviewData(
        positive=[
            "Great sound quality, very clear!",
            "Battery lasts forever, love it",
            "Perfect fit, stays in my ears during workout",
            "Excellent value for money, recommend!",
            "Fast shipping, well packaged",
        ]
    )
    
    result = analyze(my_product, competitors, competitor_reviews, my_reviews)
    print(format_report(result, lang))


if __name__ == "__main__":
    main()

Product Differentiation Ebay

Skill

eBay product differentiation strategy tool. Analyze competitor weaknesses, extract pain points from negative feedback, identify unique selling points, and ge...

---
name: product-differentiation-ebay
version: 1.0.0
author: Nexscope AI
description: "eBay product differentiation strategy tool. Analyze competitor weaknesses, extract pain points from negative feedback, identify unique selling points, and generate actionable differentiation strategies. Includes eBay-specific seller feedback analysis. No API key required."
metadata: {"nexscope":{"emoji":"🎯","category":"ecommerce"}}
---

# Product Differentiation — eBay 🎯

Develop winning product differentiation strategies for eBay marketplace.

## Installation

```bash
npx skills add nexscope-ai/eCommerce-Skills --skill product-differentiation-ebay -g
```

## Features

- **Competitor Matrix** — Side-by-side listing comparison
- **Pain Point Mining** — Extract issues from negative feedback
- **USP Extraction** — Identify selling points from positive feedback
- **Differentiation Opportunities** — Find gaps in the market
- **Positioning Strategy** — Market positioning recommendations
- **Action Plan** — Prioritized improvement roadmap

## eBay-Specific Analysis

| Dimension | Method | Output |
|-----------|--------|--------|
| Seller Feedback | Feedback score analysis | Trust signals |
| Item Specifics | Attribute comparison | Missing features |
| Shipping Options | Delivery comparison | Speed advantage |
| Return Policy | Policy comparison | Buyer confidence |
| Best Offer | Price flexibility | Negotiation edge |

## Progressive Analysis Levels

| Level | Required Data | Unlocked Analysis |
|-------|---------------|-------------------|
| **L1 Basic** | Listing info | Basic comparison matrix |
| **L2 Pain Points** | + Competitor feedback | Pain point analysis |
| **L3 USP** | + Your feedback | Selling point extraction |
| **L4 Complete** | + Market data | Full strategy & action plan |

## Usage

### Interactive Mode

```bash
python3 scripts/analyzer.py
```

### With Parameters

```bash
python3 scripts/analyzer.py '{
  "your_item_id": "123456789012",
  "competitor_ids": ["234567890123", "345678901234"],
  "category": "Consumer Electronics"
}'
```

## Output Example

```
🎯 eBay Product Differentiation Report

Listing: Wireless Earbuds Pro
Category: Consumer Electronics
Competitors Analyzed: 3

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 COMPETITOR COMPARISON

Attribute       | You  | Comp A | Comp B | Comp C
─────────────────────────────────────────────────
Price           | $45  | $40    | $50    | $38
Shipping        | Free | $5     | Free   | Free
Returns         | 30d  | 14d    | 30d    | None
Feedback Score  | 99%  | 97%    | 98%    | 95%
Best Offer      | ✅   | ❌     | ✅     | ❌

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

😤 TOP PAIN POINTS

1. 🔴 Slow shipping (mentioned 38x)
2. 🔴 Item not as described (mentioned 25x)
3. 🟡 Poor packaging (mentioned 18x)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✨ YOUR ADVANTAGES

1. ⭐ Higher feedback score (99%)
2. ⭐ Free shipping included
3. ⭐ Best Offer enabled

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 ACTION PLAN

Priority | Action                    | Impact
─────────────────────────────────────────────
HIGH     | Highlight fast shipping   | +12% CVR
HIGH     | Add more item photos      | +8% CVR
MEDIUM   | Extend return policy      | +5% trust
```

---

**Part of [Nexscope AI](https://www.nexscope.ai/) — AI tools for e-commerce sellers.**

FILE:scripts/analyzer.py
#!/usr/bin/env python3
"""
Product Differentiation Analyzer - Core Engine
ProductDifferenceAnalyze - Core Engine

Features:
- CompetitorFeatureComparisonMatrix
- CompetitorNegative ReviewPain pointMining
- Positive ReviewSelling point extraction
- Difference angleDegreeIdentify
- MarketPositioningStrategy
- PricingStrategyRecommendation
- MarketingSelling pointRecommendation
- ProductImproveRecommendation

SupportProgressiveAnalyze:
L1: BasicComparison (ProductInformation)
L2: Pain pointAnalyze (+ CompetitorNegative Review)
L3: Selling point extraction (+ SelfPositive Review)
L4: CompleteStrategy (+ MarketData)

Version: 1.0.0
"""

import json
from dataclasses import dataclass, field
from typing import List, Dict, Optional, Tuple
from enum import Enum
from datetime import datetime
import sys
import re
from collections import Counter


class AnalysisLevel(Enum):
    """AnalyzelayerLevel"""
    L1 = "L1"  # BasicComparison
    L2 = "L2"  # Pain pointAnalyze
    L3 = "L3"  # Selling point extraction
    L4 = "L4"  # CompleteStrategy


class DiffAngle(Enum):
    """Difference angleDegree"""
    FUNCTION = "function"       # FeatureDifference
    QUALITY = "quality"         # QualityDifference
    DESIGN = "design"           # Design difference
    PRICE = "price"             # PriceDifference
    SERVICE = "service"         # Service difference
    AUDIENCE = "audience"       # Audience difference
    SCENARIO = "scenario"       # Scenario difference
    BRAND = "brand"             # BrandDifference


# ============================================================
# Pain pointKeywordsLibrary
# ============================================================

PAIN_POINT_KEYWORDS = {
    "quality": {
        "en": ["cheap", "broke", "broken", "flimsy", "poor quality", "fell apart", "defective", "doesn't last", "stopped working"],
        "zh": ["Poor quality", " bad  ", "Fragile", "Poor workmanship", "Not durable", "StopWork"],
    },
    "function": {
        "en": ["doesn't work", "not working", "malfunction", "missing feature", "can't", "won't", "failed", "useless"],
        "zh": ["notWork", "Fault", "FeatureMissing", "Cannot", "Failed", "Useless"],
    },
    "design": {
        "en": ["ugly", "looks cheap", "bulky", "heavy", "uncomfortable", "awkward", "hard to use", "confusing"],
        "zh": ["ugly", "Looks cheap", "clumsy heavy ", " heavy ", "Uncomfortable", "Hard to use", "Complex"],
    },
    "size": {
        "en": ["too small", "too big", "wrong size", "doesn't fit", "smaller than expected", "bigger than"],
        "zh": [" too  small ", " too  big ", "Sizenot for ", "Not suitable"],
    },
    "shipping": {
        "en": ["late", "damaged", "wrong item", "missing parts", "packaging"],
        "zh": ["late to ", "loss bad ", "Sent wrong", "Missing parts", "Packaging"],
    },
    "value": {
        "en": ["overpriced", "not worth", "waste of money", "rip off", "too expensive"],
        "zh": [" too expensive", "notValue", "Waste money", "trap"],
    },
}

SELLING_POINT_KEYWORDS = {
    "quality": {
        "en": ["solid", "sturdy", "durable", "well made", "high quality", "premium", "excellent", "perfect"],
        "zh": ["Sturdy", "Durable", "Workmanship good ", "HighQuality", "Quality", "Perfect"],
    },
    "function": {
        "en": ["works great", "works perfectly", "easy to use", "convenient", "efficient", "powerful", "fast"],
        "zh": [" good use", "Convenient", "Higheffect", "strong big ", " fast "],
    },
    "design": {
        "en": ["beautiful", "sleek", "stylish", "modern", "compact", "lightweight", "elegant"],
        "zh": ["Beautiful", "Timeyet", "Modern", " small clever", " light easy", "Elegant"],
    },
    "value": {
        "en": ["great value", "worth it", "good price", "affordable", "best purchase", "recommend"],
        "zh": ["Value ", "Value for money", "Recommended", "Worth it"],
    },
    "service": {
        "en": ["great service", "fast shipping", "well packaged", "responsive seller"],
        "zh": ["Service good ", "Shipping fast ", "Packaging good ", "SellerResponse fast "],
    },
}


# ============================================================
# Data Structures
# ============================================================

@dataclass
class ProductInfo:
    """ProductInformation"""
    name: str = ""
    asin: str = ""
    price: float = 0.0
    rating: float = 0.0
    review_count: int = 0
    features: List[str] = field(default_factory=list)
    bullet_points: List[str] = field(default_factory=list)
    category: str = ""
    brand: str = ""
    is_mine: bool = False


@dataclass
class ReviewData:
    """Review Countdata"""
    positive: List[str] = field(default_factory=list)  # Positive Review
    negative: List[str] = field(default_factory=list)  # Negative Review
    neutral: List[str] = field(default_factory=list)   # Neutral review


@dataclass
class PainPoint:
    """Pain point"""
    category: str
    description: str
    description_zh: str
    frequency: int
    severity: str  # high/medium/low
    example_reviews: List[str] = field(default_factory=list)


@dataclass
class SellingPoint:
    """Selling point"""
    category: str
    description: str
    description_zh: str
    frequency: int
    strength: str  # strong/medium/weak
    example_reviews: List[str] = field(default_factory=list)


@dataclass
class DiffOpportunity:
    """Differentiation Opportunities"""
    angle: DiffAngle
    opportunity: str
    opportunity_zh: str
    priority: str  # high/medium/low
    action: str
    action_zh: str
    potential_impact: str


@dataclass
class PositioningStrategy:
    """PositioningStrategy"""
    position_type: str  # premium/value/niche/innovation
    target_audience: str
    target_audience_zh: str
    price_strategy: str
    price_strategy_zh: str
    key_message: str
    key_message_zh: str
    marketing_angles: List[str] = field(default_factory=list)


@dataclass
class AnalysisResult:
    """AnalyzeResult"""
    level: AnalysisLevel
    my_product: ProductInfo
    competitors: List[ProductInfo]
    comparison_matrix: Dict
    pain_points: List[PainPoint]
    selling_points: List[SellingPoint]
    diff_opportunities: List[DiffOpportunity]
    positioning: Optional[PositioningStrategy]
    action_items: List[Dict]
    next_level_hint: str
    next_level_hint_zh: str
    summary: str
    summary_zh: str


# ============================================================
# AnalyzeFunction
# ============================================================

def extract_pain_points(reviews: List[str], lang: str = "en") -> List[PainPoint]:
    """ from Negative Review in ExtractPain point"""
    pain_points = []
    category_counts = Counter()
    category_examples = {}
    
    for review in reviews:
        review_lower = review.lower()
        for category, keywords in PAIN_POINT_KEYWORDS.items():
            for keyword in keywords.get(lang, []) + keywords.get("en", []):
                if keyword.lower() in review_lower:
                    category_counts[category] += 1
                    if category not in category_examples:
                        category_examples[category] = []
                    if len(category_examples[category]) < 3:
                        category_examples[category].append(review[:100])
                    break
    
    category_names = {
        "quality": ("Quality Issues", "QualityIssue"),
        "function": ("Functionality Problems", "FeatureIssue"),
        "design": ("Design Flaws", "Design defect"),
        "size": ("Size/Fit Issues", "SizeIssue"),
        "shipping": ("Shipping/Packaging", "LogisticsPackaging"),
        "value": ("Value Concerns", "Value for money"),
    }
    
    for category, count in category_counts.most_common():
        if count >= 1:
            severity = "high" if count >= 5 else "medium" if count >= 2 else "low"
            names = category_names.get(category, (category.title(), category))
            pain_points.append(PainPoint(
                category=category,
                description=names[0],
                description_zh=names[1],
                frequency=count,
                severity=severity,
                example_reviews=category_examples.get(category, []),
            ))
    
    return pain_points


def extract_selling_points(reviews: List[str], lang: str = "en") -> List[SellingPoint]:
    """ from Positive ReviewExtract selling points from"""
    selling_points = []
    category_counts = Counter()
    category_examples = {}
    
    for review in reviews:
        review_lower = review.lower()
        for category, keywords in SELLING_POINT_KEYWORDS.items():
            for keyword in keywords.get(lang, []) + keywords.get("en", []):
                if keyword.lower() in review_lower:
                    category_counts[category] += 1
                    if category not in category_examples:
                        category_examples[category] = []
                    if len(category_examples[category]) < 3:
                        category_examples[category].append(review[:100])
                    break
    
    category_names = {
        "quality": ("Build Quality", "WorkmanshipQuality"),
        "function": ("Functionality", "Featurenature"),
        "design": ("Design & Aesthetics", "Beautiful design"),
        "value": ("Value for Money", "Value for money"),
        "service": ("Service & Shipping", "ServiceLogistics"),
    }
    
    for category, count in category_counts.most_common():
        if count >= 1:
            strength = "strong" if count >= 5 else "medium" if count >= 2 else "weak"
            names = category_names.get(category, (category.title(), category))
            selling_points.append(SellingPoint(
                category=category,
                description=names[0],
                description_zh=names[1],
                frequency=count,
                strength=strength,
                example_reviews=category_examples.get(category, []),
            ))
    
    return selling_points


def build_comparison_matrix(my_product: ProductInfo, competitors: List[ProductInfo]) -> Dict:
    """BuildComparisonMatrix"""
    matrix = {
        "products": [my_product.name] + [c.name for c in competitors],
        "prices": [my_product.price] + [c.price for c in competitors],
        "ratings": [my_product.rating] + [c.rating for c in competitors],
        "review_counts": [my_product.review_count] + [c.review_count for c in competitors],
    }
    
    # PricePositioning
    all_prices = [p for p in matrix["prices"] if p > 0]
    if all_prices:
        avg_price = sum(all_prices) / len(all_prices)
        matrix["price_position"] = "above_avg" if my_product.price > avg_price else "below_avg"
        matrix["avg_price"] = avg_price
    
    # RatingPositioning
    all_ratings = [r for r in matrix["ratings"] if r > 0]
    if all_ratings:
        avg_rating = sum(all_ratings) / len(all_ratings)
        matrix["rating_position"] = "above_avg" if my_product.rating > avg_rating else "below_avg"
        matrix["avg_rating"] = avg_rating
    
    return matrix


def identify_opportunities(
    my_product: ProductInfo,
    competitors: List[ProductInfo],
    pain_points: List[PainPoint],
    selling_points: List[SellingPoint],
    matrix: Dict
) -> List[DiffOpportunity]:
    """IdentifyDifferentiation Opportunities"""
    opportunities = []
    
    # 1. Based onCompetitorPain pointOpportunity
    for pain in pain_points:
        if pain.severity == "high":
            opp = DiffOpportunity(
                angle=DiffAngle.FUNCTION if pain.category == "function" else DiffAngle.QUALITY,
                opportunity=f"Address competitor weakness: {pain.description}",
                opportunity_zh=f"SolveCompetitorWeakness: {pain.description_zh}",
                priority="high",
                action=f"Improve {pain.category} and highlight in marketing",
                action_zh=f"Improve{pain.description_zh}and in Marketing in Highlight",
                potential_impact="High - directly addresses customer pain",
            )
            opportunities.append(opp)
    
    # 2. Based onPriceOpportunity
    if matrix.get("price_position") == "below_avg":
        opportunities.append(DiffOpportunity(
            angle=DiffAngle.PRICE,
            opportunity="Value positioning - lower price than competitors",
            opportunity_zh="Value for moneyPositioning - Price low  at Competitor",
            priority="medium",
            action="Emphasize value proposition in marketing",
            action_zh=" in Marketing in EmphasizeValue for money",
            potential_impact="Medium - price-sensitive customers",
        ))
    elif matrix.get("price_position") == "above_avg":
        opportunities.append(DiffOpportunity(
            angle=DiffAngle.PRICE,
            opportunity="Premium positioning - justify higher price",
            opportunity_zh="PremiumPositioning - ProofHigherPriceReasonable",
            priority="high",
            action="Highlight premium features and quality",
            action_zh="HighlightPremiumFeatureAndQuality",
            potential_impact="High - must justify price premium",
        ))
    
    # 3. Based onRatingOpportunity
    if matrix.get("rating_position") == "above_avg":
        opportunities.append(DiffOpportunity(
            angle=DiffAngle.QUALITY,
            opportunity="Quality leader - leverage higher rating",
            opportunity_zh="Qualitylead first  - UtilizeHigherRating",
            priority="high",
            action="Display rating prominently, collect more reviews",
            action_zh="HighlightDisplayRating，Collect more  many Review",
            potential_impact="High - social proof advantage",
        ))
    
    # 4. SegmentMarketOpportunity
    opportunities.append(DiffOpportunity(
        angle=DiffAngle.AUDIENCE,
        opportunity="Niche targeting - focus on specific user segment",
        opportunity_zh="SegmentPositioning - Focus on specificUserGroup",
        priority="medium",
        action="Identify underserved segment and tailor product/marketing",
        action_zh="IdentifyUnmetSegmentMarket，CustomProduct/Marketing",
        potential_impact="Medium - reduced competition in niche",
    ))
    
    return opportunities


def generate_positioning(
    my_product: ProductInfo,
    matrix: Dict,
    opportunities: List[DiffOpportunity]
) -> PositioningStrategy:
    """GeneratePositioningStrategy"""
    
    # ConfirmPositioningCategoryType
    price_pos = matrix.get("price_position", "below_avg")
    rating_pos = matrix.get("rating_position", "below_avg")
    
    if price_pos == "above_avg" and rating_pos == "above_avg":
        position_type = "premium"
        target = "Quality-conscious buyers willing to pay more"
        target_zh = "Willing for QualityPayPremiumUser"
        price_strategy = "Maintain premium pricing, bundle with extras"
        price_strategy_zh = "MaintainPremiumPricing，Bundle increaseValueService"
        key_message = "The premium choice for discerning customers"
        key_message_zh = "PremiumUserSmart choice"
    elif price_pos == "below_avg":
        position_type = "value"
        target = "Price-sensitive buyers seeking good deals"
        target_zh = "FindHighValue for moneyPriceSensitiveUser"
        price_strategy = "Competitive pricing, volume-focused"
        price_strategy_zh = "CompetitivePricing，Pursue sales volume"
        key_message = "Same quality, better price"
        key_message_zh = "same etcQuality， more excellentPrice"
    else:
        position_type = "balanced"
        target = "Mainstream buyers seeking reliable products"
        target_zh = "FindCanrelyProductMainflowUser"
        price_strategy = "Market-aligned pricing"
        price_strategy_zh = "MarketPricing"
        key_message = "The trusted choice"
        key_message_zh = "ValueTrustedChoice"
    
    marketing_angles = [
        f"[{opp.angle.value.upper()}] {opp.opportunity}" 
        for opp in opportunities[:3] if opp.priority == "high"
    ]
    
    return PositioningStrategy(
        position_type=position_type,
        target_audience=target,
        target_audience_zh=target_zh,
        price_strategy=price_strategy,
        price_strategy_zh=price_strategy_zh,
        key_message=key_message,
        key_message_zh=key_message_zh,
        marketing_angles=marketing_angles,
    )


def generate_action_items(
    opportunities: List[DiffOpportunity],
    pain_points: List[PainPoint],
    positioning: PositioningStrategy
) -> List[Dict]:
    """GenerateActionRecommendation"""
    actions = []
    
    # ProductImprove
    for pain in pain_points[:2]:
        if pain.severity in ["high", "medium"]:
            actions.append({
                "category": "Product",
                "category_zh": "Product",
                "action": f"Address {pain.description}",
                "action_zh": f"Solve{pain.description_zh}",
                "priority": "P1" if pain.severity == "high" else "P2",
                "timeline": "1-3 months",
            })
    
    # MarketingImprove
    for opp in opportunities[:2]:
        if opp.priority == "high":
            actions.append({
                "category": "Marketing",
                "category_zh": "Marketing",
                "action": opp.action,
                "action_zh": opp.action_zh,
                "priority": "P1",
                "timeline": "Immediate",
            })
    
    # PositioningRelated
    actions.append({
        "category": "Positioning",
        "category_zh": "Positioning",
        "action": f"Adopt {positioning.position_type} positioning strategy",
        "action_zh": f"Adopt{positioning.position_type}PositioningStrategy",
        "priority": "P1",
        "timeline": "Ongoing",
    })
    
    return actions


def determine_level(
    my_product: ProductInfo,
    competitors: List[ProductInfo],
    competitor_reviews: ReviewData,
    my_reviews: ReviewData
) -> AnalysisLevel:
    """ConfirmAnalyzelayerLevel"""
    has_products = my_product.name and len(competitors) > 0
    has_competitor_reviews = len(competitor_reviews.negative) > 0
    has_my_reviews = len(my_reviews.positive) > 0
    has_market_data = my_product.price > 0 and my_product.rating > 0
    
    if has_products and has_competitor_reviews and has_my_reviews and has_market_data:
        return AnalysisLevel.L4
    elif has_products and has_competitor_reviews and has_my_reviews:
        return AnalysisLevel.L3
    elif has_products and has_competitor_reviews:
        return AnalysisLevel.L2
    else:
        return AnalysisLevel.L1


def analyze(
    my_product: ProductInfo,
    competitors: List[ProductInfo],
    competitor_reviews: ReviewData = None,
    my_reviews: ReviewData = None,
) -> AnalysisResult:
    """MainAnalyzeFunction"""
    
    if competitor_reviews is None:
        competitor_reviews = ReviewData()
    if my_reviews is None:
        my_reviews = ReviewData()
    
    # ConfirmAnalyzelayerLevel
    level = determine_level(my_product, competitors, competitor_reviews, my_reviews)
    
    # BuildComparisonMatrix
    matrix = build_comparison_matrix(my_product, competitors)
    
    # ExtractPain point (L2+)
    pain_points = []
    if level.value >= AnalysisLevel.L2.value:
        pain_points = extract_pain_points(competitor_reviews.negative)
    
    # Extract selling points (L3+)
    selling_points = []
    if level.value >= AnalysisLevel.L3.value:
        selling_points = extract_selling_points(my_reviews.positive)
    
    # IdentifyDifferentiation Opportunities
    opportunities = identify_opportunities(my_product, competitors, pain_points, selling_points, matrix)
    
    # GeneratePositioningStrategy (L4)
    positioning = None
    if level == AnalysisLevel.L4:
        positioning = generate_positioning(my_product, matrix, opportunities)
    
    # GenerateActionRecommendation
    action_items = generate_action_items(opportunities, pain_points, positioning or PositioningStrategy(
        position_type="balanced", target_audience="", target_audience_zh="",
        price_strategy="", price_strategy_zh="", key_message="", key_message_zh=""
    ))
    
    #  below oneLevelHint
    hints = {
        AnalysisLevel.L1: ("Add competitor negative reviews for pain point analysis", "AddCompetitorNegative Review to ProceedPain pointAnalyze"),
        AnalysisLevel.L2: ("Add your product's positive reviews for selling point extraction", "AddyouProductPositive ReviewTo extract selling points"),
        AnalysisLevel.L3: ("Add price and rating data for complete positioning strategy", "AddPriceAndRatingDataTo obtainCompletePositioningStrategy"),
        AnalysisLevel.L4: ("Full analysis complete!", "CompleteAnalyze already Complete！"),
    }
    next_hint, next_hint_zh = hints[level]
    
    # Summary
    summary = f"Level {level.value} Analysis | {len(opportunities)} opportunities | {len(pain_points)} pain points identified"
    summary_zh = f"{level.value} LevelAnalyze | {len(opportunities)} Differentiation Opportunities | {len(pain_points)} Pain pointIdentify"
    
    return AnalysisResult(
        level=level,
        my_product=my_product,
        competitors=competitors,
        comparison_matrix=matrix,
        pain_points=pain_points,
        selling_points=selling_points,
        diff_opportunities=opportunities,
        positioning=positioning,
        action_items=action_items,
        next_level_hint=next_hint,
        next_level_hint_zh=next_hint_zh,
        summary=summary,
        summary_zh=summary_zh,
    )


# ============================================================
# OutputFormat
# ============================================================

def format_report(result: AnalysisResult, lang: str = "en") -> str:
    """FormatReport"""
    
    if lang == "zh":
        lines = [
            "🎯 **ProductDifferenceAnalyzeReport**",
            "",
            f"**AnalyzelayerLevel**: {result.level.value}",
            f"**IProduct**: {result.my_product.name}",
            f"**CompetitorQuantity**: {len(result.competitors)}",
            "",
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            "## 📊 CompetitorComparisonMatrix",
            "",
        ]
        
        # ComparisonTable
        lines.append("| Product | Price | Rating | Review Count |")
        lines.append("|------|------|------|--------|")
        lines.append(f"| **{result.my_product.name}** (I) | .2f | {result.my_product.rating} | {result.my_product.review_count} |")
        for c in result.competitors:
            lines.append(f"| {c.name} | .2f | {c.rating} | {c.review_count} |")
        
        if result.pain_points:
            lines.extend([
                "",
                "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
                "",
                "## 😤 CompetitorPain point (Differentiation Opportunities)",
                "",
            ])
            for i, pain in enumerate(result.pain_points, 1):
                severity_icon = "🔴" if pain.severity == "high" else "🟡" if pain.severity == "medium" else "🟢"
                lines.append(f"**{i}. {pain.description_zh}** {severity_icon}")
                lines.append(f"   Occurrence frequency: {pain.frequency} | CriticalprocessDegree: {pain.severity}")
                if pain.example_reviews:
                    lines.append(f"   Example: \"{pain.example_reviews[0][:50]}...\"")
                lines.append("")
        
        if result.selling_points:
            lines.extend([
                "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
                "",
                "## ✨ My selling point",
                "",
            ])
            for i, sp in enumerate(result.selling_points, 1):
                strength_icon = "💪" if sp.strength == "strong" else "👍" if sp.strength == "medium" else "👌"
                lines.append(f"**{i}. {sp.description_zh}** {strength_icon}")
                lines.append(f"   Occurrence frequency: {sp.frequency}")
                lines.append("")
        
        lines.extend([
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            "## 💡 Differentiation Opportunities",
            "",
        ])
        for i, opp in enumerate(result.diff_opportunities[:5], 1):
            priority_icon = "🔴" if opp.priority == "high" else "🟡"
            lines.append(f"**{i}. [{opp.angle.value.upper()}] {opp.opportunity_zh}** {priority_icon}")
            lines.append(f"   Action: {opp.action_zh}")
            lines.append("")
        
        if result.positioning:
            lines.extend([
                "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
                "",
                "## 🎯 PositioningStrategy",
                "",
                f"**PositioningCategoryType**: {result.positioning.position_type.upper()}",
                f"**Target audience**: {result.positioning.target_audience_zh}",
                f"**PriceStrategy**: {result.positioning.price_strategy_zh}",
                f"**CoreInformation**: {result.positioning.key_message_zh}",
                "",
            ])
        
        lines.extend([
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            "## 📋 Action Plan",
            "",
        ])
        for action in result.action_items[:5]:
            lines.append(f"**[{action['priority']}] [{action['category_zh']}]** {action['action_zh']}")
            lines.append(f"   Timeline: {action['timeline']}")
            lines.append("")
        
        if result.level != AnalysisLevel.L4:
            lines.extend([
                "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
                "",
                f"🔍 **Want to go deeperAnalyze？** {result.next_level_hint_zh}",
            ])
        
        lines.extend([
            "",
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            result.summary_zh,
        ])
    else:
        # English version (similar structure)
        lines = [
            "🎯 **Product Differentiation Analysis Report**",
            "",
            f"**Analysis Level**: {result.level.value}",
            f"**My Product**: {result.my_product.name}",
            f"**Competitors**: {len(result.competitors)}",
            "",
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            "## 📊 Comparison Matrix",
            "",
            "| Product | Price | Rating | Reviews |",
            "|---------|-------|--------|---------|",
            f"| **{result.my_product.name}** (Mine) | .2f | {result.my_product.rating} | {result.my_product.review_count} |",
        ]
        for c in result.competitors:
            lines.append(f"| {c.name} | .2f | {c.rating} | {c.review_count} |")
        
        if result.pain_points:
            lines.extend(["", "## 😤 Competitor Pain Points", ""])
            for i, pain in enumerate(result.pain_points, 1):
                lines.append(f"**{i}. {pain.description}** (Frequency: {pain.frequency})")
        
        if result.diff_opportunities:
            lines.extend(["", "## 💡 Differentiation Opportunities", ""])
            for i, opp in enumerate(result.diff_opportunities[:5], 1):
                lines.append(f"**{i}. [{opp.angle.value}]** {opp.opportunity}")
                lines.append(f"   Action: {opp.action}")
        
        if result.level != AnalysisLevel.L4:
            lines.extend(["", f"🔍 **Want deeper analysis?** {result.next_level_hint}"])
        
        lines.extend(["", result.summary])
    
    return "\n".join(lines)


# ============================================================
# CLI
# ============================================================

def main():
    lang = "zh" if "--zh" in sys.argv else "en"
    
    # DemoData
    my_product = ProductInfo(
        name="My Wireless Earbuds Pro",
        asin="B08MYASIN1",
        price=49.99,
        rating=4.3,
        review_count=150,
        features=["ANC", "30h battery", "Waterproof"],
        is_mine=True,
    )
    
    competitors = [
        ProductInfo(name="Competitor A Earbuds", asin="B08COMP1", price=59.99, rating=4.1, review_count=500),
        ProductInfo(name="Competitor B Earbuds", asin="B08COMP2", price=39.99, rating=4.5, review_count=1200),
        ProductInfo(name="Competitor C Earbuds", asin="B08COMP3", price=45.99, rating=3.9, review_count=300),
    ]
    
    competitor_reviews = ReviewData(
        negative=[
            "The quality is poor, broke after 2 weeks",
            "Sound quality is bad, very cheap feeling",
            "Doesn't fit well, keeps falling out",
            "Battery life is terrible, only lasts 2 hours",
            "Charging case stopped working after a month",
            "Too expensive for this quality",
            "Bluetooth keeps disconnecting",
        ]
    )
    
    my_reviews = ReviewData(
        positive=[
            "Great sound quality, very clear!",
            "Battery lasts forever, love it",
            "Perfect fit, stays in my ears during workout",
            "Excellent value for money, recommend!",
            "Fast shipping, well packaged",
        ]
    )
    
    result = analyze(my_product, competitors, competitor_reviews, my_reviews)
    print(format_report(result, lang))


if __name__ == "__main__":
    main()

Product Differentiation Amazon

Skill

Amazon product differentiation strategy tool. Analyze competitor weaknesses, extract pain points from negative reviews, identify unique selling points from p...

---
name: product-differentiation-amazon
version: 1.0.0
author: Nexscope AI
description: "Amazon product differentiation strategy tool. Analyze competitor weaknesses, extract pain points from negative reviews, identify unique selling points from positive reviews, and generate actionable differentiation strategies. Progressive L1-L4 analysis depth. No API key required."
metadata: {"nexscope":{"emoji":"🎯","category":"ecommerce"}}
---

# Product Differentiation — Amazon 🎯

Develop winning product differentiation strategies by analyzing competitor reviews and market positioning.

## Installation

```bash
npx skills add nexscope-ai/eCommerce-Skills --skill product-differentiation-amazon -g
```

## Features

- **Competitor Matrix** — Side-by-side product comparison
- **Pain Point Mining** — Extract issues from negative reviews
- **USP Extraction** — Identify selling points from positive reviews
- **Differentiation Opportunities** — Find gaps in the market
- **Positioning Strategy** — Market positioning recommendations
- **Action Plan** — Prioritized improvement roadmap

## Progressive Analysis Levels

| Level | Required Data | Unlocked Analysis |
|-------|---------------|-------------------|
| **L1 Basic** | Product info | Basic comparison matrix |
| **L2 Pain Points** | + Competitor negative reviews | Pain point analysis |
| **L3 USP** | + Your positive reviews | Selling point extraction |
| **L4 Complete** | + Market data | Full strategy & action plan |

## Analysis Dimensions

| Dimension | Method | Output |
|-----------|--------|--------|
| Feature Gap | Competitor comparison | Missing features list |
| Pain Points | Negative review NLP | Top complaints ranked |
| Selling Points | Positive review NLP | Key USPs identified |
| Price Position | Price-value mapping | Positioning quadrant |
| Quality Signals | Review sentiment | Quality perception score |

## Usage

### Interactive Mode

```bash
python3 scripts/analyzer.py
```

### With Parameters

```bash
python3 scripts/analyzer.py '{
  "your_asin": "B08XXXXXX1",
  "competitor_asins": ["B08XXXXXX2", "B08XXXXXX3"],
  "category": "Electronics"
}'
```

### Demo Mode

```bash
python3 scripts/analyzer.py --demo
```

## Input Example

```json
{
  "your_product": {
    "asin": "B08XXXXXX1",
    "title": "Wireless Earbuds Pro",
    "price": 49.99,
    "rating": 4.2,
    "features": ["Bluetooth 5.0", "30h battery", "IPX5"]
  },
  "competitors": [
    {
      "asin": "B08XXXXXX2",
      "title": "Competitor Earbuds A",
      "price": 39.99,
      "rating": 4.0
    }
  ],
  "negative_reviews": [...],
  "positive_reviews": [...]
}
```

## Output Example

```
🎯 Product Differentiation Report

Product: Wireless Earbuds Pro
Category: Electronics
Competitors Analyzed: 3

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 COMPETITOR COMPARISON MATRIX

Feature         | You  | Comp A | Comp B | Comp C
─────────────────────────────────────────────────
Bluetooth       | 5.0  | 5.0    | 4.2    | 5.0
Battery Life    | 30h  | 24h    | 20h    | 28h
Water Resist    | IPX5 | IPX4   | None   | IPX5
Noise Cancel    | ❌   | ❌     | ❌     | ✅
Price           | $50  | $40    | $30    | $70

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

😤 TOP PAIN POINTS (from competitor reviews)

1. 🔴 Battery dies quickly (mentioned 45x)
2. 🔴 Poor Bluetooth connection (mentioned 32x)
3. 🟡 Uncomfortable fit (mentioned 28x)
4. 🟡 Case quality issues (mentioned 15x)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✨ YOUR UNIQUE SELLING POINTS

1. ⭐ Superior battery life (30h vs avg 24h)
2. ⭐ Better water resistance (IPX5)
3. ⭐ Stable connection (highlighted in reviews)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🎯 DIFFERENTIATION OPPORTUNITIES

1. Add noise cancellation (gap in mid-range)
2. Improve comfort messaging
3. Highlight battery advantage in listing

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 ACTION PLAN

Priority | Action                    | Impact
─────────────────────────────────────────────
HIGH     | Update listing bullets    | +15% CVR
HIGH     | Add battery comparison    | +10% CVR
MEDIUM   | Request comfort reviews   | +5% rating
LOW      | Consider ANC version      | New SKU
```

## Strategy Framework

```
Competitor Analysis
      ↓
Pain Point Mining
      ↓
USP Identification
      ↓
Gap Analysis
      ↓
Positioning Strategy
      ↓
Action Plan
```

---

**Part of [Nexscope AI](https://www.nexscope.ai/) — AI tools for e-commerce sellers.**

FILE:scripts/analyzer.py
#!/usr/bin/env python3
"""
Product Differentiation Analyzer - Core Engine
ProductDifferenceAnalyze - Core Engine

Features:
- CompetitorFeatureComparisonMatrix
- CompetitorNegative ReviewPain pointMining
- Positive ReviewSelling point extraction
- Difference angleDegreeIdentify
- MarketPositioningStrategy
- PricingStrategyRecommendation
- MarketingSelling pointRecommendation
- ProductImproveRecommendation

SupportProgressiveAnalyze:
L1: BasicComparison (ProductInformation)
L2: Pain pointAnalyze (+ CompetitorNegative Review)
L3: Selling point extraction (+ SelfPositive Review)
L4: CompleteStrategy (+ MarketData)

Version: 1.0.0
"""

import json
from dataclasses import dataclass, field
from typing import List, Dict, Optional, Tuple
from enum import Enum
from datetime import datetime
import sys
import re
from collections import Counter


class AnalysisLevel(Enum):
    """AnalyzelayerLevel"""
    L1 = "L1"  # BasicComparison
    L2 = "L2"  # Pain pointAnalyze
    L3 = "L3"  # Selling point extraction
    L4 = "L4"  # CompleteStrategy


class DiffAngle(Enum):
    """Difference angleDegree"""
    FUNCTION = "function"       # FeatureDifference
    QUALITY = "quality"         # QualityDifference
    DESIGN = "design"           # Design difference
    PRICE = "price"             # PriceDifference
    SERVICE = "service"         # Service difference
    AUDIENCE = "audience"       # Audience difference
    SCENARIO = "scenario"       # Scenario difference
    BRAND = "brand"             # BrandDifference


# ============================================================
# Pain pointKeywordsLibrary
# ============================================================

PAIN_POINT_KEYWORDS = {
    "quality": {
        "en": ["cheap", "broke", "broken", "flimsy", "poor quality", "fell apart", "defective", "doesn't last", "stopped working"],
        "zh": ["Poor quality", " bad  ", "Fragile", "Poor workmanship", "Not durable", "StopWork"],
    },
    "function": {
        "en": ["doesn't work", "not working", "malfunction", "missing feature", "can't", "won't", "failed", "useless"],
        "zh": ["notWork", "Fault", "FeatureMissing", "Cannot", "Failed", "Useless"],
    },
    "design": {
        "en": ["ugly", "looks cheap", "bulky", "heavy", "uncomfortable", "awkward", "hard to use", "confusing"],
        "zh": ["ugly", "Looks cheap", "clumsy heavy ", " heavy ", "Uncomfortable", "Hard to use", "Complex"],
    },
    "size": {
        "en": ["too small", "too big", "wrong size", "doesn't fit", "smaller than expected", "bigger than"],
        "zh": [" too  small ", " too  big ", "Sizenot for ", "Not suitable"],
    },
    "shipping": {
        "en": ["late", "damaged", "wrong item", "missing parts", "packaging"],
        "zh": ["late to ", "loss bad ", "Sent wrong", "Missing parts", "Packaging"],
    },
    "value": {
        "en": ["overpriced", "not worth", "waste of money", "rip off", "too expensive"],
        "zh": [" too expensive", "notValue", "Waste money", "trap"],
    },
}

SELLING_POINT_KEYWORDS = {
    "quality": {
        "en": ["solid", "sturdy", "durable", "well made", "high quality", "premium", "excellent", "perfect"],
        "zh": ["Sturdy", "Durable", "Workmanship good ", "HighQuality", "Quality", "Perfect"],
    },
    "function": {
        "en": ["works great", "works perfectly", "easy to use", "convenient", "efficient", "powerful", "fast"],
        "zh": [" good use", "Convenient", "Higheffect", "strong big ", " fast "],
    },
    "design": {
        "en": ["beautiful", "sleek", "stylish", "modern", "compact", "lightweight", "elegant"],
        "zh": ["Beautiful", "Timeyet", "Modern", " small clever", " light easy", "Elegant"],
    },
    "value": {
        "en": ["great value", "worth it", "good price", "affordable", "best purchase", "recommend"],
        "zh": ["Value ", "Value for money", "Recommended", "Worth it"],
    },
    "service": {
        "en": ["great service", "fast shipping", "well packaged", "responsive seller"],
        "zh": ["Service good ", "Shipping fast ", "Packaging good ", "SellerResponse fast "],
    },
}


# ============================================================
# Data Structures
# ============================================================

@dataclass
class ProductInfo:
    """ProductInformation"""
    name: str = ""
    asin: str = ""
    price: float = 0.0
    rating: float = 0.0
    review_count: int = 0
    features: List[str] = field(default_factory=list)
    bullet_points: List[str] = field(default_factory=list)
    category: str = ""
    brand: str = ""
    is_mine: bool = False


@dataclass
class ReviewData:
    """Review Countdata"""
    positive: List[str] = field(default_factory=list)  # Positive Review
    negative: List[str] = field(default_factory=list)  # Negative Review
    neutral: List[str] = field(default_factory=list)   # Neutral review


@dataclass
class PainPoint:
    """Pain point"""
    category: str
    description: str
    description_zh: str
    frequency: int
    severity: str  # high/medium/low
    example_reviews: List[str] = field(default_factory=list)


@dataclass
class SellingPoint:
    """Selling point"""
    category: str
    description: str
    description_zh: str
    frequency: int
    strength: str  # strong/medium/weak
    example_reviews: List[str] = field(default_factory=list)


@dataclass
class DiffOpportunity:
    """Differentiation Opportunities"""
    angle: DiffAngle
    opportunity: str
    opportunity_zh: str
    priority: str  # high/medium/low
    action: str
    action_zh: str
    potential_impact: str


@dataclass
class PositioningStrategy:
    """PositioningStrategy"""
    position_type: str  # premium/value/niche/innovation
    target_audience: str
    target_audience_zh: str
    price_strategy: str
    price_strategy_zh: str
    key_message: str
    key_message_zh: str
    marketing_angles: List[str] = field(default_factory=list)


@dataclass
class AnalysisResult:
    """AnalyzeResult"""
    level: AnalysisLevel
    my_product: ProductInfo
    competitors: List[ProductInfo]
    comparison_matrix: Dict
    pain_points: List[PainPoint]
    selling_points: List[SellingPoint]
    diff_opportunities: List[DiffOpportunity]
    positioning: Optional[PositioningStrategy]
    action_items: List[Dict]
    next_level_hint: str
    next_level_hint_zh: str
    summary: str
    summary_zh: str


# ============================================================
# AnalyzeFunction
# ============================================================

def extract_pain_points(reviews: List[str], lang: str = "en") -> List[PainPoint]:
    """ from Negative Review in ExtractPain point"""
    pain_points = []
    category_counts = Counter()
    category_examples = {}
    
    for review in reviews:
        review_lower = review.lower()
        for category, keywords in PAIN_POINT_KEYWORDS.items():
            for keyword in keywords.get(lang, []) + keywords.get("en", []):
                if keyword.lower() in review_lower:
                    category_counts[category] += 1
                    if category not in category_examples:
                        category_examples[category] = []
                    if len(category_examples[category]) < 3:
                        category_examples[category].append(review[:100])
                    break
    
    category_names = {
        "quality": ("Quality Issues", "QualityIssue"),
        "function": ("Functionality Problems", "FeatureIssue"),
        "design": ("Design Flaws", "Design defect"),
        "size": ("Size/Fit Issues", "SizeIssue"),
        "shipping": ("Shipping/Packaging", "LogisticsPackaging"),
        "value": ("Value Concerns", "Value for money"),
    }
    
    for category, count in category_counts.most_common():
        if count >= 1:
            severity = "high" if count >= 5 else "medium" if count >= 2 else "low"
            names = category_names.get(category, (category.title(), category))
            pain_points.append(PainPoint(
                category=category,
                description=names[0],
                description_zh=names[1],
                frequency=count,
                severity=severity,
                example_reviews=category_examples.get(category, []),
            ))
    
    return pain_points


def extract_selling_points(reviews: List[str], lang: str = "en") -> List[SellingPoint]:
    """ from Positive ReviewExtract selling points from"""
    selling_points = []
    category_counts = Counter()
    category_examples = {}
    
    for review in reviews:
        review_lower = review.lower()
        for category, keywords in SELLING_POINT_KEYWORDS.items():
            for keyword in keywords.get(lang, []) + keywords.get("en", []):
                if keyword.lower() in review_lower:
                    category_counts[category] += 1
                    if category not in category_examples:
                        category_examples[category] = []
                    if len(category_examples[category]) < 3:
                        category_examples[category].append(review[:100])
                    break
    
    category_names = {
        "quality": ("Build Quality", "WorkmanshipQuality"),
        "function": ("Functionality", "Featurenature"),
        "design": ("Design & Aesthetics", "Beautiful design"),
        "value": ("Value for Money", "Value for money"),
        "service": ("Service & Shipping", "ServiceLogistics"),
    }
    
    for category, count in category_counts.most_common():
        if count >= 1:
            strength = "strong" if count >= 5 else "medium" if count >= 2 else "weak"
            names = category_names.get(category, (category.title(), category))
            selling_points.append(SellingPoint(
                category=category,
                description=names[0],
                description_zh=names[1],
                frequency=count,
                strength=strength,
                example_reviews=category_examples.get(category, []),
            ))
    
    return selling_points


def build_comparison_matrix(my_product: ProductInfo, competitors: List[ProductInfo]) -> Dict:
    """BuildComparisonMatrix"""
    matrix = {
        "products": [my_product.name] + [c.name for c in competitors],
        "prices": [my_product.price] + [c.price for c in competitors],
        "ratings": [my_product.rating] + [c.rating for c in competitors],
        "review_counts": [my_product.review_count] + [c.review_count for c in competitors],
    }
    
    # PricePositioning
    all_prices = [p for p in matrix["prices"] if p > 0]
    if all_prices:
        avg_price = sum(all_prices) / len(all_prices)
        matrix["price_position"] = "above_avg" if my_product.price > avg_price else "below_avg"
        matrix["avg_price"] = avg_price
    
    # RatingPositioning
    all_ratings = [r for r in matrix["ratings"] if r > 0]
    if all_ratings:
        avg_rating = sum(all_ratings) / len(all_ratings)
        matrix["rating_position"] = "above_avg" if my_product.rating > avg_rating else "below_avg"
        matrix["avg_rating"] = avg_rating
    
    return matrix


def identify_opportunities(
    my_product: ProductInfo,
    competitors: List[ProductInfo],
    pain_points: List[PainPoint],
    selling_points: List[SellingPoint],
    matrix: Dict
) -> List[DiffOpportunity]:
    """IdentifyDifferentiation Opportunities"""
    opportunities = []
    
    # 1. Based onCompetitorPain pointOpportunity
    for pain in pain_points:
        if pain.severity == "high":
            opp = DiffOpportunity(
                angle=DiffAngle.FUNCTION if pain.category == "function" else DiffAngle.QUALITY,
                opportunity=f"Address competitor weakness: {pain.description}",
                opportunity_zh=f"SolveCompetitorWeakness: {pain.description_zh}",
                priority="high",
                action=f"Improve {pain.category} and highlight in marketing",
                action_zh=f"Improve{pain.description_zh}and in Marketing in Highlight",
                potential_impact="High - directly addresses customer pain",
            )
            opportunities.append(opp)
    
    # 2. Based onPriceOpportunity
    if matrix.get("price_position") == "below_avg":
        opportunities.append(DiffOpportunity(
            angle=DiffAngle.PRICE,
            opportunity="Value positioning - lower price than competitors",
            opportunity_zh="Value for moneyPositioning - Price low  at Competitor",
            priority="medium",
            action="Emphasize value proposition in marketing",
            action_zh=" in Marketing in EmphasizeValue for money",
            potential_impact="Medium - price-sensitive customers",
        ))
    elif matrix.get("price_position") == "above_avg":
        opportunities.append(DiffOpportunity(
            angle=DiffAngle.PRICE,
            opportunity="Premium positioning - justify higher price",
            opportunity_zh="PremiumPositioning - ProofHigherPriceReasonable",
            priority="high",
            action="Highlight premium features and quality",
            action_zh="HighlightPremiumFeatureAndQuality",
            potential_impact="High - must justify price premium",
        ))
    
    # 3. Based onRatingOpportunity
    if matrix.get("rating_position") == "above_avg":
        opportunities.append(DiffOpportunity(
            angle=DiffAngle.QUALITY,
            opportunity="Quality leader - leverage higher rating",
            opportunity_zh="Qualitylead first  - UtilizeHigherRating",
            priority="high",
            action="Display rating prominently, collect more reviews",
            action_zh="HighlightDisplayRating，Collect more  many Review",
            potential_impact="High - social proof advantage",
        ))
    
    # 4. SegmentMarketOpportunity
    opportunities.append(DiffOpportunity(
        angle=DiffAngle.AUDIENCE,
        opportunity="Niche targeting - focus on specific user segment",
        opportunity_zh="SegmentPositioning - Focus on specificUserGroup",
        priority="medium",
        action="Identify underserved segment and tailor product/marketing",
        action_zh="IdentifyUnmetSegmentMarket，CustomProduct/Marketing",
        potential_impact="Medium - reduced competition in niche",
    ))
    
    return opportunities


def generate_positioning(
    my_product: ProductInfo,
    matrix: Dict,
    opportunities: List[DiffOpportunity]
) -> PositioningStrategy:
    """GeneratePositioningStrategy"""
    
    # ConfirmPositioningCategoryType
    price_pos = matrix.get("price_position", "below_avg")
    rating_pos = matrix.get("rating_position", "below_avg")
    
    if price_pos == "above_avg" and rating_pos == "above_avg":
        position_type = "premium"
        target = "Quality-conscious buyers willing to pay more"
        target_zh = "Willing for QualityPayPremiumUser"
        price_strategy = "Maintain premium pricing, bundle with extras"
        price_strategy_zh = "MaintainPremiumPricing，Bundle increaseValueService"
        key_message = "The premium choice for discerning customers"
        key_message_zh = "PremiumUserSmart choice"
    elif price_pos == "below_avg":
        position_type = "value"
        target = "Price-sensitive buyers seeking good deals"
        target_zh = "FindHighValue for moneyPriceSensitiveUser"
        price_strategy = "Competitive pricing, volume-focused"
        price_strategy_zh = "CompetitivePricing，Pursue sales volume"
        key_message = "Same quality, better price"
        key_message_zh = "same etcQuality， more excellentPrice"
    else:
        position_type = "balanced"
        target = "Mainstream buyers seeking reliable products"
        target_zh = "FindCanrelyProductMainflowUser"
        price_strategy = "Market-aligned pricing"
        price_strategy_zh = "MarketPricing"
        key_message = "The trusted choice"
        key_message_zh = "ValueTrustedChoice"
    
    marketing_angles = [
        f"[{opp.angle.value.upper()}] {opp.opportunity}" 
        for opp in opportunities[:3] if opp.priority == "high"
    ]
    
    return PositioningStrategy(
        position_type=position_type,
        target_audience=target,
        target_audience_zh=target_zh,
        price_strategy=price_strategy,
        price_strategy_zh=price_strategy_zh,
        key_message=key_message,
        key_message_zh=key_message_zh,
        marketing_angles=marketing_angles,
    )


def generate_action_items(
    opportunities: List[DiffOpportunity],
    pain_points: List[PainPoint],
    positioning: PositioningStrategy
) -> List[Dict]:
    """GenerateActionRecommendation"""
    actions = []
    
    # ProductImprove
    for pain in pain_points[:2]:
        if pain.severity in ["high", "medium"]:
            actions.append({
                "category": "Product",
                "category_zh": "Product",
                "action": f"Address {pain.description}",
                "action_zh": f"Solve{pain.description_zh}",
                "priority": "P1" if pain.severity == "high" else "P2",
                "timeline": "1-3 months",
            })
    
    # MarketingImprove
    for opp in opportunities[:2]:
        if opp.priority == "high":
            actions.append({
                "category": "Marketing",
                "category_zh": "Marketing",
                "action": opp.action,
                "action_zh": opp.action_zh,
                "priority": "P1",
                "timeline": "Immediate",
            })
    
    # PositioningRelated
    actions.append({
        "category": "Positioning",
        "category_zh": "Positioning",
        "action": f"Adopt {positioning.position_type} positioning strategy",
        "action_zh": f"Adopt{positioning.position_type}PositioningStrategy",
        "priority": "P1",
        "timeline": "Ongoing",
    })
    
    return actions


def determine_level(
    my_product: ProductInfo,
    competitors: List[ProductInfo],
    competitor_reviews: ReviewData,
    my_reviews: ReviewData
) -> AnalysisLevel:
    """ConfirmAnalyzelayerLevel"""
    has_products = my_product.name and len(competitors) > 0
    has_competitor_reviews = len(competitor_reviews.negative) > 0
    has_my_reviews = len(my_reviews.positive) > 0
    has_market_data = my_product.price > 0 and my_product.rating > 0
    
    if has_products and has_competitor_reviews and has_my_reviews and has_market_data:
        return AnalysisLevel.L4
    elif has_products and has_competitor_reviews and has_my_reviews:
        return AnalysisLevel.L3
    elif has_products and has_competitor_reviews:
        return AnalysisLevel.L2
    else:
        return AnalysisLevel.L1


def analyze(
    my_product: ProductInfo,
    competitors: List[ProductInfo],
    competitor_reviews: ReviewData = None,
    my_reviews: ReviewData = None,
) -> AnalysisResult:
    """MainAnalyzeFunction"""
    
    if competitor_reviews is None:
        competitor_reviews = ReviewData()
    if my_reviews is None:
        my_reviews = ReviewData()
    
    # ConfirmAnalyzelayerLevel
    level = determine_level(my_product, competitors, competitor_reviews, my_reviews)
    
    # BuildComparisonMatrix
    matrix = build_comparison_matrix(my_product, competitors)
    
    # ExtractPain point (L2+)
    pain_points = []
    if level.value >= AnalysisLevel.L2.value:
        pain_points = extract_pain_points(competitor_reviews.negative)
    
    # Extract selling points (L3+)
    selling_points = []
    if level.value >= AnalysisLevel.L3.value:
        selling_points = extract_selling_points(my_reviews.positive)
    
    # IdentifyDifferentiation Opportunities
    opportunities = identify_opportunities(my_product, competitors, pain_points, selling_points, matrix)
    
    # GeneratePositioningStrategy (L4)
    positioning = None
    if level == AnalysisLevel.L4:
        positioning = generate_positioning(my_product, matrix, opportunities)
    
    # GenerateActionRecommendation
    action_items = generate_action_items(opportunities, pain_points, positioning or PositioningStrategy(
        position_type="balanced", target_audience="", target_audience_zh="",
        price_strategy="", price_strategy_zh="", key_message="", key_message_zh=""
    ))
    
    #  below oneLevelHint
    hints = {
        AnalysisLevel.L1: ("Add competitor negative reviews for pain point analysis", "AddCompetitorNegative Review to ProceedPain pointAnalyze"),
        AnalysisLevel.L2: ("Add your product's positive reviews for selling point extraction", "AddyouProductPositive ReviewTo extract selling points"),
        AnalysisLevel.L3: ("Add price and rating data for complete positioning strategy", "AddPriceAndRatingDataTo obtainCompletePositioningStrategy"),
        AnalysisLevel.L4: ("Full analysis complete!", "CompleteAnalyze already Complete！"),
    }
    next_hint, next_hint_zh = hints[level]
    
    # Summary
    summary = f"Level {level.value} Analysis | {len(opportunities)} opportunities | {len(pain_points)} pain points identified"
    summary_zh = f"{level.value} LevelAnalyze | {len(opportunities)} Differentiation Opportunities | {len(pain_points)} Pain pointIdentify"
    
    return AnalysisResult(
        level=level,
        my_product=my_product,
        competitors=competitors,
        comparison_matrix=matrix,
        pain_points=pain_points,
        selling_points=selling_points,
        diff_opportunities=opportunities,
        positioning=positioning,
        action_items=action_items,
        next_level_hint=next_hint,
        next_level_hint_zh=next_hint_zh,
        summary=summary,
        summary_zh=summary_zh,
    )


# ============================================================
# OutputFormat
# ============================================================

def format_report(result: AnalysisResult, lang: str = "en") -> str:
    """FormatReport"""
    
    if lang == "zh":
        lines = [
            "🎯 **ProductDifferenceAnalyzeReport**",
            "",
            f"**AnalyzelayerLevel**: {result.level.value}",
            f"**IProduct**: {result.my_product.name}",
            f"**CompetitorQuantity**: {len(result.competitors)}",
            "",
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            "## 📊 CompetitorComparisonMatrix",
            "",
        ]
        
        # ComparisonTable
        lines.append("| Product | Price | Rating | Review Count |")
        lines.append("|------|------|------|--------|")
        lines.append(f"| **{result.my_product.name}** (I) | .2f | {result.my_product.rating} | {result.my_product.review_count} |")
        for c in result.competitors:
            lines.append(f"| {c.name} | .2f | {c.rating} | {c.review_count} |")
        
        if result.pain_points:
            lines.extend([
                "",
                "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
                "",
                "## 😤 CompetitorPain point (Differentiation Opportunities)",
                "",
            ])
            for i, pain in enumerate(result.pain_points, 1):
                severity_icon = "🔴" if pain.severity == "high" else "🟡" if pain.severity == "medium" else "🟢"
                lines.append(f"**{i}. {pain.description_zh}** {severity_icon}")
                lines.append(f"   Occurrence frequency: {pain.frequency} | CriticalprocessDegree: {pain.severity}")
                if pain.example_reviews:
                    lines.append(f"   Example: \"{pain.example_reviews[0][:50]}...\"")
                lines.append("")
        
        if result.selling_points:
            lines.extend([
                "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
                "",
                "## ✨ My selling point",
                "",
            ])
            for i, sp in enumerate(result.selling_points, 1):
                strength_icon = "💪" if sp.strength == "strong" else "👍" if sp.strength == "medium" else "👌"
                lines.append(f"**{i}. {sp.description_zh}** {strength_icon}")
                lines.append(f"   Occurrence frequency: {sp.frequency}")
                lines.append("")
        
        lines.extend([
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            "## 💡 Differentiation Opportunities",
            "",
        ])
        for i, opp in enumerate(result.diff_opportunities[:5], 1):
            priority_icon = "🔴" if opp.priority == "high" else "🟡"
            lines.append(f"**{i}. [{opp.angle.value.upper()}] {opp.opportunity_zh}** {priority_icon}")
            lines.append(f"   Action: {opp.action_zh}")
            lines.append("")
        
        if result.positioning:
            lines.extend([
                "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
                "",
                "## 🎯 PositioningStrategy",
                "",
                f"**PositioningCategoryType**: {result.positioning.position_type.upper()}",
                f"**Target audience**: {result.positioning.target_audience_zh}",
                f"**PriceStrategy**: {result.positioning.price_strategy_zh}",
                f"**CoreInformation**: {result.positioning.key_message_zh}",
                "",
            ])
        
        lines.extend([
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            "## 📋 Action Plan",
            "",
        ])
        for action in result.action_items[:5]:
            lines.append(f"**[{action['priority']}] [{action['category_zh']}]** {action['action_zh']}")
            lines.append(f"   Timeline: {action['timeline']}")
            lines.append("")
        
        if result.level != AnalysisLevel.L4:
            lines.extend([
                "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
                "",
                f"🔍 **Want to go deeperAnalyze？** {result.next_level_hint_zh}",
            ])
        
        lines.extend([
            "",
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            result.summary_zh,
        ])
    else:
        # English version (similar structure)
        lines = [
            "🎯 **Product Differentiation Analysis Report**",
            "",
            f"**Analysis Level**: {result.level.value}",
            f"**My Product**: {result.my_product.name}",
            f"**Competitors**: {len(result.competitors)}",
            "",
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            "## 📊 Comparison Matrix",
            "",
            "| Product | Price | Rating | Reviews |",
            "|---------|-------|--------|---------|",
            f"| **{result.my_product.name}** (Mine) | .2f | {result.my_product.rating} | {result.my_product.review_count} |",
        ]
        for c in result.competitors:
            lines.append(f"| {c.name} | .2f | {c.rating} | {c.review_count} |")
        
        if result.pain_points:
            lines.extend(["", "## 😤 Competitor Pain Points", ""])
            for i, pain in enumerate(result.pain_points, 1):
                lines.append(f"**{i}. {pain.description}** (Frequency: {pain.frequency})")
        
        if result.diff_opportunities:
            lines.extend(["", "## 💡 Differentiation Opportunities", ""])
            for i, opp in enumerate(result.diff_opportunities[:5], 1):
                lines.append(f"**{i}. [{opp.angle.value}]** {opp.opportunity}")
                lines.append(f"   Action: {opp.action}")
        
        if result.level != AnalysisLevel.L4:
            lines.extend(["", f"🔍 **Want deeper analysis?** {result.next_level_hint}"])
        
        lines.extend(["", result.summary])
    
    return "\n".join(lines)


# ============================================================
# CLI
# ============================================================

def main():
    lang = "zh" if "--zh" in sys.argv else "en"
    
    # DemoData
    my_product = ProductInfo(
        name="My Wireless Earbuds Pro",
        asin="B08MYASIN1",
        price=49.99,
        rating=4.3,
        review_count=150,
        features=["ANC", "30h battery", "Waterproof"],
        is_mine=True,
    )
    
    competitors = [
        ProductInfo(name="Competitor A Earbuds", asin="B08COMP1", price=59.99, rating=4.1, review_count=500),
        ProductInfo(name="Competitor B Earbuds", asin="B08COMP2", price=39.99, rating=4.5, review_count=1200),
        ProductInfo(name="Competitor C Earbuds", asin="B08COMP3", price=45.99, rating=3.9, review_count=300),
    ]
    
    competitor_reviews = ReviewData(
        negative=[
            "The quality is poor, broke after 2 weeks",
            "Sound quality is bad, very cheap feeling",
            "Doesn't fit well, keeps falling out",
            "Battery life is terrible, only lasts 2 hours",
            "Charging case stopped working after a month",
            "Too expensive for this quality",
            "Bluetooth keeps disconnecting",
        ]
    )
    
    my_reviews = ReviewData(
        positive=[
            "Great sound quality, very clear!",
            "Battery lasts forever, love it",
            "Perfect fit, stays in my ears during workout",
            "Excellent value for money, recommend!",
            "Fast shipping, well packaged",
        ]
    )
    
    result = analyze(my_product, competitors, competitor_reviews, my_reviews)
    print(format_report(result, lang))


if __name__ == "__main__":
    main()

Product Description Generator

Skill

E-commerce product description generator for any platform. Generates optimized titles, bullet points, descriptions, and backend keywords using competitor res...

---
name: product-description-generator
description: "E-commerce product description generator for any platform. Generates optimized titles, bullet points, descriptions, and backend keywords using competitor research + keyword scoring + FABE copywriting. Two modes: (A) Create — generate listing from product specs with optional competitor analysis, (B) Optimize — improve existing listing with keyword gap analysis. Supports Amazon, eBay, Walmart, Shopify, Etsy, TikTok Shop, Lazada, Shopee. No API key required. Use when: (1) writing a new product listing, (2) analyzing what makes competitors rank, (3) improving an underperforming listing."
metadata: {"nexscope":{"emoji":"📝","category":"ecommerce"}}
---

# Product Description Generator 📝

Generate platform-optimized product copy — titles, bullet points, descriptions, and backend keywords — for any major e-commerce platform. No API key required.

## Installation

```bash
npx skills add nexscope-ai/eCommerce-Skills --skill product-description-generator -g
```

> **For Amazon listings**, use our dedicated skill with Cosmo algorithm optimization:
> ```bash
> npx skills add nexscope-ai/Amazon-Skills --skill amazon-listing-optimization -g
> ```
> See: [amazon-listing-optimization](https://github.com/nexscope-ai/Amazon-Skills/tree/main/amazon-listing-optimization)

## Two Modes

| Mode | When to Use | Input |
|------|-------------|-------|
| **A — Create** | Writing a new listing | Product specs + optional competitor URLs |
| **B — Optimize** | Improving existing listing | Current listing or URL + optional competitor URLs |

Both modes support competitor analysis — just include competitor URLs to enable it.

## Supported Platforms

| Platform | Output Components |
|----------|-------------------|
| **Amazon** | Title (≤200) + 5 Bullets (≤500 each) + Description (≤2000) + Backend (≤250 bytes) |
| **eBay** | Title (≤80) + HTML Description |
| **Walmart** | Title (≤75) + Short Desc (≤150) + 10 Features + Long Desc |
| **Shopify/DTC** | SEO Title (≤60) + Meta Desc (≤160) + Product Description |
| **Etsy** | Title (≤140) + Description + 13 Tags (≤20 each) |
| **TikTok Shop** | Title (≤255) + Description (≤1000) |
| **Lazada/Shopee** | Title (≤120) + 5 Highlights + Description |

## Usage Examples

### Mode A — Create
```
Create a listing for my yoga mat on eBay UK.
Competitors: https://www.ebay.co.uk/itm/123456789, https://www.ebay.co.uk/itm/987654321
My product: 6mm TPE, non-slip, carrying strap included. Brand: ZenMat. Tone: Friendly.
```

```
Platform: Etsy. Product: hand-poured soy candle, lavender scent, 8oz glass jar, 40-hour burn time.
Target audience: gift buyers. Tone: Luxury.
```

### Mode B — Optimize
```
Optimize this Shopify listing: https://mystore.com/products/portable-blender
Beat these competitors: https://amazon.com/dp/B09V3KXJPB, https://walmart.com/ip/123456
```

```
Find keyword gaps and rewrite this Etsy listing:
[paste current title, description, and tags]
```

---

## Handling Incomplete Input

If user doesn't provide enough info, ask upfront:

```
To generate your listing, I need:

**Required:**
- Platform (eBay / Walmart / Shopify / Etsy / TikTok Shop / Lazada / Shopee)
- Product name and key features
- Brand name

**Recommended (better results):**
- 1-3 competitor URLs to analyze
- Target audience
- Tone preference (Professional / Friendly / Urgent / Luxury)

Which mode?
- **A — Create**: I'm writing a new listing from scratch
- **B — Optimize**: I have an existing listing to improve

💡 For Amazon listings, I recommend using [amazon-listing-optimization](https://github.com/nexscope-ai/Amazon-Skills/tree/main/amazon-listing-optimization) — it's optimized for Amazon's Cosmo algorithm.
```

---

## Mode A Workflow — Create New Listing

### Step 1: Collect Product Info

| Field | Required | Example |
|-------|----------|---------|
| `product_name` | ✅ | Portable blender |
| `platform` | ✅ | Etsy |
| `brand` | ✅ | BlendJet |
| `key_features` | ✅ | USB-C, 6 blades, BPA-free |
| `specs` | ✅ | 380ml, 175W motor |
| `target_audience` | 👍 | Gym-goers, travelers |
| `use_cases` | 👍 | Smoothies, protein shakes |
| `competitor_urls` | 👍 | 1-3 URLs to analyze |
| `tone` | Optional | Professional (default) / Friendly / Luxury / Urgent |

### Step 2: Gather Keywords

**If competitor URLs provided:**

1. Fetch each competitor page:
   ```
   Use web_fetch on each competitor URL.
   Extract: title, bullets/features, description, price, review count, brand name.
   ```

2. If `web_fetch` fails or returns incomplete data:
   ```
   Fallback: web_search for "[product title from URL]" site:[platform].com
   Extract data from search snippets.
   ```

3. Parse competitor content and extract keywords in these categories:
   - **Product-type terms**: What it IS (yoga mat, exercise mat)
   - **Feature terms**: What it DOES (non-slip, eco-friendly)
   - **Use-case terms**: WHERE/WHEN used (home gym, yoga studio)
   - **Audience terms**: WHO buys (beginners, athletes)
   - **Attribute terms**: Specs (6mm, TPE material)

4. Expand beyond competitors:
   ```
   web_search: "[product type]" best seller features what buyers want
   web_search: "[product type]" review complaints common issues
   web_search: site:[platform].com "[product type]"
   ```

**If no competitor URLs provided:**

1. Discover keywords via web search:
   ```
   web_search: "[product name]" best seller [platform] features
   web_search: "[product name]" review what customers love
   web_search: "[product name]" vs alternatives comparison
   web_search: site:[platform].com "[product name]"
   ```

2. Extract keywords from top 5 results following the same categories above.

⚠️ **Critical**: Remove all competitor brand names — never include them in output.

### Step 3: Score and Prioritize Keywords

Score each keyword (1-9 points):

| Dimension | Scoring |
|-----------|---------|
| **Frequency** | In 3+ competitor titles = 3 pts / In 1-2 = 2 pts / Bullets only = 1 pt |
| **Relevance** | Core descriptor = 3 pts / Feature = 2 pts / Peripheral = 1 pt |
| **Opportunity** | Few competitors use = 3 pts / Most use = 2 pts / All use = 1 pt |

Assign to tiers:
```
🔴 Primary (7-9 pts)   → Title
🟡 Secondary (4-6 pts) → Bullets / Features
🟢 Tertiary (2-3 pts)  → Description
⚪ Backend (1 pt)       → Tags / Search Terms
```

### Step 4: Generate Copy

Proceed to **Generate Copy** section.

---

## Mode B Workflow — Optimize Existing Listing

### Step 1: Analyze Current Listing

User may provide:
- **Full listing copy** (title, bullets, description pasted directly)
- **Product URL** (e.g., `https://www.etsy.com/listing/123456`)
- **Platform + product identifier** (e.g., "Etsy listing 123456")

**If user provides URL or identifier only:**
```
Use web_fetch on the provided URL.
Extract: current title, bullets/features, description, tags (if visible), price.
```

If `web_fetch` fails:
```
Fallback: web_search for the product title or identifier.
Ask user to paste the listing content manually if data is incomplete.
```

**Once listing content is obtained**, parse and extract:
- All keywords currently present
- Structure and format used
- Obvious gaps (missing features, weak benefits, no FABE structure)

### Step 2: Gather Target Keywords

**If competitor URLs provided:**

Follow the same competitor analysis process as Mode A Step 2:
1. `web_fetch` each competitor URL
2. Extract their keywords
3. Expand via web search

**If no competitor URLs provided:**

Discover ideal keywords for the product type:
```
web_search: "[product type]" top keywords [platform] 2024 2025
web_search: "[product type]" best seller features
web_search: site:[platform].com "[product type]" top listings
```

### Step 3: Gap Analysis

Compare current keywords vs. target keywords:

```
## Keyword Gap Analysis

### ✅ Keywords You Already Have
| Keyword | Title | Bullets | Description |
|---------|-------|---------|-------------|
| yoga mat | ✅ | ✅ | ✅ |
| exercise mat | ❌ | ✅ | ❌ |

### ❌ Keywords You're Missing
| Keyword | Priority | Recommendation |
|---------|----------|----------------|
| non-slip | 🔴 High | Add to title |
| eco-friendly | 🟡 Medium | Add to bullet 2 |
| extra thick | 🟡 Medium | Add to bullet 3 |

Current Coverage: 12/20 keywords (60%)
Target Coverage: 90%+
```

### Step 4: Rewrite

Generate optimized copy incorporating missing keywords.

Show **Before → After** for each component.

Proceed to **Generate Copy** section.

---

## Generate Copy

Final step for all modes after keyword priority table is built.

### Writing Framework: FABE

Apply to every bullet:

```
F — Feature:   What the product HAS or DOES
A — Advantage: Why this is BETTER than alternatives
B — Benefit:   What this MEANS for the customer
E — Evidence:  Spec, number, or proof that backs the claim
```

**Lead with the Benefit** — customers buy outcomes, not features.

Example:
```
❌ "Made with BPA-free Tritan plastic"
✅ "SAFE FOR YOUR FAMILY — BPA-free Tritan plastic means no harmful chemicals leaching into your smoothies, even after 1000+ uses"
```

### Platform-Specific Writing Rules

#### Amazon (Cosmo Algorithm)
- **Title**: Brand + Primary Keyword + Attribute + Attribute + Secondary Keyword, ≤200 chars
- **Bullets**: [CAPS HEADER] — Benefit-led sentence with 1-2 keywords embedded
- **Description**: Hook → Features → Use cases → What's in box → CTA
- **Backend**: Space-separated keywords, no duplicates, ≤250 bytes
- ⚠️ **Cosmo tip**: Use situational language (when/where/why), cover multiple use cases
- 💡 For advanced Amazon optimization, consider [amazon-listing-optimization](https://github.com/nexscope-ai/Amazon-Skills/tree/main/amazon-listing-optimization)

#### eBay (Cassini Algorithm)
- **Title**: Front-load exact-match keywords, 80 chars max
- **Description**: Repeat top 3 keywords naturally throughout, include specs table in HTML

#### Walmart
- **Title**: Brand + product name + primary attribute, ≤75 chars
- **Short Desc**: One-sentence value prop with primary keyword
- **Features**: 10 attribute-focused bullets, one fact per bullet

#### Shopify/DTC (Google SEO)
- **SEO Title**: Primary keyword + brand, written for Google (not just product name)
- **Meta Desc**: Keyword + benefit + CTA, drives CTR from search results
- **Description**: Storytelling structure with `<h2>`, `<ul>`, `<strong>` for on-page SEO

#### Etsy (Tag Matching)
- **Title**: Long-tail keyword phrase first, then style/material/occasion
- **Description**: Conversational, first 160 chars = meta description
- **Tags**: 13 tags (≤20 chars each), match phrases used in title exactly

#### TikTok Shop (Social Commerce)
- **Title**: Lead with problem or desire ("Tired of X?") → product → top feature
- **Description**: Hook → pain point → solution → 3 bullets → CTA. Conversational, emoji-friendly.

#### Lazada/Shopee
- **Title**: Brand + product + model + material + key attribute (completeness over cleverness)
- **Highlights**: 5 short bullets, one feature per line, spec-focused
- **Description**: Feature table + expanded use cases

### Tone Guide

| Tone | Style | Best For |
|------|-------|----------|
| **Professional** | Authoritative, spec-focused, trust-building | Electronics, tools, B2B |
| **Friendly** | Conversational, benefit-focused, relatable | Kitchen, lifestyle, gifts |
| **Urgent** | Scarcity-driven, action words, problem-solving | Health, safety, seasonal |
| **Luxury** | Premium, sensory language, exclusivity | Beauty, fashion, premium goods |

Default: **Professional** if not specified.

---

## Output Format

```
# ✅ Your Listing — Ready to Copy

Platform: [Platform] | Marketplace: [XX] | Tone: [Tone]

## Title
[title — copy directly into platform]

## Bullets / Features
1. [CAPS HEADER] — [text]
2. [CAPS HEADER] — [text]
3. [CAPS HEADER] — [text]
4. [CAPS HEADER] — [text]
5. [CAPS HEADER] — [text]

## Description
[description — copy directly into platform]

## Tags / Keywords
[keywords formatted per platform rules]

---

# 📊 Diagnostic Report

**Mode:** [A/B] | **Competitors analyzed:** [N] | **Keywords scored:** [N]

## Keyword Priority Table
| # | Keyword | Score | Tier | Placed In |
|---|---------|-------|------|-----------|
| 1 | [keyword] | 8 | 🔴 | Title |
| 2 | [keyword] | 6 | 🟡 | Bullet 1 |

## Keyword Coverage Map
| Keyword | Title | Bullets | Desc | Tags | Status |
|---------|-------|---------|------|------|--------|
| [kw] | ✅ | ✅ | ✅ | — | 🟢 |
| [kw] | ✅ | ❌ | ✅ | ✅ | 🟡 |

Coverage: X/Y keywords (Z%)
🟢 90%+ Excellent · 🟡 70-89% Good · 🔴 <70% Needs work

## ⚠️ Excluded Competitor Brands
[brands found in competitor copy — excluded from all output]
```

---

## Integration with Other Skills

Looking for more e-commerce tools? Check out our other skill collections:

- **[Amazon Skills](https://github.com/nexscope-ai/Amazon-Skills)** — Specialized tools for Amazon sellers: keyword research, listing optimization, PPC campaigns, sales estimation
- **[eCommerce Skills](https://github.com/nexscope-ai/eCommerce-Skills)** — Cross-platform tools for all e-commerce businesses

---

## Limitations

This skill uses publicly available data via web search and page fetching. For real-time market data, exact search volumes, and advanced analytics, check out **[Nexscope](https://nexscope.ai)**.

---

**Part of [Nexscope AI](https://www.nexscope.ai/) — AI tools for e-commerce sellers.**

ClawHub Research Marketing+2

Etsy Seo

Skill

Etsy SEO analyzer and optimizer. Improve search visibility with title optimization, tag analysis, description scoring, and keyword research. Includes SEO sco...

---
name: etsy-seo
version: 1.0.0
author: Nexscope AI
description: "Etsy SEO analyzer and optimizer. Improve search visibility with title optimization, tag analysis, description scoring, and keyword research. Includes SEO scoring (0-100), long-tail keyword suggestions, and prioritized action plans. No API key required."
metadata: {"nexscope":{"emoji":"🔍","category":"ecommerce"}}
---

# Etsy SEO 🔍

Analyze and optimize Etsy listings for better search visibility.

## Installation

```bash
npx skills add nexscope-ai/eCommerce-Skills --skill etsy-seo -g
```

## Features

- **SEO Score** — 0-100 comprehensive rating
- **Title Optimization** — Keyword placement, length analysis
- **Tag Analysis** — 13 tag optimization, long-tail suggestions
- **Description Analysis** — First 160 chars, keyword density
- **Attribute Check** — Completeness validation
- **Keyword Research** — Category-based suggestions
- **Action Plan** — Prioritized improvement roadmap

## SEO Scoring Weights

| Dimension | Weight | Max Score |
|-----------|--------|-----------|
| Title | 30% | 100 |
| Tags | 25% | 100 |
| Description | 20% | 100 |
| Attributes | 15% | 100 |
| Images | 10% | 100 |

## Etsy Tag Rules

| Rule | Specification |
|------|---------------|
| Quantity | Max 13 tags |
| Length | Max 20 characters each |
| Format | Multi-word phrases allowed |
| Strategy | Long-tail + synonyms + attributes |

## Title Best Practices

```
[Core Keyword] + [Attributes] + [Material/Style] + [Use Case/Occasion]

✅ Good:
"Personalized Name Bracelet, Custom Gold Bracelet for Women, Birthday Gift"

❌ Bad:
"Beautiful Handmade Bracelet"
```

## Usage

### Interactive Mode

```bash
python3 scripts/analyzer.py
```

### With Listing Data

```bash
python3 scripts/analyzer.py '{
  "title": "Handmade Silver Ring",
  "tags": ["silver ring", "handmade jewelry"],
  "description": "Beautiful handmade ring...",
  "category": "Jewelry"
}'
```

### Demo Mode

```bash
python3 scripts/analyzer.py --demo
```

## Output Example

```
🔍 Etsy SEO Analysis Report

Listing: Personalized Name Bracelet
Category: Jewelry > Bracelets

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 SEO SCORE: 72/100 ⚠️

Title:       85/100 ████████░░
Tags:        65/100 ██████░░░░
Description: 70/100 ███████░░░
Attributes:  80/100 ████████░░
Images:      60/100 ██████░░░░

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📝 TITLE ANALYSIS

Current: "Handmade Silver Bracelet"
Length: 24/140 characters ⚠️ Too short

Issues:
• Missing core keyword at start
• No personalization keywords
• Missing occasion/gift keywords

Suggested:
"Personalized Silver Bracelet, Custom Name Bracelet, Birthday Gift for Her"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🏷️ TAG ANALYSIS

Used: 8/13 tags ⚠️ Add 5 more

Current Tags:
✅ silver bracelet
✅ handmade jewelry
⚠️ bracelet (too generic)

Suggested Tags:
+ personalized bracelet
+ custom name jewelry
+ birthday gift for women
+ anniversary gift
+ minimalist bracelet

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 ACTION PLAN

Priority | Action                      | Impact
──────────────────────────────────────────────
HIGH     | Rewrite title with keywords | +15 score
HIGH     | Add 5 more tags             | +10 score
MEDIUM   | Optimize first 160 chars    | +8 score
LOW      | Add more product photos     | +5 score
```

## Keyword Research

The tool suggests keywords based on:
- Category trends
- Competitor analysis
- Search volume indicators
- Long-tail variations

## Optimization Workflow

```
Analyze current listing
      ↓
Score each dimension
      ↓
Identify gaps
      ↓
Generate suggestions
      ↓
Prioritize actions
      ↓
Track improvements
```

---

**Part of [Nexscope AI](https://www.nexscope.ai/) — AI tools for e-commerce sellers.**

FILE:scripts/analyzer.py
#!/usr/bin/env python3
"""
Etsy SEO Analyzer - Core Engine
Etsy SEO Analyze - Core Engine

Features:
- SEO Overall Rating (0-100)
- TitleOptimization Suggestions
- 13 TagRecommended
- DescriptionOptimization Suggestions
- KeywordsResearch
- Competitor SEO Analyze
- Store SEO Optimization
- Attribute fillingCheck

Version: 1.0.0
"""

import json
import re
from dataclasses import dataclass, field
from typing import List, Dict, Optional, Tuple
from enum import Enum
from collections import Counter
import sys


class SEOGrade(Enum):
    """SEO Grade"""
    EXCELLENT = "A"   # 90-100
    GOOD = "B"        # 70-89
    AVERAGE = "C"     # 50-69
    POOR = "D"        # 30-49
    CRITICAL = "F"    # 0-29


# ============================================================
# Etsy PopularKeywordsLibrary (By category)
# ============================================================

ETSY_KEYWORDS = {
    "jewelry": [
        "handmade jewelry", "personalized necklace", "custom bracelet",
        "birthstone ring", "minimalist earrings", "gold filled",
        "sterling silver", "dainty jewelry", "layered necklace",
        "initial jewelry", "gift for her", "bridesmaid gift",
    ],
    "home_decor": [
        "wall art", "home decor", "farmhouse decor", "boho decor",
        "personalized sign", "custom portrait", "macrame", "plant holder",
        "candle holder", "throw pillow", "wall hanging", "housewarming gift",
    ],
    "clothing": [
        "vintage clothing", "handmade dress", "boho style", "linen clothing",
        "custom t-shirt", "embroidered", "sustainable fashion", "cottagecore",
        "oversized sweater", "matching set", "loungewear", "festival outfit",
    ],
    "accessories": [
        "leather wallet", "handmade bag", "personalized keychain",
        "phone case", "hair accessories", "scrunchie", "tote bag",
        "crossbody bag", "beanie", "scarf", "belt", "sunglasses chain",
    ],
    "art": [
        "digital download", "printable art", "wall print", "custom portrait",
        "pet portrait", "watercolor", "illustration", "line art",
        "minimalist art", "abstract art", "nursery art", "office decor",
    ],
    "craft_supplies": [
        "beads", "charms", "fabric", "yarn", "patterns", "stickers",
        "stamps", "dies", "embellishments", "ribbon", "findings",
    ],
    "wedding": [
        "wedding invitation", "bridal jewelry", "bridesmaid gift",
        "wedding decor", "cake topper", "guest book", "veil",
        "wedding favor", "flower girl", "groomsmen gift", "engagement",
    ],
    "default": [
        "handmade", "custom", "personalized", "gift", "unique",
        "vintage", "boho", "minimalist", "eco friendly", "sustainable",
    ],
}

# Long-tailKeywordsTemplate
LONG_TAIL_TEMPLATES = [
    "{keyword} for women",
    "{keyword} for men",
    "{keyword} gift",
    "personalized {keyword}",
    "custom {keyword}",
    "handmade {keyword}",
    "{keyword} for mom",
    "{keyword} for her",
    "{keyword} for him",
    "vintage {keyword}",
]


# ============================================================
# Data Structures
# ============================================================

@dataclass
class ListingInfo:
    """ProductInformation"""
    title: str = ""
    tags: List[str] = field(default_factory=list)
    description: str = ""
    category: str = "default"
    attributes: Dict[str, str] = field(default_factory=dict)
    price: float = 0.0
    images: int = 0
    image_alts: List[str] = field(default_factory=list)
    url: str = ""


@dataclass
class ShopInfo:
    """StoreInformation"""
    name: str = ""
    announcement: str = ""
    about: str = ""
    policies: str = ""
    sections: List[str] = field(default_factory=list)


@dataclass
class SEOScore:
    """SEO Rating"""
    total: int = 0
    grade: SEOGrade = SEOGrade.CRITICAL
    title_score: int = 0
    tags_score: int = 0
    description_score: int = 0
    attributes_score: int = 0
    images_score: int = 0


@dataclass
class TitleAnalysis:
    """TitleAnalyze"""
    length: int = 0
    max_length: int = 140
    keyword_count: int = 0
    has_main_keyword: bool = False
    readability: str = ""
    issues: List[str] = field(default_factory=list)
    suggestions: List[str] = field(default_factory=list)
    optimized_title: str = ""


@dataclass
class TagsAnalysis:
    """TagAnalyze"""
    count: int = 0
    max_count: int = 13
    avg_length: float = 0.0
    long_tail_count: int = 0
    missing_count: int = 0
    issues: List[str] = field(default_factory=list)
    suggested_tags: List[str] = field(default_factory=list)


@dataclass
class DescriptionAnalysis:
    """DescriptionAnalyze"""
    length: int = 0
    first_160_chars: str = ""
    keyword_density: float = 0.0
    has_call_to_action: bool = False
    issues: List[str] = field(default_factory=list)
    suggestions: List[str] = field(default_factory=list)


@dataclass
class SEOReport:
    """SEO AnalyzeReport"""
    listing: ListingInfo
    score: SEOScore
    title_analysis: TitleAnalysis
    tags_analysis: TagsAnalysis
    description_analysis: DescriptionAnalysis
    keyword_suggestions: List[str]
    competitor_insights: List[str]
    action_items: List[Dict]
    summary: str
    summary_zh: str


# ============================================================
# AnalyzeFunction
# ============================================================

def analyze_title(title: str, category: str) -> Tuple[int, TitleAnalysis]:
    """AnalyzeTitle"""
    analysis = TitleAnalysis()
    analysis.length = len(title)
    issues = []
    suggestions = []
    score = 100
    
    # DegreeCheck (Etsy Restriction 140 Character)
    if analysis.length < 40:
        issues.append("Title too short (< 40 chars)")
        score -= 20
    elif analysis.length > 140:
        issues.append("Title exceeds 140 character limit")
        score -= 30
    elif analysis.length < 80:
        suggestions.append("Consider using more characters (ideal: 80-140)")
        score -= 5
    
    # KeywordsCheck
    category_keywords = ETSY_KEYWORDS.get(category, ETSY_KEYWORDS["default"])
    title_lower = title.lower()
    
    found_keywords = [kw for kw in category_keywords if kw.lower() in title_lower]
    analysis.keyword_count = len(found_keywords)
    analysis.has_main_keyword = analysis.keyword_count > 0
    
    if not analysis.has_main_keyword:
        issues.append("No category keywords found in title")
        score -= 25
    elif analysis.keyword_count < 2:
        suggestions.append("Add more relevant keywords")
        score -= 10
    
    # CanReadabilityCheck
    words = title.split()
    if len(words) < 5:
        issues.append("Title has too few words")
        score -= 15
    
    # Special charactersCheck
    if re.search(r'[!@#$%^&*()_+=\[\]{}|\\:";\'<>?/]', title):
        suggestions.append("Avoid special characters in title")
        score -= 5
    
    #  all  big writeCheck
    if title.isupper():
        issues.append("Avoid ALL CAPS in title")
        score -= 15
    
    analysis.issues = issues
    analysis.suggestions = suggestions
    analysis.readability = "Good" if len(issues) == 0 else "Needs improvement"
    
    # GenerateOptimization SuggestionsTitle
    if not analysis.has_main_keyword and category_keywords:
        base_keyword = category_keywords[0]
        analysis.optimized_title = f"{base_keyword.title()}, {title}"[:140]
    
    return max(0, score), analysis


def analyze_tags(tags: List[str], category: str) -> Tuple[int, TagsAnalysis]:
    """AnalyzeTag"""
    analysis = TagsAnalysis()
    analysis.count = len(tags)
    issues = []
    score = 100
    
    # QuantityCheck (Etsy Allow 13 )
    analysis.missing_count = 13 - analysis.count
    if analysis.count < 13:
        issues.append(f"Only {analysis.count}/13 tags used")
        score -= (13 - analysis.count) * 5
    
    # DegreeAnalyze
    if tags:
        lengths = [len(tag) for tag in tags]
        analysis.avg_length = sum(lengths) / len(lengths)
        
        # Check  short Tag
        short_tags = [t for t in tags if len(t) < 5]
        if short_tags:
            issues.append(f"{len(short_tags)} tags are too short")
            score -= len(short_tags) * 3
        
        # ChecksuperTag (20 Character limit)
        long_tags = [t for t in tags if len(t) > 20]
        if long_tags:
            issues.append(f"{len(long_tags)} tags exceed 20 characters")
            score -= len(long_tags) * 5
    
    # Long-tailKeywordsCheck
    analysis.long_tail_count = len([t for t in tags if ' ' in t])
    if analysis.long_tail_count < 5:
        issues.append("Need more multi-word (long-tail) tags")
        score -= 10
    
    #  heavy complexCheck
    unique_tags = set(t.lower() for t in tags)
    if len(unique_tags) < len(tags):
        issues.append("Duplicate tags found")
        score -= 10
    
    analysis.issues = issues
    
    # GenerateRecommendedTag
    category_keywords = ETSY_KEYWORDS.get(category, ETSY_KEYWORDS["default"])
    existing_lower = set(t.lower() for t in tags)
    
    suggested = []
    for kw in category_keywords:
        if kw.lower() not in existing_lower and len(suggested) < analysis.missing_count:
            suggested.append(kw)
    
    # AddLong-tailVariant
    if suggested and len(suggested) < analysis.missing_count:
        base = suggested[0].split()[0] if suggested else category_keywords[0]
        for template in LONG_TAIL_TEMPLATES:
            tag = template.format(keyword=base)
            if len(tag) <= 20 and tag.lower() not in existing_lower:
                suggested.append(tag)
                if len(suggested) >= analysis.missing_count:
                    break
    
    analysis.suggested_tags = suggested[:analysis.missing_count]
    
    return max(0, score), analysis


def analyze_description(description: str, category: str) -> Tuple[int, DescriptionAnalysis]:
    """AnalyzeDescription"""
    analysis = DescriptionAnalysis()
    analysis.length = len(description)
    issues = []
    suggestions = []
    score = 100
    
    # DegreeCheck
    if analysis.length < 100:
        issues.append("Description too short (< 100 chars)")
        score -= 30
    elif analysis.length < 300:
        suggestions.append("Consider a longer description (300+ chars)")
        score -= 10
    
    #  before  160 CharacterCheck (SearchEngineSummary)
    analysis.first_160_chars = description[:160]
    
    # KeywordsdenseDegree
    category_keywords = ETSY_KEYWORDS.get(category, ETSY_KEYWORDS["default"])
    desc_lower = description.lower()
    keyword_count = sum(1 for kw in category_keywords if kw.lower() in desc_lower)
    analysis.keyword_density = keyword_count / max(1, len(description.split())) * 100
    
    if keyword_count == 0:
        issues.append("No category keywords in description")
        score -= 20
    
    # CTA Check
    cta_phrases = ["shop now", "buy now", "order today", "click", "add to cart", "check out", "contact"]
    analysis.has_call_to_action = any(cta in desc_lower for cta in cta_phrases)
    if not analysis.has_call_to_action:
        suggestions.append("Add a call-to-action")
        score -= 5
    
    # ParagraphCheck
    if '\n' not in description and analysis.length > 200:
        suggestions.append("Break into paragraphs for readability")
        score -= 5
    
    analysis.issues = issues
    analysis.suggestions = suggestions
    
    return max(0, score), analysis


def calculate_seo_score(
    title_score: int,
    tags_score: int,
    desc_score: int,
    attr_score: int,
    img_score: int
) -> SEOScore:
    """CalculateComprehensive SEO Rating"""
    
    # Weight: Title30%, Tag25%, Description20%, Property15%, Image10%
    total = int(
        title_score * 0.30 +
        tags_score * 0.25 +
        desc_score * 0.20 +
        attr_score * 0.15 +
        img_score * 0.10
    )
    
    if total >= 90:
        grade = SEOGrade.EXCELLENT
    elif total >= 70:
        grade = SEOGrade.GOOD
    elif total >= 50:
        grade = SEOGrade.AVERAGE
    elif total >= 30:
        grade = SEOGrade.POOR
    else:
        grade = SEOGrade.CRITICAL
    
    return SEOScore(
        total=total,
        grade=grade,
        title_score=title_score,
        tags_score=tags_score,
        description_score=desc_score,
        attributes_score=attr_score,
        images_score=img_score,
    )


def generate_action_items(
    title_analysis: TitleAnalysis,
    tags_analysis: TagsAnalysis,
    desc_analysis: DescriptionAnalysis,
    score: SEOScore
) -> List[Dict]:
    """GenerateActionRecommendation"""
    actions = []
    
    # TitleIssue
    for issue in title_analysis.issues:
        actions.append({
            "category": "Title",
            "category_zh": "Title",
            "priority": "P1",
            "action": f"Fix: {issue}",
            "action_zh": f"Fix: {issue}",
        })
    
    # TagIssue
    if tags_analysis.missing_count > 0:
        actions.append({
            "category": "Tags",
            "category_zh": "Tag",
            "priority": "P1",
            "action": f"Add {tags_analysis.missing_count} more tags",
            "action_zh": f"Add {tags_analysis.missing_count} Tag",
        })
    
    for issue in tags_analysis.issues:
        if "missing" not in issue.lower():
            actions.append({
                "category": "Tags",
                "category_zh": "Tag",
                "priority": "P2",
                "action": f"Fix: {issue}",
                "action_zh": f"Fix: {issue}",
            })
    
    # DescriptionIssue
    for issue in desc_analysis.issues:
        actions.append({
            "category": "Description",
            "category_zh": "Description",
            "priority": "P2",
            "action": f"Fix: {issue}",
            "action_zh": f"Fix: {issue}",
        })
    
    return actions


def analyze_listing(listing: ListingInfo) -> SEOReport:
    """AnalyzeProduct SEO"""
    
    # Analyze each Part
    title_score, title_analysis = analyze_title(listing.title, listing.category)
    tags_score, tags_analysis = analyze_tags(listing.tags, listing.category)
    desc_score, desc_analysis = analyze_description(listing.description, listing.category)
    
    # PropertyRating (simple)
    attr_score = 100 if len(listing.attributes) >= 5 else len(listing.attributes) * 20
    
    # ImageRating
    img_score = min(100, listing.images * 10) if listing.images > 0 else 0
    
    # Overall Rating
    score = calculate_seo_score(title_score, tags_score, desc_score, attr_score, img_score)
    
    # KeywordsRecommendation
    category_keywords = ETSY_KEYWORDS.get(listing.category, ETSY_KEYWORDS["default"])
    keyword_suggestions = category_keywords[:10]
    
    # ActionRecommendation
    action_items = generate_action_items(title_analysis, tags_analysis, desc_analysis, score)
    
    # Summary
    summary = f"SEO Score: {score.total}/100 ({score.grade.value}) | Title: {title_score} | Tags: {tags_score} | Desc: {desc_score}"
    summary_zh = f"SEO Rating: {score.total}/100 ({score.grade.value}) | Title: {title_score} | Tag: {tags_score} | Description: {desc_score}"
    
    return SEOReport(
        listing=listing,
        score=score,
        title_analysis=title_analysis,
        tags_analysis=tags_analysis,
        description_analysis=desc_analysis,
        keyword_suggestions=keyword_suggestions,
        competitor_insights=[],
        action_items=action_items,
        summary=summary,
        summary_zh=summary_zh,
    )


# ============================================================
# OutputFormat
# ============================================================

def format_report(report: SEOReport, lang: str = "en") -> str:
    """FormatReport"""
    s = report.score
    t = report.title_analysis
    tg = report.tags_analysis
    d = report.description_analysis
    
    grade_colors = {"A": "🟢", "B": "🔵", "C": "🟡", "D": "🟠", "F": "🔴"}
    grade_icon = grade_colors.get(s.grade.value, "⚪")
    
    if lang == "zh":
        lines = [
            "🏷️ **Etsy SEO AnalyzeReport**",
            "",
            f"**Product**: {report.listing.title[:50]}...",
            f"**Category**: {report.listing.category}",
            "",
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            f"## {grade_icon} SEO Overall Rating: {s.total}/100 (Grade {s.grade.value})",
            "",
            "| dimensionDegree | Score | Weight |",
            "|------|------|------|",
            f"| Title | {s.title_score}/100 | 30% |",
            f"| Tag | {s.tags_score}/100 | 25% |",
            f"| Description | {s.description_score}/100 | 20% |",
            f"| Property | {s.attributes_score}/100 | 15% |",
            f"| Image | {s.images_score}/100 | 10% |",
            "",
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            "## 📝 TitleAnalyze",
            "",
            f"**Degree**: {t.length}/{t.max_length} Character",
            f"**Keywords**: {t.keyword_count} ",
            f"**CanReadability**: {t.readability}",
            "",
        ]
        
        if t.issues:
            lines.append("**Issue:**")
            for issue in t.issues:
                lines.append(f"- ❌ {issue}")
            lines.append("")
        
        if t.suggestions:
            lines.append("**Recommendation:**")
            for sug in t.suggestions:
                lines.append(f"- 💡 {sug}")
            lines.append("")
        
        if t.optimized_title:
            lines.extend([
                "**Optimization after TitleExample:**",
                f"```{t.optimized_title}```",
                "",
            ])
        
        lines.extend([
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            "## 🏷️ TagAnalyze",
            "",
            f"** already Use**: {tg.count}/13 ",
            f"**Long-tail Keywords**: {tg.long_tail_count} ",
            f"**AverageDegree**: {tg.avg_length:.1f} Character",
            "",
        ])
        
        if tg.issues:
            lines.append("**Issue:**")
            for issue in tg.issues:
                lines.append(f"- ❌ {issue}")
            lines.append("")
        
        if tg.suggested_tags:
            lines.extend([
                "**RecommendedAddTag:**",
                "",
            ])
            for i, tag in enumerate(tg.suggested_tags, 1):
                lines.append(f"{i}. `{tag}`")
            lines.append("")
        
        lines.extend([
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            "## 📄 DescriptionAnalyze",
            "",
            f"**Degree**: {d.length} Character",
            f"**KeywordsdenseDegree**: {d.keyword_density:.1f}%",
            f"** has  CTA**: {'✅  is ' if d.has_call_to_action else '❌ no'}",
            "",
        ])
        
        if d.issues or d.suggestions:
            for issue in d.issues:
                lines.append(f"- ❌ {issue}")
            for sug in d.suggestions:
                lines.append(f"- 💡 {sug}")
            lines.append("")
        
        if report.keyword_suggestions:
            lines.extend([
                "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
                "",
                "## 🔑 RecommendedKeywords",
                "",
                ", ".join([f"`{kw}`" for kw in report.keyword_suggestions[:8]]),
                "",
            ])
        
        if report.action_items:
            lines.extend([
                "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
                "",
                "## 📋 Action Plan",
                "",
            ])
            for action in report.action_items[:5]:
                lines.append(f"**[{action['priority']}] [{action['category_zh']}]** {action['action_zh']}")
            lines.append("")
        
        lines.extend([
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            report.summary_zh,
        ])
    else:
        # English version (similar structure)
        lines = [
            "🏷️ **Etsy SEO Analysis Report**",
            "",
            f"**Listing**: {report.listing.title[:50]}...",
            f"**Category**: {report.listing.category}",
            "",
            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
            "",
            f"## {grade_icon} SEO Score: {s.total}/100 (Grade {s.grade.value})",
            "",
            "| Dimension | Score | Weight |",
            "|-----------|-------|--------|",
            f"| Title | {s.title_score}/100 | 30% |",
            f"| Tags | {s.tags_score}/100 | 25% |",
            f"| Description | {s.description_score}/100 | 20% |",
            f"| Attributes | {s.attributes_score}/100 | 15% |",
            f"| Images | {s.images_score}/100 | 10% |",
            "",
            "## 📝 Title Analysis",
            f"Length: {t.length}/{t.max_length} | Keywords: {t.keyword_count}",
            "",
        ]
        
        if t.issues:
            for issue in t.issues:
                lines.append(f"- ❌ {issue}")
        
        if tg.suggested_tags:
            lines.extend([
                "",
                "## 🏷️ Suggested Tags",
                ", ".join([f"`{tag}`" for tag in tg.suggested_tags]),
            ])
        
        lines.extend(["", report.summary])
    
    return "\n".join(lines)


# ============================================================
# CLI
# ============================================================

def main():
    lang = "zh" if "--zh" in sys.argv else "en"
    
    # DemoData
    listing = ListingInfo(
        title="Beautiful Handmade Bracelet",
        tags=["bracelet", "handmade", "gift", "jewelry", "beaded"],
        description="A beautiful handmade bracelet perfect for any occasion. Made with high quality beads.",
        category="jewelry",
        attributes={"material": "beads", "color": "blue"},
        images=5,
    )
    
    report = analyze_listing(listing)
    print(format_report(report, lang))


if __name__ == "__main__":
    main()

Ecommerce Ppc Strategy Planner

Skill

Cross-platform PPC strategy planner for ecommerce businesses. Analyzes your product and margins, recommends the right advertising platforms (Google Ads, Meta...

---
name: ecommerce-ppc-strategy-planner
description: "Cross-platform PPC strategy planner for ecommerce businesses. Analyzes your product and margins, recommends the right advertising platforms (Google Ads, Meta Ads, TikTok Ads), calculates ROAS targets, allocates budget across channels, and generates platform-specific campaign briefs with ad copy and creative direction. Two modes: (A) Build — design a multi-platform ad strategy from scratch, (B) Optimize — audit existing cross-platform campaigns and reallocate budget. Works for Shopify, WooCommerce, standalone stores, and marketplace sellers expanding to external traffic. No API key required."
metadata: {"nexscope":{"emoji":"📊","category":"ecommerce"}}
---

# E-Commerce PPC Strategy Planner 📊

Plan your cross-platform advertising strategy: which platforms to use, how much to spend on each, and what campaigns to run. Generates actionable briefs for Google Ads, Meta Ads, and TikTok Ads — with ad copy and creative direction included.

## Installation

```bash
npx skills add nexscope-ai/eCommerce-Skills --skill ecommerce-ppc-strategy-planner -g
```

## Two Modes

| Mode | When to Use | Input | Output |
|------|-------------|-------|--------|
| **A — Build** | Starting ads for the first time | Product info + budget + margins | Platform recommendation + budget split + campaign briefs + ad copy |
| **B — Optimize** | Running ads but want better results | Per-platform ROAS/CPA data | Cross-platform audit + budget reallocation + optimization actions |

## Capabilities

- **ROAS financial framework**: Calculate break-even ROAS, target ROAS, and max CPA from product margins — the foundation for all platform decisions
- **Platform recommendation**: Match your product type to the right ad channels (search-intent → Google, visual/impulse → Meta, demo/novelty → TikTok)
- **Cross-platform budget allocation**: Split budget across channels based on expected ROAS and funnel stage
- **Google Ads brief**: Shopping, Search, and Performance Max campaign structures with keyword direction
- **Meta Ads brief**: Audience targeting, ad set structure, and creative hooks for Facebook + Instagram
- **TikTok Ads brief**: Video hook concepts, Spark Ads strategy, and audience targeting
- **Ad copy generation**: Headlines, descriptions, and CTAs for each platform
- **Creative brief**: Image/video specs, style direction, hook angles (not actual image/video creation)
- **Cross-platform audit**: Compare ROAS/CPA across channels and identify where to shift budget

## Usage Examples

### Mode A — Build New Strategy

```
I sell handmade candles on Shopify. Price $34, cost $8. Monthly ad budget $2,000. Help me plan which platforms to advertise on.
```

```
I'm launching a fitness resistance band set, $29.99, 60% margin. $5,000/month budget. Where should I advertise and how much on each platform?
```

```
I have a Shopify store selling pet accessories. Best sellers are dog bandanas ($15) and cat toys ($12). $1,000/month to start. What's my ad strategy?
```

### Mode B — Optimize Existing

```
Running Google Shopping (ROAS 3.2x, $3,000/mo) and Facebook ($1,800/mo, ROAS 1.4x). Margin is 45%. Should I shift budget?
```

```
My TikTok ads get tons of views but barely convert. Google Shopping is profitable. Total budget $4,000/month. Help me optimize.
```

---

## How This Skill Collects Information

**Step 1: Extract from the prompt.** Parse product type, price, margins, budget, platforms mentioned, ROAS data, store type.

**Step 2: Identify gaps.** Compare against what's needed:

Mode A critical info:
| Info | Why It's Needed |
|------|----------------|
| Product price + cost/margin | Calculate break-even ROAS and Max CPA |
| Monthly ad budget | Allocate across platforms |
| **Buyer behavior type** | Determines which platform is primary (see below) |
| Existing website traffic / email list | Determines if retargeting is viable |

Mode B critical info:
| Info | Why It's Needed |
|------|----------------|
| Per-platform spend + ROAS/CPA | Audit each platform's performance |
| Profit margin | Calculate break-even ROAS |
| Campaign duration | New campaigns need 2-4 weeks before optimization |

**Step 3: One follow-up.** Ask only for missing critical items. Always include the buyer behavior question for Mode A:

```
Mode A example:
"Nice — handmade candles at $34 with $2,000/month budget. To plan your 
strategy, I need a few things:

  1. Your product cost per unit (to calculate break-even ROAS)
  2. How do customers typically find products like yours?
     a) They search for it (e.g., 'soy candles') — they know what they want
     b) They discover it visually — they see it and want it (lifestyle, fashion, decor)
     c) They need to see it in action — demo/video is what sells it
     d) Not sure — I'll analyze and recommend
  3. Do you have existing website traffic or an email list?
     (This affects whether retargeting is viable from day one)"

Mode B example:
"Got it — Google and Facebook running. To audit properly:
  1. Your product margin (or cost + price, I'll calculate)
  2. How long have these campaigns been running? (New campaigns 
     need 2-4 weeks before optimization)"
```

The buyer behavior answer directly determines platform selection:
- **a) Search** → Google Shopping / Search is primary
- **b) Visual** → Meta Ads (Facebook / Instagram) is primary
- **c) Demo** → TikTok Ads is primary
- **d) Not sure** → Infer from product type, mark as ⚠️ estimated

**Step 4: Use estimates when stuck.** Don't block on missing data — use category benchmarks, but:
- **Mark every estimate clearly** in the output with ⚠️ (e.g., "⚠️ Estimated: conversion rate 2.5% based on home decor category average")
- **Explain what better data would change** (e.g., "If you can share your actual Shopify conversion rate, I can recalculate the ROAS target and budget split more accurately")
- **List what to provide next time** at the end of the report for more precise results

---

## Key Concepts

### ROAS (Return on Ad Spend)
The universal metric across all platforms. ROAS = Revenue ÷ Ad Spend. A 4:1 ROAS means $4 revenue for every $1 spent.

### Break-even ROAS
The minimum ROAS needed to not lose money: **Break-even ROAS = 1 ÷ Profit Margin**

| Profit Margin | Break-even ROAS | Meaning |
|:-------------:|:---------------:|---------|
| 25% | 4.0x | Need $4 revenue per $1 ad spend just to break even |
| 33% | 3.0x | |
| 50% | 2.0x | |
| 60% | 1.67x | |
| 75% | 1.33x | Higher margin = more room for ad spend |

### Target ROAS
Break-even ROAS + profit buffer. Typically 1.5-2x the break-even ROAS for sustainable growth.

### Platform ROAS Benchmarks (2025-2026)

| Platform | Average ROAS | Top Quartile | Best For |
|----------|:-----------:|:------------:|----------|
| Google Ads (Shopping) | 4.5x | 6x+ | High-intent buyers (they're already searching) |
| Meta Ads (FB/IG) | 2.2x | 4-5x | Visual products, impulse buys, retargeting (3.6x) |
| TikTok Ads | 1.4x | 2x+ | Product discovery, demo-driven, younger audiences |

Industry-wide ecommerce average: 2.87x

### Max CPA (Cost per Acquisition)
Maximum you can pay to acquire one customer: **Max CPA = Average Order Value × Profit Margin**. Example: $34 product × 50% margin = $17 max CPA.

---

## Mode A Workflow — Build Strategy

### Step A1: Collect Product Info

| Detail | How to Get It | Critical? |
|--------|--------------|:---------:|
| Product type and description | From user's prompt | ✅ Yes |
| Selling price (or AOV) | Ask or infer | ✅ Yes |
| Product cost / profit margin | Must ask user | ✅ Yes |
| Monthly ad budget | Must ask user | ✅ Yes |
| Buyer behavior type | Asked in follow-up (see "How This Skill Collects Information") | ✅ Yes |
| Store platform (Shopify, WooCommerce, etc.) | Ask or infer | Helpful |
| Existing website traffic / email list | Asked in follow-up | Helpful |
| Target market / geography | Ask or infer | Helpful |

### Step A2: Calculate ROAS Framework

```
📊 CROSS-PLATFORM FINANCIAL FRAMEWORK

Product Price (AOV):     $34.00
Product Cost:            $8.00
Profit Margin:           76.5%

Break-even ROAS:         1.31x ($1 ad spend must generate $1.31 revenue)
Target ROAS:             2.5x (maintains ~36% profit after ads)
Max CPA:                 $26.01 (max cost to acquire one sale)

Monthly Ad Budget:       $2,000
At Target ROAS (2.5x):   $5,000 expected monthly ad revenue
At Break-even (1.31x):   $2,620 minimum monthly ad revenue
```

### Step A3: Recommend Platform Mix

Match the product to the right platforms based on product characteristics:

| Product Type | Primary Platform | Secondary | Why |
|-------------|-----------------|-----------|-----|
| Commodities (people search for them) | Google Shopping | Meta retargeting | Capture existing demand |
| Visual / lifestyle products | Meta Ads | Google Shopping | Create demand through imagery |
| Novel / demo-driven products | TikTok Ads | Meta Ads | "Wow" factor drives discovery |
| High-ticket / considered purchases | Google Search | Meta retargeting | Research-heavy buyer journey |
| Repeat consumables | Meta + Email | Google Brand | Build loyalty, retarget buyers |

**Platform selection logic (based on buyer behavior answer from follow-up):**
1. User answered **a) Search** → Google Shopping is primary
2. User answered **b) Visual** → Meta is primary
3. User answered **c) Demo** → TikTok is primary
4. User answered **d) Not sure** → infer from product type using the table above (mark as ⚠️ estimated, explain reasoning)
5. Always include retargeting (Meta or Google Display) if budget > $1,000/mo AND user has existing website traffic or email list
6. If budget < $1,000/mo → pick ONE primary platform only, don't spread thin

### Step A4: Allocate Budget Across Platforms

Use this framework, adjusted for product type:

**For search-intent products (Google primary):**
| Channel | % of Budget | Purpose |
|---------|:-----------:|---------|
| Google Shopping / PMax | 50-60% | Capture high-intent buyers |
| Meta Ads (prospecting) | 20-25% | Create demand + build audiences |
| Meta/Google retargeting | 10-15% | Convert visitors who didn't buy |
| Testing (TikTok / new) | 5-10% | Discover new channels |

**For visual/impulse products (Meta primary):**
| Channel | % of Budget | Purpose |
|---------|:-----------:|---------|
| Meta Ads (prospecting) | 45-55% | Primary demand creation |
| Google Shopping | 20-25% | Capture search spillover |
| Meta/Google retargeting | 15-20% | Highest ROAS channel |
| TikTok Ads | 5-10% | Discovery + younger audience |

**For demo/novelty products (TikTok primary):**
| Channel | % of Budget | Purpose |
|---------|:-----------:|---------|
| TikTok Ads | 40-50% | Product discovery via video |
| Meta Ads | 20-30% | Broader audience + retargeting |
| Google Shopping | 10-20% | Capture search from viral interest |
| Retargeting | 10-15% | Convert viewers who didn't buy |

### Step A5: Generate Platform Briefs

For each recommended platform, output a campaign brief:

**Google Ads Brief:**
- Campaign type recommendation (Shopping, Search, Performance Max)
- Keyword themes (not full keyword list — that's for google-ads-ecommerce skill)
- Bidding strategy recommendation (Target ROAS, Maximize Conversions)
- Daily budget
- Key settings (location targeting, device bids, scheduling)

**Meta Ads Brief:**
- Campaign objective (Sales, Traffic, Engagement)
- Audience targeting: demographics, interests, behaviors, lookalikes
- Ad set structure (how many ad sets, what audiences)
- Placement recommendations (Feed, Stories, Reels)
- Daily budget per ad set

**TikTok Ads Brief:**
- Campaign objective (Conversions, Traffic)
- Targeting: demographics, interests, behaviors
- Spark Ads vs In-Feed vs TopView recommendation
- Content style recommendation (UGC, product demo, before/after)
- Daily budget

### Step A6: Generate Ad Copy and Creative Direction

For each platform, generate 3 ad copy variations AND a creative brief using these specs:

#### Google Ads Copy Specs

| Element | Max Length | Notes |
|---------|:---------:|-------|
| Headline | **30 characters** | Write 3-5 headlines; Google rotates them |
| Long headline | **90 characters** | For Performance Max / Display |
| Description | **90 characters** | Write 2-4 descriptions |
| Display path | **15 characters × 2** | e.g., /soy-candles/shop |

CTA: Chosen from Google's preset list (Shop Now, Learn More, Get Offer, Sign Up).

**Example:**
```
Headline 1: Handmade Soy Candles – $34    (30 chars)
Headline 2: 60+ Hour Clean Burn            (22 chars)
Headline 3: Free Shipping Over $50         (25 chars)
Description 1: Hand-poured soy candles with natural essential oils. Clean burn, long-lasting fragrance. Shop now.  (90 chars)
Description 2: Eco-friendly candles perfect for gifts or self-care. Made in small batches with premium soy wax.    (90 chars)
```

#### Meta Ads (Facebook / Instagram) Copy Specs

| Element | Recommended | Max | Notes |
|---------|:----------:|:---:|-------|
| Primary text | **125 chars** | 2,200 | First 125 visible before "See more" |
| Headline | **40 chars** | 255 | Below the image/video |
| Description | **30 chars** | — | Shows in some placements only |
| Image | **1080×1080** | — | Square for Feed |
| Stories/Reels | **1080×1920** | — | Vertical 9:16 |
| Video length | **15-60s** | 240 min | 15-30s performs best |

CTA: Shop Now, Learn More, Get Offer, Sign Up, Order Now.

**Example:**
```
Primary text: Your evening ritual, upgraded. Hand-poured soy candles that fill your space with natural fragrance for 60+ hours. 🕯️
Headline: Shop Handmade Soy Candles
Description: From $34 · Free Shipping
CTA: Shop Now
```

#### TikTok Ads Copy Specs

| Element | Max Length | Notes |
|---------|:---------:|-------|
| Ad text / caption | **100 characters** | Keep short — users scroll fast |
| Display name | **40 characters** | Your brand name |
| Video | **9:16 vertical** | 720×1280 minimum |
| Video length | **9-15 seconds** | Sweet spot; max 60s |
| Spark Ads | N/A | Boost existing organic posts — no separate copy needed |

CTA: Shop Now, Learn More, Download, Contact Us.

**Hook rule:** First 2-3 seconds must grab attention. Start with motion, a question, or a surprising visual — never a logo or slow intro.

**Example:**
```
Hook (0-3s): [Close-up of match striking, candle being lit in cozy room]
Caption: The only candle that lasts 60+ hours 🕯️ #soycandle #cozyvibes
CTA: Shop Now
```

#### Creative Brief (all platforms)

For each platform, also provide:
- **Visual style direction**: lifestyle, product-only, UGC, comparison, or before/after
- **Video hook concept**: What happens in the first 3 seconds (the make-or-break moment)
- **Key messages**: 2-3 bullet points the creative must communicate
- **What NOT to do**: Common mistakes for this product type (e.g., "Don't use stock photos for a handmade product")

#### Creative Asset Prompts

Generate ready-to-use prompts that users can take directly to a designer or AI image tool (Midjourney, DALL-E, Flux, etc.):

**For each recommended platform, provide 2-3 image prompts:**

```
📸 AI Image Prompt (Product Shot):
"[Product] on [surface/background], [lighting style], [camera angle], 
[mood/aesthetic], commercial product photography, [aspect ratio]"

📸 AI Image Prompt (Lifestyle):
"[Scene description with product in context], [lighting], [color palette], 
[mood], editorial photography style, [aspect ratio]"

📸 AI Image Prompt (Ad Creative):
"[Scene] with space for text overlay on [top/bottom/left], 
[style], [dimensions for platform]"
```

**For video ads, provide a shot list:**
```
🎬 Video Shot List (15s):
0-3s: [Hook — what grabs attention]
3-8s: [Product showcase — key features/benefits]
8-12s: [Social proof or lifestyle context]
12-15s: [CTA — clear next step + end card]
```

**For designer briefs, include:**
- Deliverables: exact sizes and quantities needed per platform
- Reference mood/style (e.g., "Aesop-style minimalist" or "Glossier-style friendly")
- Brand colors and fonts (if user provides them)
- What assets the designer should deliver (PSD, PNG, video files)

This section ensures the user can immediately act on the strategy — either by generating visuals with AI tools or briefing a designer/photographer.

### Step A7: Generate Complete Strategy

Compile Steps A1-A6 into the Mode A Output template below.

---

## Mode B Workflow — Optimize Existing

### Step B1: Collect Platform Data

| Detail | Critical? | Notes |
|--------|:---------:|-------|
| Platforms running | ✅ Yes | Google, Meta, TikTok, etc. |
| Per-platform spend | ✅ Yes | Monthly or daily |
| Per-platform ROAS or CPA | ✅ Yes | The core metric |
| Product profit margin | ✅ Yes | To calculate break-even |
| Campaign duration | Helpful | New campaigns need 2-4 weeks before optimization |
| CTR and conversion rates | Bonus | Deeper performance analysis |
| Best/worst performing audiences | Bonus | For audience optimization |

### Step B2: Cross-Platform Audit

Compare each platform against break-even and target ROAS:

| Platform | Spend | ROAS | vs Break-even | vs Target | Status | Action |
|----------|------:|:----:|:-------------:|:---------:|:------:|--------|
| Google Shopping | $3,000 | 4.5x | ✅ +3.2x | ✅ +2.0x | 🟢 | Scale budget |
| Meta Prospecting | $1,200 | 1.8x | ✅ +0.5x | ❌ -0.7x | 🟡 | Optimize audiences |
| Meta Retargeting | $600 | 5.2x | ✅ +3.9x | ✅ +2.7x | 🟢 | Scale budget |
| TikTok | $800 | 0.9x | ❌ -0.4x | ❌ -1.6x | 🔴 | Cut or restructure |

### Step B3: Budget Reallocation

Shift money from underperformers to winners:
- 🟢 Platforms beating target ROAS → increase budget 20-30%
- 🟡 Platforms between break-even and target → optimize before scaling
- 🔴 Platforms below break-even → cut budget 50% or pause

### Step B4: Per-Platform Optimization

For each underperforming platform, provide specific actions:
- **Google:** keyword negative list, bidding strategy change, campaign type switch
- **Meta:** audience refinement, creative refresh, placement optimization, lookalike expansion
- **TikTok:** creative hook changes, targeting adjustments, Spark Ads pivot

### Step B5: Generate Optimization Plan

Compile into the Mode B Output template below with prioritized actions and timeline.

---

## Output Formats

### Mode A Output — Multi-Platform Strategy

```
# ✅ E-Commerce PPC Strategy — Ready to Implement

## Financial Framework
Product: [name] | Price: $XX | Margin: XX%
Break-even ROAS: X.Xx | Target ROAS: X.Xx | Max CPA: $XX
Monthly Budget: $X,XXX

## Platform Mix
[Visual showing recommended platforms and % allocation]

## Platform 1: [Google Ads / Meta / TikTok]
  Budget: $XXX/month (XX%)
  Campaign Type: [type]
  Targeting: [audiences / keywords]
  Bidding: [strategy]

  Ad Copy (3 variations):
    V1: [headline] | [description] | [CTA]
    V2: ...
    V3: ...

  Creative Brief:
    Format: [dimensions + type]
    Style: [lifestyle / UGC / product demo / comparison]
    Hook: [first 3 seconds concept for video, or key visual for static]
    Key Messages: [2-3 bullet points]

  Creative Asset Prompts:
    📸 Product Shot: "[AI image prompt ready to paste into Midjourney/DALL-E]"
    📸 Lifestyle: "[AI image prompt for lifestyle scene]"
    📸 Ad Creative: "[AI image prompt with text overlay space]"
    🎬 Video (15s):
      0-3s: [Hook]
      3-8s: [Product showcase]
      8-12s: [Social proof / lifestyle]
      12-15s: [CTA + end card]

## Platform 2: [...]
  [same structure]

## Budget Summary
| Platform | Monthly | Daily | % | Expected ROAS | Expected Revenue |
|----------|---------|-------|---|:-------------:|-----------------:|
| [name]   | $XXX    | $XX   | XX% | X.Xx       | $X,XXX           |

## 30-Day Test Plan
Week 1: [launch actions]
Week 2: [check metrics, early optimizations]
Week 3: [scale winners, cut losers]
Week 4: [full review, reallocate]
```

### Mode B Output — Cross-Platform Optimization

```
# ✅ PPC Optimization Actions — Ready to Implement

## Priority 1: Budget Shifts (Do Today)
  [Platform]: $XX/mo → $XX/mo (reason)
  [Platform]: $XX/mo → $XX/mo (reason)

## Priority 2: Platform-Specific Fixes (This Week)
  [Platform]: [specific actions — audience changes, creative refresh, etc.]

## Priority 3: Testing (Next Week)
  [New audience / creative / platform to test]

## Cross-Platform Audit
[Full comparison table from Step B2]

## Expected Results (4 Weeks)
| Metric | Current | Target | Impact |
|--------|---------|--------|--------|
| Blended ROAS | X.Xx | X.Xx | +XX% |
| Monthly Revenue | $X,XXX | $X,XXX | +$X,XXX |
```

---

## Other Skills

This skill covers cross-platform strategy. For platform-specific execution, check out these dedicated skills:

- **google-ads-ecommerce** — Google Shopping, Search, and Performance Max campaign setup (coming soon)
- **meta-ads-ecommerce** — Facebook and Instagram ad campaign setup (coming soon)
- **tiktok-ads-ecommerce** — TikTok ad campaign setup (coming soon)

More e-commerce skills: [nexscope-ai/eCommerce-Skills](https://github.com/nexscope-ai/eCommerce-Skills)

### Selling on Amazon?

**[amazon-ppc-campaign](https://github.com/nexscope-ai/Amazon-Skills/tree/main/amazon-ppc-campaign)** — Build and optimize Amazon Sponsored Products / Brands / Display campaigns. Calculates ACoS targets, groups keywords by campaign type, sets bid strategies based on Amazon's suggested ranges. Output follows Seller Central hierarchy — ready to implement.

```bash
npx skills add nexscope-ai/Amazon-Skills --skill amazon-ppc-campaign -g
```

See all Amazon seller skills: [nexscope-ai/Amazon-Skills](https://github.com/nexscope-ai/Amazon-Skills)

## Limitations

This skill provides strategic planning and creative direction based on industry benchmarks and product analysis. It cannot access live ad platform data, create actual images/videos, set up tracking pixels, or manage ad accounts directly. For deeper optimization with live data, check out **[Nexscope](https://www.nexscope.ai/)** — Your AI Assistant for smarter E-commerce decisions.

---

**Built by [Nexscope](https://www.nexscope.ai/)** — research, validate, and act on e-commerce opportunities with AI.

ClawHub Marketing Finance+2

Ecommerce Marketing Strategy Builder

Skill

Full-stack e-commerce marketing strategy builder. Analyzes your product, market, and competitors, then builds a complete omnichannel marketing plan covering...

---
name: ecommerce-marketing-strategy-builder
description: "Full-stack e-commerce marketing strategy builder. Analyzes your product, market, and competitors, then builds a complete omnichannel marketing plan covering paid ads, SEO, email/SMS, content marketing, social media, influencer partnerships, and referral programs. Includes target audience persona, competitive landscape, channel prioritization with budget allocation, content direction, and a 90-day action plan. Works for any e-commerce platform — Shopify, Amazon, Etsy, WooCommerce, TikTok Shop, and more. No API key required."
metadata:
  nexscope:
    emoji: 🎯
    category: ecommerce
---

# E-Commerce Marketing Strategy Builder 🎯

Build a complete omnichannel marketing strategy for your e-commerce business. Covers all major channels — paid ads, SEO, email, content, social media, influencers, and referral programs — with budget allocation, audience targeting, and a 90-day action plan.

## Installation

```bash
npx skills add nexscope-ai/eCommerce-Skills --skill ecommerce-marketing-strategy-builder -g
```

## Capabilities

- **Target audience persona**: Demographics, interests, pain points, buying motivations, and where they spend time online — built from product analysis and competitor research
- **Competitive landscape**: How competitors position, price, and market — and where the gaps are
- **Channel prioritization**: Which marketing channels to use and in what order, ranked by expected ROI for your specific product and stage
- **Budget allocation**: How to split your marketing budget across channels, with benchmarks
- **Email & SMS strategy**: Flows, sequences, and campaign types — the highest-ROI channel most sellers ignore
- **SEO & content plan**: Keyword themes, content types, and publishing cadence
- **Paid ads brief**: High-level ad strategy per platform (for detailed campaign setup, use [ecommerce-ppc-strategy-planner](https://github.com/nexscope-ai/eCommerce-Skills/tree/main/ecommerce-ppc-strategy-planner))
- **Social media plan**: Platform selection, content pillars, posting frequency
- **Influencer & affiliate direction**: Who to partner with, what to offer, how to structure deals
- **Referral & loyalty program**: How to turn existing customers into growth engines
- **Pricing positioning**: Where to price relative to competitors based on market analysis
- **90-day action plan**: Week-by-week roadmap with priorities and milestones

## Usage Examples

```
I'm launching a Shopify store selling premium dog treats, $24.99 per bag. Margin is 65%. 
Budget: $3,000/month for marketing. Target: US dog owners. Help me build a marketing strategy.
```

```
I sell handmade jewelry on Etsy and my own website. Price range $40-120. I have 2,000 
Instagram followers and 800 email subscribers. Monthly marketing budget is $1,500. 
I want to grow beyond Etsy. What's my strategy?
```

```
We're a new DTC skincare brand on Shopify. AOV $55, margin 70%. We have $10,000/month 
marketing budget and want to hit $100K revenue in 6 months. Build our marketing plan.
```

---

## How This Skill Collects Information

**Step 1: Extract from the prompt.** Parse product type, price, margin, budget, current channels, goals, stage, competitors mentioned.

**Step 2: Identify gaps.** Compare against what's needed:

Critical info:
| Info | Why It's Needed |
|------|----------------|
| Product type and price/AOV | Determines which channels and audiences fit |
| Profit margin | Calculates how much you can spend to acquire a customer |
| Monthly marketing budget | Allocates across channels |
| Business stage | New launch vs growing vs established — changes priority order |
| Marketing goal | Brand awareness vs direct sales vs both — changes channel mix |
| Sales channels | Shopify only? Amazon + Shopify? Etsy? Affects strategy |
| Existing assets | Email list, social following, content, reviews — what you already have to work with |

**Step 3: One follow-up.** Consolidate ALL missing questions into a single message. Use multiple-choice format to make it easy to answer quickly:

```
Example:
"Premium dog treats at $24.99, 65% margin, $3,000/month budget — great start! 
A few quick questions so I can build your strategy (just reply with the letters):

  1. Business stage?
     a) Pre-launch — haven't sold yet
     b) Early — selling, but under $10K/mo
     c) Growing — $10K-50K/mo
     d) Scaling — $50K+/mo

  2. Main goal?
     a) Brand awareness — get known
     b) Direct sales — revenue now
     c) Both
     d) Other: ___________

  3. Where do you sell?
     a) Shopify / own website only
     b) Amazon
     c) Etsy
     d) Multiple platforms (which ones?)

  4. Your target customer buys because of:
     a) Price / value
     b) Quality / premium
     c) Unique / can't find elsewhere
     d) Convenience
     e) Other: ___________

  5. What do you already have? (check all that apply)
     a) Email list — how many subscribers?
     b) Social media following — which platform, how many?
     c) Existing content (blog, videos, etc.)
     d) Customer reviews
     e) Nothing yet — starting from zero
     f) Other: ___________

  6. Any competitors you want me to analyze? (names or URLs, or skip)"
```

**Key rules:**
- **Never split into multiple follow-up rounds.** One message, all questions.
- **Use a/b/c/d choices** wherever possible — faster than open-ended questions.
- **Mix in 1-2 open-ended** only where choice format doesn't work (competitors, specific numbers).
- **If user gives short answers** like "1b 2c 3a 5e", that's enough — proceed with the strategy.

**Step 4: Use estimates when stuck.** Don't block on missing data — use category benchmarks, but:
- **Mark every estimate clearly** with ⚠️
- **Explain what better data would change**
- **List what to provide next time** at the end of the report

---

## Key Benchmarks (2025-2026)

### Channel ROI

| Channel | Average ROI | Best For | Source |
|---------|:----------:|----------|--------|
| Email marketing | $36-40 per $1 | Retention, repeat purchases, cart recovery | Omnisend 2026 Report |
| SMS marketing | $21-71 per $1 | Time-sensitive offers, cart abandonment | Omnisend 2026 Report |
| SEO / organic search | $7.48 per $1 | Long-term sustainable traffic | FirstPageSage |
| Google Ads (search) | $8 per $1 | High-intent buyers | Google Economic Impact Report |
| Paid social (Meta/TikTok) | $2.5 per $1 | Awareness + prospecting | FirstPageSage ROAS Statistics |
| Influencer marketing | Varies | Brand credibility, new audiences | — |
| Affiliate marketing | Performance-based | Low-risk expansion (pay per sale) | — |

### Marketing Budget Benchmarks

| Business Stage | Marketing as % of Revenue | Notes | Source |
|---------------|:------------------------:|-------|--------|
| New / pre-launch | 15-20% | Invest heavily to build awareness | Hostinger, WebFX |
| Early stage (<$500K/yr) | 10-15% | Build foundational channels | Hostinger |
| Growing ($500K-$5M/yr) | 7-12% | Optimize and scale what works | Gartner 2025 CMO Survey (avg 7.7%) |
| Established ($5M+/yr) | 5-8% | Efficiency + retention focus | Gartner |

### Budget Allocation Framework

| Channel | % of Budget | Priority |
|---------|:----------:|:--------:|
| Paid ads (Google, Meta, TikTok) | 25-35% | P1 — Immediate traffic |
| Content + SEO | 20-25% | P2 — Long-term compound growth |
| Email + SMS | 15-20% | P1 — Highest ROI, retention |
| Social media (organic) | 10-15% | P3 — Brand building |
| Influencer / affiliate | 10-15% | P2 — Credibility + reach |
| Testing / new channels | 5-10% | P3 — Discover next winner |

Recommended overall split: **60% owned/organic (SEO, email, content) + 40% paid channels (PPC, social ads, influencers)**

### Customer Retention Stats

- Repeat customers = 21% of customer base but drive 44% of revenue *(Omnisend)*
- After 1st purchase: 27% chance of buying again → 2nd: 49% → 3rd: 62% *(Smile.io)*
- Using 3+ marketing channels: 287% higher purchase rate *(Omnisend)*

---

## Workflow

### Step 1: Understand the Business

Collect and organize:
- Product, price, margin, business stage
- Marketing goal, budget, sales channels
- Existing assets (email list, social, content, reviews)
- Competitive landscape (who are the main competitors?)

### Step 2: Build Target Audience Persona

**Using info collected from the follow-up questions (stage, goal, buying motivation, existing assets), plus your own research:**

1. **If user provided customer data** → build persona from real data
2. **If user is pre-launch / no data** → infer from:
   - Product category → typical buyer profile (e.g., premium dog treats → dog owners 28-55, health-conscious pet parents)
   - Price point → income bracket (budget vs premium vs luxury)
   - Platform → audience skew (Etsy skews female 25-45, TikTok Shop skews 18-34)
3. **Research competitor audiences** — search for top brands in the category, check who follows them, what their reviews say
4. **Mark estimates** with ⚠️ when inferring instead of using real data

**Output the persona in this format:**

```
🎯 TARGET AUDIENCE PERSONA

Demographics:
  Age: [range]
  Gender: [split %]
  Location: [markets]
  Income: [range]
  Source: [user data / inferred from product type ⚠️ / competitor analysis]
  
Psychographics:
  Interests: [relevant interests]
  Values: [what they care about]
  Pain points: [problems your product solves]
  Buying motivation: [why they buy — convenience, quality, status, price]
  
Online behavior:
  Where they discover products: [Instagram, Google, TikTok, Amazon, etc.]
  Where they research: [reviews, YouTube, Reddit, blogs]
  What influences purchase: [price, reviews, brand, influencer recommendation]
  
Language they use:
  [Real phrases from reviews / social media — how they describe the problem 
  and solution in their own words. Use these in ad copy and content.]
  Source: [extracted from competitor reviews / user-provided / estimated ⚠️]
```

### Step 3: Competitive Landscape

**Using competitors from the follow-up (Q6), or find them yourself:**

- **If user provided competitors** → research those directly
- **If not** → search "[product category] best brands", check platform best sellers, look at who's running ads for the same keywords

**For each competitor, analyze:**
- **Pricing** — price range, budget/mid/premium positioning
- **Positioning** — tagline, USP, how they describe themselves
- **Strengths / Weaknesses** — from reviews (what people praise vs complain about)
- **Marketing channels** — where are they advertising? Social? Email? Content?

**Then identify:** market gaps, differentiation opportunities, and pricing recommendation.

**Output format:**

```
📊 COMPETITIVE LANDSCAPE

Market Price Range:  [$low — $high]
Your Position:       [where you sit and why]

Top Competitors:
  [Competitor 1]: 
    Price: $XX | Positioning: [how they position]
    Strengths: [from reviews/research]
    Weaknesses: [from reviews/research]
    Marketing: [channels they use]

  [Competitor 2]:
    [same structure]
  
Market Gaps:         [underserved segments, unmet needs, positioning opportunities]
Your Differentiation: [what makes you different — and how to communicate it]
Pricing Recommendation: [where to price and why]
```

### Step 4: Channel Prioritization

Based on business stage, budget, goals, and audience, rank channels.

**Where these percentages come from:**
- Omnisend 2026 Ecommerce Report: 60% owned/organic + 40% paid as optimal split
- Azarian Growth Agency 2025: 25-30% content/SEO, 20-25% paid search, 15-20% paid social, 10-15% email
- Gartner 2025 CMO Survey: marketing budgets at 7.7% of company revenue
- The stage-specific splits below are synthesized from these sources — adjust based on the user's actual data and goals

**For new launches (brand awareness + first sales):**
| Priority | Channel | Why | Budget % |
|:--------:|---------|-----|:--------:|
| P1 | Paid Ads (Meta/Google) | Immediate traffic when you have zero audience | 30-35% |
| P1 | Email setup (welcome flow, cart abandonment) | Capture and convert visitors from day 1 | 10-15% |
| P2 | Social media (organic) | Build brand, create content library | 10-15% |
| P2 | Influencer seeding | Get product in hands of micro-influencers | 15-20% |
| P3 | SEO / Content | Start building, won't pay off for 3-6 months | 10-15% |
| P3 | Testing | Try one new thing each month | 5-10% |

**For growing businesses (scale what works):**
| Priority | Channel | Why | Budget % |
|:--------:|---------|-----|:--------:|
| P1 | Email + SMS | Highest ROI, monetize existing customers | 15-20% |
| P1 | Paid Ads (scale winners) | Increase spend on proven channels | 25-30% |
| P2 | SEO / Content | Reduce CAC over time | 15-20% |
| P2 | Influencer / Affiliate | Expand reach cost-effectively | 10-15% |
| P3 | Social media | Maintain presence, repurpose content | 10% |
| P3 | Referral / Loyalty program | Turn customers into advocates | 5-10% |

**For established businesses (optimize + retain):**
| Priority | Channel | Why | Budget % |
|:--------:|---------|-----|:--------:|
| P1 | Email + SMS + Loyalty | Retention = highest-margin revenue | 20-25% |
| P1 | SEO / Content | Compound returns, reduce paid dependency | 20-25% |
| P2 | Paid Ads (efficient) | Maintain acquisition at target CAC | 20-25% |
| P2 | Affiliate program | Scale through partners | 10-15% |
| P3 | Social media | Brand + community | 10% |
| P3 | New market / channel | Expand to new platforms or geographies | 5-10% |

### Step 5: Channel-by-Channel Plan

For each prioritized channel, output:

**Email & SMS:**
- Key automated flows: Welcome series, abandoned cart, post-purchase, win-back
- Campaign types: New products, sales, content newsletters
- List building tactics: Pop-up offer, checkout opt-in, social media lead magnets
- Target metrics: Open rate >35%, click rate >3%, revenue per email >$0.10

**SEO & Content:**
- Keyword themes (not full keyword research — that's a separate skill)
- Content types: Blog posts, buying guides, comparison pages, FAQ
- Publishing cadence: X posts per week/month
- Technical SEO priorities if applicable

**Paid Ads:**
- Recommended platforms and why
- Budget split across platforms
- Campaign types (awareness vs conversion)
- Note: "For detailed campaign setup, use ecommerce-ppc-strategy-planner"

**Social Media:**
- Platform selection (based on where target audience is)
- Content pillars (3-4 themes to rotate)
- Posting frequency
- Engagement strategy

**Influencer / Affiliate:**
- Type of influencers (micro vs macro, niche)
- Outreach approach and what to offer
- Commission/payment structure
- How to measure ROI

**Referral / Loyalty:**
- Program structure (points, tiers, referral rewards)
- When to launch (need enough customers first)
- Expected impact

### Step 6: 90-Day Action Plan

Break the strategy into weekly actions:

```
📅 90-DAY ACTION PLAN

MONTH 1: Foundation
  Week 1: [Setup actions — accounts, tools, tracking]
  Week 2: [Launch first channel — usually paid ads + email flows]
  Week 3: [Content + social media kickoff]
  Week 4: [First review — what's working? Adjust]

MONTH 2: Optimize & Expand
  Week 5-6: [Optimize winning channels, cut losers]
  Week 7-8: [Launch second wave — influencer outreach, SEO content]

MONTH 3: Scale
  Week 9-10: [Scale winners with more budget]
  Week 11-12: [Launch referral/loyalty, review full strategy]

KEY MILESTONES:
  Day 30: [target metric]
  Day 60: [target metric]
  Day 90: [target metric]
```

### Step 7: KPIs & Measurement

Define success metrics:

| Metric | Benchmark | Your Target (how to set) | How to Track |
|--------|:---------:|:------------------------:|-------------|
| CAC | Varies | Must be < profit per order (AOV × margin) | Ad platforms + analytics |
| LTV | Varies | Aim for > 3× CAC (if LTV < 3× CAC, acquisition is too expensive) | Shopify/platform analytics |
| Email list growth | 5-10%/month | New stores: aim for 5%/mo. Growing: 8-10%/mo | Email platform |
| Email revenue share | 25-30% of total | Start with 15% target, grow to 25%+ over 6 months | Email platform |
| Organic traffic growth | 10-20%/month | SEO takes 3-6 months to kick in. Set 10%/mo after month 3 | Google Analytics |
| Social engagement rate | 1-3% | Below 1% = content problem. Target 2%+ | Platform analytics |
| Repeat purchase rate | 28% avg | New stores: 15-20%. Growing: 25%+. Established: 30%+ | Platform analytics |
| Blended ROAS | 2.5x+ | Calculate: 1 ÷ margin × 1.5 = your minimum target ROAS | All platforms combined |

---

## Output Format

```
# ✅ E-Commerce Marketing Strategy — Ready to Execute

## Business Snapshot
Product: [name] | Price: $XX | Margin: XX%
Stage: [new/growing/established] | Budget: $X,XXX/mo
Goal: [awareness / sales / both]
Channels: [where you sell]

## Target Audience Persona
[Full persona from Step A2]

## Competitive Landscape
[Analysis from Step A3]

## Channel Strategy (Prioritized)
[Full channel plan from Step A4-A5 with budget allocation]

## 90-Day Action Plan
[Weekly roadmap from Step A6]

## KPIs & Measurement
[Metrics table from Step A7]
```

---

## Other Skills

This skill builds the strategy. For execution on specific channels:

- **[ecommerce-ppc-strategy-planner](https://github.com/nexscope-ai/eCommerce-Skills/tree/main/ecommerce-ppc-strategy-planner)** — Detailed paid ads strategy for Google, Meta, and TikTok with ad copy + creative prompts

```bash
npx skills add nexscope-ai/eCommerce-Skills --skill ecommerce-ppc-strategy-planner -g
```

Selling on Amazon? See [nexscope-ai/Amazon-Skills](https://github.com/nexscope-ai/Amazon-Skills) for keyword research, listing optimization, and Amazon PPC.

More e-commerce skills: [nexscope-ai/eCommerce-Skills](https://github.com/nexscope-ai/eCommerce-Skills)

## Limitations

This skill provides strategic planning based on industry benchmarks, product analysis, and competitive research. It cannot access your actual analytics data, run A/B tests, create content, set up email flows, or manage ad accounts. For AI-powered marketing execution with live data, check out **[Nexscope](https://www.nexscope.ai/)** — your AI assistant for smarter e-commerce decisions.

---

**Built by [Nexscope](https://www.nexscope.ai/)** — research, validate, and act on e-commerce opportunities with AI.

ClawHub Research Marketing+2