Centralize the LLM model names and record the vision default

[hechth]

Refs #145 — deliberately not Closes, see "Unresolved" below.

Validation of the issue against main

The issue is stale in its main claim. Checked on main (d5f61cc):

Issue claim	Actual state on main
"main still contains the retired model name"	False — git grep llama-4-scout origin/main -- src tests examples returns nothing. PR #149 merged 2026-09-24, bringing the swap.
"tests/test_pymupdf_parser.py:147 still uses redhatai-scout"	False — that site is qwen3.5-122b. The only redhatai-scout left in the repo is a test fixture string in tests/test_service_availability.py:27, where it is deliberate sample content for the failure classifier, not a model being requested.
"examples/find_chemicals_relationships.py:57,68 duplicate the class default"	True, still there.
"examples/parse_pdfs.py:14 uses qwen3.5"	True, still there.
"No decision is recorded anywhere about which model is the supported vision model"	True.

So of the four remaining items, only 3 (make the model configurable) and 4 (align example model names) plus the recording part of 2 were still actionable. Item 1 (confirm the model is currently available) could not be verified — see below.

Changes

• DEFAULT_MODEL = "gpt-oss-120b" and DEFAULT_VISION_MODEL = "qwen3.5-122b" defined once in src/aoptk/text_generation_api.py, in the style of the existing module-level topics constant. __init__'s default now refers to DEFAULT_MODEL instead of repeating the literal.
• The four vision call sites (tests/test_text_generation.py ×3, tests/test_pymupdf_parser.py ×1) use DEFAULT_VISION_MODEL. examples/parse_pdfs.py — which does figure→text vision work and passed a bare qwen3.5 — now uses the same constant.
• examples/find_chemicals_relationships.py passed model="gpt-oss-120b", i.e. the class default, in two places; it now passes no model. The issue itself flags this duplication as a problem, and dropping it rather than introducing a DEFAULT_MODEL import keeps this PR clear of Retry LLM answers the transport accepted but we cannot use #154, which rewrites the same loop.
• DEFAULT_VISION_MODEL carries the rationale the issue says was recorded nowhere.
• New tests/test_default_models.py: greps src/aoptk for retired model names, and pins that the constructor default is the shared constant rather than a second copy of its value.

After this, git grep 'model="' over tracked source, tests and examples returns nothing.

Why a static test for retired names

While working on this I found the reason the issue's own verification step ("grep returns nothing") deserves a test rather than a checklist item. tests/service_availability.py classifies "invalid model name" as a service problem, so when the endpoint reports a retired model, the vision tests xfail instead of failing. A regression to a retired model therefore silences the four live vision tests rather than breaking them — the suite structurally cannot catch it. tests/test_default_models.py covers the part the live tests cannot, and is fast, offline, and non-fragile (it names retired models, not the current one, so a routine model bump does not break it).

Unresolved — needs a key to settle, and I did not guess

I could not confirm step 1: whether qwen3.5-122b is still available. GET /v1/models returns 401 without a key, and I have no CERIT_API_KEY here. I kept the value at qwen3.5-122b rather than inventing a replacement, and the comment does not claim it is verified.

Worth flagging: CI evidence suggests qwen3.5-122b may itself now be retired.

• Run 28241321216 (June, on qwen3.5-122b): the three vision tests PASSED.
• Runs 35978921687 and 35981367222 (this month, same model string): all four vision tests XFAIL, while every live test using the default model passes in the same runs.

The only variable between passing and xfailing is the vision model name. Given the masking behaviour above, that pattern is consistent with qwen3.5-122b having been retired — but xfail truncates the reason in -v output and I could not extract it from the logs, so this stays a hypothesis, not a conclusion. This needs someone with a key to run pytest -m openai -rs and read the reason; if it is a retired model, the constant is the one-line fix, which is the point of centralizing it.

pytest -m openai is not run on SonarCloud, only on the build matrix's 3.12/ubuntu job.

Verification

• ruff check, ruff format --check, mypy — clean.
• pytest -m "not openai" on main + this change: 125 passed, 2 skipped, 25 xfailed on the offline subset; full suite run on the pre-change tree gave 157 passed / 3 skipped / 25 xfailed / 53 xpassed, no regressions.
• pytest -m openai --collect-only collects all 19 live tests.
• Constants resolve; TextGenerationAPI().model == DEFAULT_MODEL.

Deliberately not touched

• tests/test_service_availability.py:27 — redhatai-scout there is sample error text for the failure classifier. Renaming it would weaken that test to satisfy a grep. The new test scopes its scan to src/aoptk for this reason.
• Making the vision model settable from outside the process (env var / config). The issue offers "a class-level constant or a constructor argument"; the constructor already takes model=, so the constant is the missing half. An env override is a separate design decision.

🤖 Generated with Claude Code