Harden OpenAIProvider readiness probe

[chris-colinsky]

Summary

Add a readiness_probe constructor kwarg on OpenAIProvider accepting "models", "chat_completions", or "both", and flip the default from the older catalog-only GET /v1/models probe to a new POST /v1/chat/completions probe with max_tokens=1.

Motivation: OpenAI-compatible proxies can return 200 on the catalog endpoint while rejecting completions (Bifrost is the field-reported case), so the previous probe reported ready while every real call failed. The new default actually exercises the inference wire path, so that failure class surfaces at preflight rather than at first real call. Non-200 chat-probe responses route through classify_http_error so canonical error categories (ProviderAuthentication, ProviderUnavailable, ProviderInvalidModel, etc.) surface consistently regardless of which probe ran. Catalog-only behavior remains opt-in for cost-sensitive cloud callers via readiness_probe="models".

The conformance harness now picks readiness_probe mode from the fixture's mocked health_endpoint.path so fixture 007's catalog semantics keep working without spec changes. Per the §5 fixture's own comment, the probe shape is implementation-defined.

This is a breaking change at the default level (pre-1.0 per the project's phased rollout policy). Pre-flight behavior changes for callers who construct OpenAIProvider without naming readiness_probe.

Test plan

• 10 new unit tests covering all three modes, the three motivating failure paths (Bifrost 405, network error, 503+model-not-loaded), and the both-mode catalog short-circuit
• Conformance fixture 007 still green via the harness's path-based probe-mode dispatch
• Full suite: 1075 pass, 210 skip, no regressions
• CHANGELOG [Unreleased] entry under ### Changed (breaking)
• docs/concepts/llms.md new "Pre-flight readiness check" section
• docs/agent/non-obvious-shapes.md entry for the agent-facing surface
• src/openarmature/AGENTS.md regenerated

[Copilot]

Pull request overview

This PR hardens OpenAIProvider.ready() by introducing a configurable readiness-probe mode and switching the default probe from the catalog endpoint (GET /v1/models) to an inference-path probe (POST /v1/chat/completions with max_tokens=1) to catch “catalog-green but inference-broken” proxies earlier.

Changes:

• Add readiness_probe kwarg to OpenAIProvider with modes "chat_completions" (default), "models", and "both".
• Update conformance harness to select probe mode based on fixture health_endpoint.path (keeping fixture 007 behavior stable).
• Add unit tests plus documentation and changelog entries describing the default flip and opt-out path.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/unit/test_llm_provider.py	Adds unit coverage for the three readiness probe modes and key failure cases.
tests/conformance/test_llm_provider.py	Dispatches readiness probe mode based on fixture health_endpoint.path.
src/openarmature/llm/providers/openai.py	Implements readiness_probe and adds a chat-completions readiness probe path.
src/openarmature/AGENTS.md	Documents the new default readiness behavior and opt-out modes.
docs/concepts/llms.md	Adds a “Pre-flight readiness check” section documenting probe modes and tradeoffs.
docs/agent/non-obvious-shapes.md	Documents readiness probe behavior for agent-facing surfaces.
CHANGELOG.md	Records the default readiness-probe flip as a breaking change under Unreleased.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.