120 lines
5.7 KiB
Markdown
120 lines
5.7 KiB
Markdown
# Pricing & Profitability Analyst — AI Agent (Pilot)
|
||
|
||
The first buildable agent from the [Amazon 1000+ product launch team](../agents_plans/).
|
||
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](ARCHITECTURE.md), which also documents which of
|
||
the two scrapers is authoritative for Buy Box state and why.
|
||
|
||
## Setup
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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)
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
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](.env.example) (credentials, tokens, paths)
|
||
or [config/pricing_rules.yaml](config/pricing_rules.yaml) (thresholds and policy). The COSMOS
|
||
endpoints themselves are catalogued in `COSMOS_API.postman_collection.json`.
|