Compare top suppliers year on year

# Instructions — Top suppliers with YoY comparison

## ⚠️ Suppliers returned without a name

`spendesk_analyze_spend` groupBy=supplier returns `key` = **supplier name** (when resolved) and `id` = supplier ID. `key` holds the raw ID only when `summary.limitations` reports `unresolved-names`.
The `name` field is not present in the response.

To display names:
1. Collect all IDs from the top-N suppliers
2. Call `get_suppliers(ids=[id1, id2, ...])` in a single call
3. Join names by ID

## ⚠️ amountChange on the "Others" row

The "Others" row also includes `previousAmount` and `amountChange`. If "Others" grows sharply, the supplier base is expanding faster than the top suppliers.

## Step 1 — Top suppliers analysis with comparison

```json
{
  "companyId": "...",
  "fromDate": "YYYY-MM-DD",
  "toDate": "YYYY-MM-DD",
  "groupBy": ["supplier"],
  "compareWithPreviousPeriod": true,
  "limit": 15
}
```

→ The previous period is automatically calculated (same duration, immediately before `fromDate`).
→ `limit: 15` to see more than the default top-10.

## Step 2 — Interpreting compareWithPreviousPeriod

Each row returns:
- `amount`: spend for the current period
- `share`: relative weight of the row within its breakdown (% of gross activity at that level, always between 0 and 100; not a share of `summary.totalAmount`)
- `previousAmount`: spend for the previous period
- `amountChange`: % change (positive = increase, negative = decrease)
  - `amountChange: null` → previousAmount = 0 (no defined percentage; quote the absolute amounts. null does not prove the supplier is new: the previous period may have netted to zero)
  - `amountChange: -100` → supplier no longer active (amount = 0)

On the summary (`summary.previousPeriod`):
- `period.from/to`: dates of the comparison period
- `totalAmount`: total for the previous period
- `amountChange`: overall % change

## Step 3 — Resolving supplier names

```json
{ "companyId": "...", "ids": ["id1", "id2", "id3", ...] }
```

Join by ID (only if names are not resolved): `{ ...row, name: suppliers.find(s => s.id === row.id)?.name || row.key }`

## Step 4 — Identifying anomalies

Alert the user about:
- `amountChange > 500%` → explosive growth (new contract, data entry error?)
- `amountChange < -50%` → sharp decline (termination, project ended?)
- `previousAmount = 0` AND `amount > threshold` → significant new supplier
- "Others" rising sharply → fragmentation of the supplier base

## Live example (real data, Jul 2025 → Jun 2026 vs Jul 2024 → Jun 2025)

Summary:
- Current period: **EUR 16,524,574.27** (7,199 payables)
- Previous period: EUR 17,108,631.54 (5,804 payables)
- **Overall change: -3.4%** (slight decrease)

Notable anomalies:
- Supplier `0qryRtMyYW`: +92,078% (EUR 424 → EUR 391,345) — practically new
- Supplier `lt1euqhnunby1f`: +361.5% (EUR 131,938 → EUR 608,940) — strong growth
- Supplier `9MCGQweUWi`: -68.3% (EUR 3,001,938 → EUR 951,166) — sharp decline
- Supplier `8xs-s358mod4ps`: new (previousAmount=0), EUR 738,607
- "Others": +53.2% (expanding supplier base)

## Example prompt

- "Who are our top 10 suppliers this year vs last year?" → groupBy=supplier, compareWithPreviousPeriod=true, limit=10 + resolve names
- "Are there any suppliers whose spend has exploded?" → filter amountChange > 200%
- "Significant new suppliers this year?" → filter previousAmount=0 AND amount > threshold