fix(packaging): gaia api crashes at import when gaia-agent-email is installed — keyring missing from the [api] extra

[itomek]

Why this matters

The Milestone-40 consuming-app recipe — pip install gaia-agent-email 'amd-gaia[api]', then gaia api — crashes at server startup with core at main, before serving a single request: ModuleNotFoundError: No module named 'keyring'. Released 0.20.1 masks the bug (its server never imports the email wheel's router), so the moment the next core release ships, the partner path goes from "works but heuristic" to "won't start". This must land before the v0.21.0 release tag.

Found during real-world verification of the partner share path (#1602 follow-up) on a Linux machine with a Radeon dGPU: a cold venv with the wheel + core@main failed exactly this way; after hand-installing keyring, LLM triage worked end-to-end against local Lemonade (Gemma-4-E4B on GPU, planted facts echoed).

Root cause

openai_server.py on main auto-mounts the email wheel's REST router whenever gaia_agent_email is importable. That router's import chain reaches a module-level import keyring:

gaia.api.openai_server → gaia_agent_email.api_routes → summarize_tools
  → gmail_backend → gaia.connectors.api → flow → store  (src/gaia/connectors/store.py:38)

But keyring is declared only in the ui and dev extras (setup.py:133, setup.py:194) — not in core install_requires and not in [api]. So the documented [api] install is missing a package its own startup path imports.

Repro

python3 -m venv venv && . venv/bin/activate
pip install 'amd-gaia[api] @ git+https://github.com/amd/gaia@main' gaia-agent-email
gaia api
# → ModuleNotFoundError: No module named 'keyring' (from gaia/connectors/store.py:38)

Fix options

1. Add keyring>=24.0.0,<26.0.0 to the api extra — one line, matches how [ui] carries it. Smallest correct fix.
2. Add it to core install_requires — heavier (pulls SecretStorage/cryptography/jeepney on Linux) but makes a bare install robust.
3. Make the import lazy in gaia/connectors/store.py — triage-only deployments (no Gmail OAuth) then don't need OAuth deps at all. Nicer layering, but changes import semantics and needs a loud, actionable error at first real use.

Acceptance criteria

• Fresh venv: email wheel + amd-gaia[api] at the fixed ref → gaia api starts and POST /v1/email/triage serves LLM triage with zero manual package installs.
• Fix is in main before the v0.21.0 release tag is cut.
• Partner instructions (docs(email): guide for third-party apps integrating the Email Triage agent over the API (connection forwarding + triage/draft/send) #1597) state the exact install line a consuming app needs.

Related

#1602 (verification that surfaced this), #1590 (the LLM triage REST router), #1597 (partner integration guide), #915 (keyring for OAuth token storage), #1179 (distribution)

[github-actions]

🟡 Confirmed — the diagnosis is accurate on main.

• The [api] extra carries only fastapi/uvicorn/python-multipart (setup.py:119-123) — no keyring, which lives in [ui] and [dev] (setup.py:133, :194).
• openai_server.py:105-113 unconditionally mounts the email wheel's router whenever gaia_agent_email is importable, and that import chain hits a module-level import keyring at src/gaia/connectors/store.py:38.

So pip install 'amd-gaia[api]' gaia-agent-email → gaia api imports a package the [api] extra never declares. Real bug, not config.

Recommended fix: option 1 — add keyring>=24.0.0,<26.0.0 to the api extra. It's the smallest correct change and mirrors exactly how [ui] already carries it (same pin, same supply-chain upper bound). Option 2 (core install_requires) over-reaches — it pulls SecretStorage/cryptography/jeepney into every bare install for a path most users never touch. Option 3 (lazy import in store.py) is the cleaner long-term layering but changes import semantics and, per the no-silent-fallback rule, needs a loud actionable error at first real OAuth use — more surface than a packaging hotfix should carry this close to a tag.

One thing worth a quick check before closing: store.py is reached through gaia.connectors.api, which several non-email paths also touch — so keyring being absent from [api] may bite more than just the email router. Worth confirming whether it belongs in the connectors runtime deps rather than (or in addition to) the [api] extra, so a future connector-using [api] deployment doesn't hit the same wall.

A maintainer will need to land and tag this — flagging for the v0.21.0 cutoff. cc @kovtcharov-amd

[github-actions]

Opened #1618 with a fix.

What was fixed: keyring was declared only in the [ui]/[dev] extras, but gaia api's startup path imports it (via the email wheel router → gaia/connectors/store.py:38). Added keyring>=24.0.0,<26.0.0 to the [api] extra — same pin the [ui]/[dev] extras already use.

How to verify:

1. python3 -m venv venv && . venv/bin/activate
2. pip install 'amd-gaia[api] @ git+https://github.com/amd/gaia@autofix/issue-1617' gaia-agent-email
3. gaia api
4. Confirm it starts (no ModuleNotFoundError: No module named 'keyring') and POST /v1/email/triage serves LLM triage.

The PR is a draft — lint and the new packaging-assertion test (tests/unit/test_api_extras.py) pass, but the fresh-venv install against a running Lemonade server needs manual validation; steps above. A maintainer can validate and merge before the v0.21.0 tag.

On the open question from the triage comment (does keyring belong in the connectors runtime deps rather than just [api]?): this PR takes the minimal pre-tag fix — [api] is the documented install that breaks today. The broader question of whether non-email [api] connector paths also need it is worth a follow-up but doesn't block the release.