feat(agent-email): add GET /v1/email/init readiness preflight (#1795)

[kovtcharov]

Why this matters

A fresh host passed /health and /version green even with Lemonade down and no model downloaded — then 502'd on the very first triage call. Every readiness signal said "ready" while the stack couldn't actually triage. GET /v1/email/init closes that trap: it probes the whole triage stack (Lemonade reachable + the triage model downloaded) and returns a structured status — 200 when ready, 503 when not, with an actionable hint — so an integrator (and the npm package's startSidecar) can verify "ready to triage," not just "process up."

// GET /v1/email/init  → 200 ready / 503 not ready
{ "ready": false,
  "lemonade": { "reachable": true, "base_url": "http://localhost:8000/api/v1" },
  "model": { "id": "Gemma-4-E4B-it-GGUF", "present": false, "loadable": null },
  "hint": "Model `Gemma-4-E4B-it-GGUF` not downloaded — run `gaia init` (or pull it via Lemonade), then retry." }

Read-only by design: probes only, no model pull or provisioning (a deferred follow-up). loadable is null in v1 — forcing a load is heavy, so present (a cheap model-list lookup) is the readiness signal. The reachability probe reuses the existing short-timeout /health logic (#1677) via a shared base-URL resolver, so "Lemonade down" fails fast instead of hanging on the OS SYN timeout. Failures are loud: even when Lemonade answers /health but its model list can't be read, the endpoint returns 503 with a specific hint rather than silently reporting "absent."

Scope: Python sidecar + its tests/docs only — the npm client wrapper and playground are handled separately.

Test plan

• pytest tests/unit/agents/email/test_init_endpoint.py — 16 tests: probe call-shape at the boundary (URL suffix, short timeout, auth header), Lemonade-down → 503 + hint, model-missing → 503 + hint, model-list-unreadable → 503 + hint, ready → 200, sidecar mount via packaging/server.py build_app().
• pytest tests/test_email_openapi_conformance.py hub/agents/python/email/tests/test_rest_contract.py — running-server conformance (200/503) + committed openapi.email.json is drift-free.
• pytest tests/unit/agents/email/test_spec_html.py — runtime /v1/email/spec page documents the new endpoint.
• python -m gaia_agent_email.export_openapi --check — /v1/email/init present, artifact up to date.
• python util/lint.py --black --isort --flake8 on the changed files — clean.

Docs synced: runtime /v1/email/spec page (spec_html.py), the hand-maintained specification.html (new #ep-init block + 503 row), and the regenerated openapi.email.json.

[github-actions]

Review: PR #1813

Summary

The code here is solid and well-tested, but the PR is mistitled and under-described: it's titled feat(agent-email): add GET /v1/email/init … (#1795), yet the actual substance — and the bulk of the commits — is refactor(agents): migrate docqa + routing to hub (#1102). The email-init endpoint it advertises already landed on main (commit 2c9f0cea), so most of that part of the diff is a carry-along that will no-op on rebase. The migration itself is clean and consistent: no dangling gaia.agents.{docqa,routing} references remain anywhere, and setup.py, errors.py, the lint import lists, and the conventions checker were all updated in lockstep. The single most important thing to fix is the title + description so a reviewer (and the squashed commit / changelog) reflects what actually changed.

Issues Found

🟡 Title and description describe #1795, not the change being reviewed
The commit list is dominated by the #1102 docqa/routing hub migration (new gaia-agent-docqa / gaia-agent-routing wheels, two new CI workflows, setup.py extras, registry/error/lint updates). The PR description says "Scope: Python sidecar + its tests/docs only" and never mentions the migration at all — a reviewer reading it would miss the entire point of the PR. Per CLAUDE.md, the title is the technical handle and the description sells the merge; both currently point at the wrong change. Please:

• retitle to refactor(agents): migrate docqa + routing to hub (#1102),
• rewrite the description around the migration (and add a short threads list if the email-init bits are genuinely meant to ride along),
• rebase on current main to drop the already-merged feat(agent-email): add /v1/init readiness+provisioning endpoint (validate Lemonade + model) #1795 diff so the review surface is just the migration.

🟢 FRAMEWORK_PATHS now inconsistent with editable hub installs (src/gaia/agents/base/errors.py:14)
This drops gaia/agents/routing, but gaia/agents/code — also migrated to a hub wheel — is still listed. More to the point, in an editable install (pip install -e hub/agents/python/routing) routing frames live at hub/agents/python/routing/…, which matches neither site-packages/ nor any remaining entry, so they'd leak into user-facing error traces. Dev-only impact and consistent with how code is already handled, so non-blocking — but worth a follow-up to filter hub/agents/python/ uniformly.

🟢 gaia-agent-code hard-depends on an unpublished gaia-agent-routing>=0.1.0 (hub/agents/python/code/pyproject.toml:13)
A PyPI install of gaia-agent-code will fail to resolve until gaia-agent-routing is published. CI works around it by installing the local wheel first and the README documents it, so this is a release-ordering note, not a defect — just make sure routing publishes before/with code.

🟢 docs/guides/email.mdx not updated for the readiness preflight (optional)
The new endpoint is documented in the agent's own specification.html / spec_html.py / openapi.email.json, which is the right contract surface. If the email-init work stays in this PR, a one-line mention of /v1/email/init in the user guide would help discoverability. Skip if you rebase the email bits out.

Strengths

• Test quality on the init endpoint is exemplary (tests/unit/agents/email/test_init_endpoint.py): it asserts the shape of the outgoing probe — /api/v1/health and /models suffixes, the short connect/read timeout pair, and the Authorization: Bearer header — plus 200/503 status mapping, strict no-extra-fields serialization, and the sidecar mount via packaging/server.py. This is exactly the "verify call validity at boundaries" rule from CLAUDE.md, not just "we called it."
• The migration is genuinely complete. Grep confirms zero remaining gaia.agents.docqa / gaia.agents.routing references; the conventions checker, FRAMEWORK_PATHS test, and both lint import lists were all updated, and the routing package correctly ships without a gaia.agent entry point (it's class-path infrastructure) while docqa ships with one.
• Fails loudly, no silent fallback (src/gaia/api/agent_registry.py): the gaia-code load path raises ValueError(... ) from e with a concrete pip install hint instead of degrading — matches the No-Silent-Fallbacks rule.
• Thoughtful CI wiring: path triggers include agent_registry.py for routing (loaded by class path) and tools/** for docqa (uses RAG/file mixins), and the routing-before-code install ordering is documented inline.
• Running probes through asyncio.to_thread keeps the sync requests calls off the event loop.

Verdict

Request changes — no code defect blocks merge; the blocking item is purely the 🟡 title/description mismatch (and the rebase to drop the already-merged #1795 diff). Fix those and this is an approve. The two remaining 🟢 items are follow-ups, not gates.

[github-actions]

🟡 hub/agents/python/email/gaia_agent_email/api_routes.py — blocking I/O in a sync generator freezes the event loop

email_provision() wraps the initial _probe_lemonade_reachable() in asyncio.to_thread (correct), but then hands a synchronous generator to StreamingResponse. When Starlette iterates that generator it calls next() on the event loop thread — so every blocking requests.* call inside _provision_progress (including _pull_model with its 30-minute (5.0, 1800.0) timeout) stalls the entire server.

Every other blocking route in the file already uses asyncio.to_thread (e.g. send_email, email_triage, email_init). The fix is the same pattern: run the generator body in a thread, or use an async generator with await asyncio.to_thread(...) for each blocking step:

# Option A — simplest: wrap the entire generator in run_in_executor
import asyncio
from starlette.concurrency import iterate_in_threadpool

@router.post("/init", include_in_schema=False)
async def email_provision() -> StreamingResponse:
    ...
    return StreamingResponse(
        iterate_in_threadpool(_provision_progress(probe_base, model_id)),
        media_type=media_type,
        status_code=200,
    )

iterate_in_threadpool is already available in Starlette (used internally by FastAPI for sync response bodies) and is the canonical approach here.