suggest-pipeline-worker — business features

1. What it is

This worker has two unrelated jobs. The obvious one: it suggests things to an author — the outline a course should follow, and the improvement cards that appear in the editor sidebar ("this lesson is hard to read", "these three text blocks in a row need a break"). The less obvious one, and the more load-bearing: it is the only service that holds the OpenRouter account key, so authoring-service-v2 calls it over HTTP whenever authoring itself needs a model — including on a screen the admin is sitting in front of.

2. Feature map

flowchart LR
  ADMIN["Admin in the course editor"] --> AV2[authoring-service-v2]
  AV2 -. NATS .-> F1["Draft a course outline"]
  AV2 -. NATS .-> F2["Suggest improvements"]
  AV2 -- "HTTP (60s, blocking)" --> F3["Screen a course prompt"]
  AV2 -- HTTP --> F4["Read OpenRouter cost + balance"]
  F1 --> S1["authoring.suggest.outline.ready"]
  F2 --> S2["authoring.suggest.suggestions.ready"]
  F3 --> Q["missing-context questions"]
  F4 --> LEDGER["nightly cost reconciliation"]
  WATCH["Credits watchdog"] --> LOW["authoring.usage.credits_low"]

3. Features

Admin

Employee (mobile)

None.

Internal (other services)

Background

4. API reference

5. Async contracts

Consumes

Publishes

Background jobs

6. Data it owns

Three tables are functionally this worker's — and its own migrations/versions/ directory is empty (only a __pycache__), so it cannot create them. They are created by a micro-learning-service-v2 migration, in micro-learning's database, because they sit next to modules and lessons which the pipeline reads. In practice that means a fresh environment must migrate micro-learning before this worker can do anything, and a schema change here is a pull request against another service.

Cross-service write: this worker writes the microlearning database, which ARCHITECTURE.md §3.4 lists as owned by micro-learning-service-v2 (plus tts-worker-v2). The suggestion tables are disjoint from micro-learning's own writes, so this is a schema-ownership coupling rather than a row-level race — but it is the same class of hazard.

7. Dependencies

flowchart LR
  AV2[authoring-service-v2] -- "HTTP H3: prompt screening · credits · generation" --> SPW[suggest-pipeline-worker]
  AV2 -. "outline.requested · suggestions.requested" .-> SPW
  SPW -. "ready · failed · usage · credits_low" .-> AV2
  SPW -- "HTTP H10: context blob" --> RAG[rag-context-worker]
  SPW -- "LLM + embeddings" --> OR["OpenRouter (account key holder)"]
  SPW -- "suggestion tables" --> DB[("microlearning DB")]

8. Dead-code verdicts

Every entry point with no in-repo caller. Deleting is a separate decision — see the hub roll-up.

All five HTTP routes have a named caller or kubelet probe, and both consumers have a named authoring-v2 publisher.

9. Sources

• suggest-pipeline-worker/README.md — the two paths, the subject table, and the "schema lives in micro-learning" note
• suggest-pipeline-worker/TODO.md — contract-alignment log; still open: honouring authoring.tool-call.cancelled, usage events for verifier calls
• spec/SDD-suggest-pipeline-worker.md §4 (two-phase pipeline), §4.4 (deduplication), §5 (trigger rules), §6 (subjects), §7 (usage)
• bug-hunt-reports/suggest-pipeline-worker.md — 5 findings; #1 and #3 fixed, #2 (cross-tenant cache slot), #4 (publish outside try), #5 (watchdog cancel) open
• ARCHITECTURE.md §3.1 (spoke topology), §3.2 (H3, H10), §3.3 (AUTHORING_SUGGEST), §3.4/§3.5 (micro-learning DB, Redis index 8), §3.6 (OpenRouter key ownership), §4.4 (committed secrets)
• app/main.py, app/workers/, app/prompt_context_api.py, app/openrouter_api.py, app/services/credits_monitor.py, app/pipeline/, app/models/, migrations/versions/ (empty)
• Scan output tools/feature-docs/out/suggest-pipeline-worker.json