AI-Pricing-Agent/README.md

Pricing & Profitability Analyst — AI Agent (Pilot)

The first buildable agent from the Amazon 1000+ product launch team. It automates the Pricing Analyst's gate: for each SKU it builds the full fee stack, computes contribution margin / break-even / MAP, checks competitive price + Buy Box / suppression, then proposes a price and an APPROVED / BLOCKED / NEEDS_REVIEW decision. A human approves before anything is written back to the master tracker.

Built on LangGraph (stateful, gated, auditable) + OpenAI (narrative only — never arithmetic). All money math lives in a pure, unit-tested module.

Architecture

enrich ─▶ compute_margin ─▶ fetch_competitive ─▶ evaluate ─▶ human_review (interrupt) ─▶ write_back
   │ provider │  │ margin_engine │  │ provider │  │ gate │        │ HITL │            │ tracker │

• providers.py — market-data seam: cosmos (live) ↔ mock (offline). Nodes are backend-agnostic.
• cosmos/ — real COSMOS integration: client.py (auth + token refresh + retries), service.py (products, take-home fee quote, invp sales-trend + inventory, bulk calculator, price read, guarded price-write stub), models.py (typed responses).
• analyze.py — the price verdict: combines per-unit margin (takehome-calculator), the 6-month sales trend (invp-insight: averageSale6Months vs 7/30-day), and total economics (bulk-calculator: volume − storage on current inventory) → GOOD / CAUTION / POOR.
• tools/margin_engine.py — pure formulas. stack_from_quote() builds the fee stack from COSMOS's real dollar fees; worst_case_stack() is the synthetic mock path. Golden values (mock): break-even $16.76, MAP $19.00, CM ~28%.
• tools/gate.py — deterministic APPROVED/BLOCKED/NEEDS_REVIEW (playbook §13).
• tools/tracker.py — SKU list in / decisions out: csv ↔ gsheets.
• llm.py — OpenAI structured output; falls back to a template if no key.
• graph.py — LangGraph wiring + interrupt() for human approval.

Competitive price / Buy Box / suppression comes from Apify (junglee/Amazon-crawler) when APIFY_TOKEN is set: SKU → COSMOS ASIN → scrape amazon.com/dp/{ASIN}. Without the token the competitive gate stays UNKNOWN (COSMOS has no Buy Box data).

For a covered product line the comparison workbook takes precedence over the per-ASIN scrape — see Coverage in ARCHITECTURE.md, which also documents which of the two scrapers is authoritative for Buy Box state and why.

Setup

pip install -e ".[dev]"
cp .env.example .env      # then fill COSMOS_EMAIL / COSMOS_PASSWORD
# Optional Buy Box: set APIFY_TOKEN (and APIFY_SELLER_ID for WON vs LOST_PRICE)

.env (git-ignored) holds secrets. Defaults: DATA_BACKEND=cosmos, TRACKER_BACKEND=csv. Set DATA_BACKEND=mock to run fully offline (tests + local dev, no credentials).

Dashboard UI

pip install -r requirements.txt   # streamlit + plotly + pandas + numpy
streamlit run app.py

One-page pricing dashboard in the Utopia/CRAI design system (cream paper, teal primary, coral accent, navy chrome): stat tiles, action pills (↑ Raise / ↓ Lower / → Hold / 🔍 Check), and a recommendation queue where each SKU expands into Approve / Modify / Reject plus seven analysis tabs — price & demand, inventory outlook, scenarios, competitors, PPC, costs, and AI reasoning.

Two ways to analyze (sidebar):

• Single product — enter one SKU for a full price analysis.
• Product line — enter a SKU prefix and a product-count slider to analyze a whole line at once.

Live COSMOS data only: every number comes from the real pipeline (take-home fees, 6-month history, elasticity, actual profit, optional competitor Buy Box prices).

The previous analyst UI is still available: streamlit run legacy_app.py.

Run (CLI)

# ANALYZE a price — full breakdown + 6-month trend + AI narrative + suggested price:
python -m pricing_agent.cli --sku <REAL_SKU> --price 24.99 --analyze

# BULK — scan a product line, ranked worst-first with suggested prices:
python -m pricing_agent.cli --bulk --sku-prefix UBMICRO --limit 15

# Live COSMOS, one real SKU at a candidate price (interactive approval):
python -m pricing_agent.cli --sku <REAL_SKU> --price 24.99

# Non-interactive (approve healthy, reject the rest):
python -m pricing_agent.cli --sku <REAL_SKU> --price 24.99 --auto smart

# Offline demo on the sample tracker:
python -m pricing_agent.cli --all --backend mock --auto smart

# Live COSMOS read-only health check:
python scripts/cosmos_smoke.py <REAL_SKU> 24.99

Outputs: data/sample_skus_out.csv (pricing columns + status) and data/audit_log.csv.

Test

pytest      # margin engine, gate, COSMOS mapping, end-to-end graph (all offline)

Going live

Switch	What you need
DATA_BACKEND=cosmos	COSMOS_EMAIL / COSMOS_PASSWORD in .env (already wired)
Price write-back to COSMOS	Confirm the price_adjustment.edit_price POST/PUT endpoint, then fill CosmosPricingService.submit_price_approval()
TRACKER_BACKEND=gsheets	Google service-account JSON + TRACKER_SHEET_ID
Live LLM rationale	OPENAI_API_KEY in .env
Buy Box / competitor gate	APIFY_TOKEN in .env (scrapes ASIN PDP via junglee/Amazon-crawler)
Confirm Buy Box owner	Set APIFY_SELLER_ID to your Amazon merchant id

Every configurable value lives in .env.example (credentials, tokens, paths) or config/pricing_rules.yaml (thresholds and policy). The COSMOS endpoints themselves are catalogued in COSMOS_API.postman_collection.json.