# Channel Insights → "Analyse all" in bulk (`leads:analyse-all`)

## What it does

The **Analyse all** button reads one lead at a time, from an open browser tab. `leads:analyse-all`
does the same work for many leads from the command line, and spends nothing until you say so:

```bash
php artisan leads:analyse-all                         # asks: which grades, how many, then "Start now?"
php artisan leads:analyse-all --run --limit=3         # try three leads, no questions
php artisan leads:analyse-all --run --workers=4       # the rest, four leads at a time
```

**Every choice is optional.** At a terminal, the command asks for whatever the options leave out:
1. **Which signal grades?** It lists how many of each grade are left to analyse, out of how many.
2. **How many leads?** Enter means all.
3. After the plan and its cost estimate: **Start now?** The default is No.

An option you give is never asked. Away from a terminal (`nohup`, `-n`) nothing is asked and the
defaults stand (grade A, all leads, plan only), so an unattended run without `--run` spends nothing.

It was first used 2026-10-12 for the A grade of the [signal grade](/docs/modules_handbook/manage/leads/signal-grade.md).
The boss chose GLM-5.3 Flash, which is the routed model the channel readings already use (OpenRouter).

| Option | Meaning |
|---|---|
| `--grade=a` | Signal grade keys to run, comma-separated (`s,a,b,c`). Default `a` |
| `--lead=<uuid>` | Only these leads (repeatable), instead of `--grade` |
| `--limit=N` | At most N leads (0 = all) |
| `--workers=N` | Leads analysed at the same time, each in its own process |
| `--max-usd=25` | Start no new lead once this run has spent this much |
| `--force` | Also run leads that already have a Summary reading |
| `--run` | Call the AI. Without it, only the plan is printed |

## How it works

- **The button's own code.** For each lead it calls every channel controller's `generate()` in the
  button's order (8 channels, then Overall, then Summary), mapped the way `useAnalyseAll.js` maps
  the responses (`200` done or reused, `404`/`422` skipped). Fingerprint reuse, stale rules,
  `saveForLead`, the proposals and the readiness cache are therefore exactly the button's.
- **What it leaves out:** the Profile enrichment. That step is a queued job (`EnrichLeadJob`) and
  spends on web search and Places. The run needs **no queue worker**, and nothing is sent to anyone.
- **Who is run.** A lead that already has a **Summary** reading counts as analysed and is skipped
  (`--force` runs it again). A run that stops part-way leaves no Summary, so the next run picks the
  lead up again. Every reading that did land is then reused for free on its fingerprint.
  - Overall and Summary run only when every channel settled. A failed channel ends that lead as
    `INCOMPLETE`.
  - Leads are taken best grade first, then by id.
- **What it runs on.** The plan prints each step's model (`ServesChannelInsights::readingRoute()`).
  - With `--run`, it **refuses to start** unless every step `AnalysisPipeline::STEPS` marks
    `routed` really is on the routed model.
  - A missing OpenRouter key, or a gateway-client site, would otherwise drop those nine readings,
    silently, onto the plain pinned model.
  - Summary is not routed: it reads on its pin, else the `channel_insights` provider in config.
- **Budget.** Before each lead it totals this run's spend on the analysis prompts in `ai_requests`
  (`AiRequest::spendColumn()`). That total covers every worker, so `--max-usd` caps the whole run.
- **Estimate.** The plan prints the average cost of one analysed lead on this site over the last
  `AnalysisPipeline::STATS_DAYS` days, times the leads to run. It warns when that is above
  `--max-usd`. With no history, it says to try 3 first.
- **Every request is an ordinary AI request.** Each reading calls `AiClient`, so each call is a row
  on Integrations → AI (`/manage/integrations/ai`) with its tokens, cost, duration and lead,
  created by the super admin the run acts as. Nothing is hidden from that page.
- **Workers.** `--workers=N` starts N child processes (`Process::pool`). The leads are dealt to
  them round-robin, and their output is streamed with a `[wN]` prefix. The children run with the
  internal `--worker` flag.
- The run acts as the first super admin, which is whose name the proposals carry.
- **Progress.** Each step prints one line as it settles (`lead 2701 · WhatsApp: done (4m39s)`);
  steps with no records are not printed. Each lead ends with `[3/45] lead 2701 complete · 16m03s ·
  US$0.076`; the `[3/45]` counts that worker's own leads. The whole run's line,
  `── Progress: 12/267 leads done (4%) · US$1.21 spent · 1h05m elapsed · about 9h40m left`, is
  printed after every lead on one worker, and every `PROGRESS_EVERY_SECONDS` (5 minutes) by the parent
  of `--workers`. The parent counts the workers' own per-lead lines, so a lead whose readings
  were all reused still counts.

## Running it on production

- It runs for hours: about 15 minutes per lead per worker, because a worker reads one step at a
  time and GLM-5.3 Flash thinks for 2 to 7 minutes per reading. Start it so an SSH drop does not
  kill it, and keep the log:

  ```bash
  nohup php -d memory_limit=1G artisan leads:analyse-all --run --grade=a --workers=6 --max-usd=40 > storage/logs/analyse-all.log 2>&1 &
  tail -f storage/logs/analyse-all.log
  ```

- Stop it with `pkill -f leads:analyse-all`. Re-running it continues where it stopped.
- OpenRouter's concurrency has not been measured for this account. Start with 4 to 6 workers.
- **Measured 2026-10-12** (local trial, lead with WhatsApp + webinars + sales):
  - US$0.076 in 16 minutes;
  - the Summary on Gemini was 41% of it (US$0.032), and each GLM reading cost US$0.007 to 0.019;
  - output tokens (mostly thinking) ran 2 to 4 times the input. Thinking is billed as output.
  - A second lead with five channels cost US$0.124 in 26 minutes. That gives US$0.10 per A-grade
    lead on average, so about US$27 for the 267 left.

## Related files

- [app/Console/Commands/AnalyseAllLeads.php](/app/Console/Commands/AnalyseAllLeads.php)
- [app/Http/Controllers/Concerns/ServesChannelInsights.php](/app/Http/Controllers/Concerns/ServesChannelInsights.php) (`readingRoute()`)
- [src/Lead/Support/AnalysisPipeline.php](/src/Lead/Support/AnalysisPipeline.php) (`STEPS`: names, `routed`, prompt keys)
- [tests/Feature/Lead/AnalyseAllLeadsTest.php](/tests/Feature/Lead/AnalyseAllLeadsTest.php)
