# Reviewed learning for Phone Buzz

The first learning workflow improves the local model's context using checked examples. It does not rewrite model weights or automatically trust its own output. The administrator workflow is available on the web and native iOS/Android clients.

## What happens automatically

- Creating a new AI-assisted email-to-trading draft captures its original reviewed values as a **Needs review** candidate, in the same transaction as the draft and source link. Retrying draft creation does not create duplicates. Manual reviews without an AI suggestion are not captured, and old records are not backfilled.
- With `PB_AI_LEARNING_ENABLED=true`, new local Ollama jobs select relevant approved examples using brand/model word overlap. There are at most three examples, with strict serialized size limits to fit the model context. No OpenAI request receives these examples.
- Each completed job preserves the exact example IDs, versions, excerpts and expected output used in that request. The review UI shows how many examples were used. Trading provenance retains IDs/versions alongside the original suggestion and human corrections.
- Pending, rejected, retired and evaluation-only examples are excluded. The requesting email's conversation and direct normalized copies/overlapping excerpts are excluded. Examples approved by a staff member who is no longer an active administrator are excluded.
- If a selected example changes, is retired or loses its eligible approver during generation, the result fails instead of becoming a ready suggestion. An explicit retry may then use the current approved set. Completed historical suggestions keep their original snapshots.

Approved examples are demonstrations, not system instructions. Source evidence and field validation still run on the new output. All commercial drafts still require staff confirmation. A relevant example can also hurt extraction quality; approval and measurement remain necessary.

## Administrator workflow

1. Staff review an AI suggestion in Inbox, correct the trading details and create the draft.
2. An administrator opens **AI learning → Needs review → Review example**. The original suggestion appears beside the reviewed values. Differences are not automatically treated as model mistakes: staff may have used information confirmed outside the email.
3. Copy a continuous, single-item passage from the source into **Single-item source excerpt**, at most 1,200 UTF-8 bytes. Exclude signatures, contacts and sensitive information by selecting a narrower passage. It must remain verbatim; this version does not support arbitrary redacted rewrites.
4. Check all ten fields against that excerpt. Keep exact supported text, including decimal digits; clear unsupported fields to blank. The model name must be present. Canonical catalogue wording, default network status and currencies entered during trading review may need to be cleared or changed to match the source wording.
5. Confirm the review and either **Approve for local learning** or **Reserve for evaluation**. Editing any field clears confirmation. Approving immediately makes the example eligible for subsequent local jobs; queued jobs select examples when claimed, not when first requested. No training/restart is required after each approval.
6. Use **Retire example** to stop future selection. Approved examples can be edited with another explicit review. Evaluation-only examples are frozen and can only be retired; they can never be switched into teaching examples. Version checks reject stale edits while keeping unsaved client values available.

A narrow contact guard rejects email-address markers, URLs and common domain names. It does not automatically detect all names, phone numbers or business-sensitive text. The administrator's source review is still required. Viewers and traders cannot access learning administration; their ordinary trading permissions are unchanged.

## Enable or pause memory

Set the same option for API disclosure and the local worker, alongside the existing Ollama configuration, then restart both:

```dotenv
PB_AI_ENABLED=true
PB_AI_PROVIDER=ollama
PB_AI_MODEL=qwen3:4b
PB_OLLAMA_PORT=11435
PB_AI_LEARNING_ENABLED=true
```

The default is false. The local development preview is started with this option enabled. There are no seeded learning examples in its database: staff must create and review real candidates. Set it to false and restart to stop adding examples to new requests while retaining ordinary local extraction and history. It does not cancel an already-issued call. The Mac must remain awake; see LOCAL-AI.md for model/API/worker startup.

The helper budgets at most 3,600 UTF-8 bytes for selected example snapshots, including expected values and quotes. The adapter additionally limits serialized chat demonstrations to 5,000 bytes and may retain fewer examples. The current email remains limited to 16,000 UTF-8 bytes. Full emails, attachments, staff notes and the company directory are not included as teaching material. Only the approved excerpt and its labels are sent to the local model.

## Measuring progress before weight training

A separate read-only tool compares baseline and assisted prompts against frozen evaluation examples, recording field correctness, missing/unsupported values, item counts, errors and timing. It checks the installed model digest so changing the model mid-run cannot silently invalidate the comparison. See LEARNING-EVALUATION.md for commands, partition rules and report interpretation. No evaluation calls run automatically, no report automatically changes the model, and no fine-tuning or automatic retraining has been performed.

In one live synthetic integration check, baseline matched 9 of 10 expected field labels and the assisted prompt matched 10 of 10. The reference had different quantity, price and color from the test input. This is a tiny development check, not a held-out business benchmark or evidence of a general accuracy improvement. Real supplier samples and independent evaluation are still needed.

The practical next step is to build a varied collection of reviewed examples and a separate evaluation set. If repeated failures remain, prepare a versioned fine-tuning dataset and compare a trained candidate against the unchanged baseline before promotion. There is no fixed training timeline or guarantee of continuous improvement.

## Storage and migration

Migration `7915a1de337c` adds only `learning_examples`. It does not rewrite existing users, trading records, suggestions or credentials. A downgrade refuses to discard populated learning data. Back up first. Example lifecycle changes are audited. Source body and original trading review remain immutable; approved learning labels can differ when trading facts were inferred outside the source.

API: administrator-only `GET /v1/learning` supports state/limit/offset; `POST /v1/learning/{id}/review` requires current version, action, excerpt, labels and confirmation for approval/evaluation. Request bodies remain bounded by the web proxy and field validation. Live email testing remains deferred. Native hardware operation, PostgreSQL contention and production deployment remain separate checks.