docs: record the provider-genericity audit

Writes up what is still OpenAI-specific in this fork, since the base URL
being configurable is what makes it reach a compatible endpoint, not what
makes it behave correctly against one. Four findings, each with what it
actually costs:

1. service_tier, store and prompt_cache_retention are sent on every
   request whatever the provider is (entity.py:515-563); reasoning,
   include and text.verbosity are gated on OpenAI name prefixes.
2. 23 startswith() model-name gates plus the UNSUPPORTED_* lists infer
   capability from OpenAI naming, which fails in both directions: service
   tier, code interpreter and web search are offered to providers that
   cannot honour them, while reasoning effort/summary and verbosity are
   withheld from any model whose name does not look like OpenAI's.
3. manufacturer="OpenAI" and the "Error talking to OpenAI" error text.
4. Repair issues citing core's 2026.9.0 removal schedule, which has
   passed and was never this fork's commitment, and an OpenAI-only
   organization-verification repair.

Two things worth having written down beyond the list itself:

- A proxy set to drop incompatible parameters hides finding 1 entirely
  and makes finding 2 worse, because a dropped parameter turns a
  misconfigured option into a silent no-op rather than an error. Testing
  only against such a proxy therefore says nothing about portability, and
  a strict server is the honest target. This reorders the priorities:
  finding 2 first, since it is what the user sees and the failure is
  silent; finding 1 matters for setups without a normalising proxy.
- The prerequisite decision is recorded rather than assumed. There is no
  capability discovery in the OpenAI API -- GET /v1/models returns ids,
  not feature support -- so the three candidates (per-entry capability
  toggle, host detection, per-endpoint checkboxes) are laid out with
  their trade-offs and explicitly marked unsettled.

No behaviour change; the README links it from a short "known
OpenAI-specific behaviour" section so it is findable from the front page.

Local: 170 passed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NxJYWgGJtCw13qUHZtG8ki
This commit is contained in:
Adam SmithandClaude Opus 5 committed 2026-09-17 23:32:21 -04:00
1 parent 4611674c6e
commit b79164b60c
2 files changed
+123

No files matched your search

+10
View File
@@ -144,6 +144,16 @@ know about anyway:
string. Options are offered based on those name patterns, and the endpoint's own error
is what you'll see if you ask for something it can't do.
## Known OpenAI-specific behaviour
The base URL is configurable, but much of the rest is still upstream's OpenAI-shaped
logic: some request parameters are sent to every provider, and which options the config
flow offers is inferred from OpenAI model-name prefixes. That means options can appear
for endpoints that cannot honour them, and be withheld from endpoints that could.
[`docs/provider-genericity.md`](docs/provider-genericity.md) has the full audit, what
each item costs, and the design decision that has to be made first.
## Relationship to Home Assistant core
`custom_components/openai_compatible/` is derived from