# Marketplace Ads — Compute Core (cross-MP)

Кросс-маркетплейсный compute-движок для биддера. Pure pandas — без сети, без знания о конкретном маркетплейсе. Один вход — DataFrame, один выход — DataFrame или `list[dict]` с детерминированным результатом.

Скилл предназначен для горячего пути биддера (тик каждые 15 минут): нужен **детерминизм**, а не LLM-арифметика. Все скрипты импортируются в sandbox и не делают сетевых вызовов.

## Когда что использовать

| Скрипт | Назначение | Вход | Выход |
| --- | --- | --- | --- |
| `compute_sku_pnl.py :: compute_sku_pnl(df)` | Истинный ДРР с маржой по каждому SKU | DataFrame: `sku, revenue, cogs, commission, logistics, returns, ad_spend` (всё в копейках) | DataFrame + `pnl_kopeks, true_drr, margin_pct` |
| `find_loss_makers.py :: find_loss_makers(pnl_df, target_drr)` | Поиск SKU, которые жгут бюджет или работают в минус | `pnl_df` (выход `compute_sku_pnl`), `target_drr` (%) | `list[{sku, reason, severity}]` |
| `apply_pause_rules.py :: apply_pause_rules(df)` | Детерминированные правила «pause / keep / exploration» | DataFrame: `sku, margin_pct, oos_days, returns_7d_pct, exploration_until` | `list[{sku, action, reason}]` |
| `propose_lineup.py :: propose_lineup(scored_df, total_budget, target_drr)` | Распределение бюджета по ABC + target-ставки | `scored_df`: `sku, abc_class, price, cogs, commission_pct, logistics` (+ опц.) | `list[{sku, allocated_budget, target_bid, strategy}]` |
| `compute_target_bid.py :: compute_target_bid(sku_metrics, target_drr, current_bid)` | Pricing-loop: следующая ставка для одного SKU | `dict`: `price, cr` (+ опц. `exploration_until`) | `int` — новая ставка в копейках |

## Контракты входа

- Все денежные значения — **в копейках** (int или float). Если на руках рубли — умножь на 100.
- ABC-класс — строка `'A' | 'B' | 'C'` (case-insensitive). Если SKU не классифицирован, передай `'C'`.
- `exploration_until` — `pd.Timestamp` (UTC-aware) или `pd.NaT`. SKU считается cold-start, пока значение в будущем.
- `target_drr` — процент (`12.0`, не `0.12`).
- `cr` (conversion rate) — доля `0..1` (например, `0.04` = 4%).

## Контракты выхода

- `compute_sku_pnl`: копия входа + три числовые колонки (`pnl_kopeks` в копейках, `true_drr` и `margin_pct` округлены до 2 знаков).
- `find_loss_makers`: один SKU может встречаться несколько раз — по одному элементу на каждое сработавшее правило (`negative_margin`, `drr_overshoot`, `ad_spend_above_margin`); `severity` ∈ `{high, medium}`.
- `apply_pause_rules`: ровно один результат на SKU; первое сработавшее правило побеждает (`exploration` → `negative_margin` → `oos_lt_7d` → `returns_above_15pct` → `ok`).
- `propose_lineup`: ровно один результат на SKU; `strategy` ∈ `{push, hold, pause, exploration}`. Для `pause` бюджет и ставка = 0.
- `compute_target_bid`: возвращает `int`. Cold-start → `EXPLORATION_BID_KOPEKS = 5000` (50 ₽). Без CR-сигнала → не трогаем `current_bid` (с минимальным флором). Иначе клампим в ±50% от `current_bid` (страховка от качелей при коротких тиках).

## Связки с другими скиллами

- Методология ABC-классификации, расчёт чистой маржи, маппинг типов списаний → `read_skill("unit_economics_ru")`.
- Когда применять авто vs ручную стратегию ставок, как связывать рекламу с жизненным циклом товара, чек-лист готовности карточки до запуска кампании → `read_skill("marketplace_ads_strategy_ru")`.
- Применение решений на конкретный маркетплейс (write-сторона) → `read_skill("ozon_guide_ru")` / `read_skill("wildberries_guide_ru")` / `read_skill("yandex_market_guide_ru")`.

## Что этот скилл НЕ делает

- Не ходит в сеть. Не вызывает Ozon/WB/ЯМ API. Если нужно прочитать данные — это работа гайд-навыка маркетплейса.
- Не пишет в БД. Только compute.
- Не решает «авто или ручная кампания». Это методологический выбор → `marketplace_ads_strategy_ru`.
- Не считает COGS / комиссии / логистику с нуля — ожидает их уже в DataFrame. Маппинг типов списаний — задача `unit_economics_ru`.