47 lines
3.4 KiB
Markdown
47 lines
3.4 KiB
Markdown
# 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 pytest src/tests -q # тесты
|
||
```
|
||
|
||
## Структура
|
||
- `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».
|