# chto-ty-takoe-na-baze-kakih — AgroMarket Price Agent

MVP ИИ-агента, который ежедневно собирает открытые агро-цены (KZ/TJ/UZ/RU),
нормализует и категоризирует их, строит аналитику и отдаёт дашборд + дайджест.

## Стек
- Python 3.12, SQLite (переносимо на PostgreSQL), APScheduler, FastAPI + Plotly
- ИИ (LLM) — только **выписывает число из фрагмента источника**, сверка посимвольно
- Каждая цена — со ссылкой на источник и датой сбора

## Запуск
```bash
python3 -m pip install -r requirements.txt
export $(grep -v '^#' .env | xargs)   # секреты в .env
python3 -m src.dashboard.run           # дашборд на $PORT (дефолт 8000)
python3 -m src.scheduler --once        # один прогон пайплайна + дайджест
python3 -m src.scheduler --daemon      # демон (ежедневно 07:30)
python3 -m src.demo_data               # синтетические данные (60 дней)
python3 -m src.export_excel            # отчёт в data/agromarket_report.xlsx
python3 -m pytest src/tests -q         # тесты
```

Дополнительно:
- На странице **Источники** — форма ручной загрузки CSV/HTML (Arbuz.kz, Sharyn и аналоги без API).
  Запись идёт через тот же пайплайн; низкая уверенность → очередь на проверку.
- На странице **Страны** — кнопка «Скачать в Excel» (SheetJS, выгрузка раскладок прямо из браузера).
- CLI-отчёт `python3 -m src.export_excel` кладёт `.xlsx` (динамика по товарам + раскладки + алерты)
  в `data/` — скачивается из вкладки **Файлы**.

## Структура
- `src/pipeline/` — fetch, extract, normalize, categorize, validate, llm_extract, raw, orchestrator
- `src/analytics/` — dynamics, spreads/arbitrage, seasonality, anomalies, alerts, forecast
- `src/dashboard/` — FastAPI: overview, products, product, countries, alerts, quality, sources
- `src/` — db.py (SQL), config.py, taxonomy.py, models.py, cache.py, scheduler.py, digest.py, demo_data.py
- `config/` — taxonomy.yaml, synonyms.yaml, sources.yaml

## Принципы (железо)
1. **Искренность**: LLM не выдумывает цены — только цитирует число из фрагмента,
   затем строковая сверка. Не прошло — запись отбрасывается (не в карантин).
2. **Корректность**: «нет данных» ≠ «цена 0». Подозрительные значения — в карантин,
   не в аналитику. Ниже порога (floor по категории) → quarantine.
3. **Легальность**: tier-3 / новые источники — `legal_status: pending_review`
   (выключены по умолчанию). Никакого обходa captcha/роботов; честный User-Agent,
   robots.txt, rate-limit, кеш.
4. **Идентичность**: повторный запуск не дублирует записи (ключ по
   source+region+product+price_type+as_of+фрагмент+snapshot).

## Ограничения MVP
- КЗ-официальные источники (stat.gov.kz/uz/tj) недоступны из run-контейнера
  (DNS) — только заглушки-адаптеры; нужен прогон из сети с доступом.
- Arbuz.kz / Sharyn — нет публичного API → `pending_review` + ручной CSV-дамп.
- Прогнозы — базовые (seasonal naive, SARIMA) с честным доверительным интервалом
  и меткой «низкая уверенность».
- Модель арбитража (груз/тариф/комиссия) — предположения, помечены в UI как «assumptions».