Price history analyzer: lows, drops, sale patterns and a buy-or-wait note

What it does

Answers "is this price actually good?" from a CSV the user already has: a hand-kept log or a price tracker export. The bundled Python script does every calculation; the agent only explains the result, so no prices are invented.

• Per item: lowest, highest, median, mean and current price (vs lowest, vs median, share of days that were cheaper)
• With several shops: daily minimum across shops and the latest price at each shop
• Day-to-day price drops (threshold configurable, default 5%) and merged sale episodes
• Weekday and month tables, plus whether the yearly low fell in the same month in two or more years
• A buy-now / consider-waiting / neutral signal with the reasons, assumptions and warnings (few observations, gaps, stale latest price)

How to use

python scripts/price_history.py prices.csv --json report.json --md report.md
python scripts/price_history.py prices.csv --item "Coffee Mill" --drop-pct 10

Columns: date, item, price, shop (in_stock optional). Formats like 1,980, JPY 1,980, $19.99 and 2026/3/1 are accepted. A sample is in examples/prices.csv.

Requirements

• Python 3 (standard library only)
• An agent such as Claude, Codex, Hermes Agent or Cursor

Caveats

• It describes past prices; it does not predict future ones.
• Shipping, points and coupons are ignored unless already in the price column.
• Gaps between observations can hide sales.
• No network access: it only reads the local CSV.