feat: one entry per provider, endpoints per type and model from a live dropdown

Reshapes setup around how a multi-model proxy is actually used: one config
entry per server/provider, then one endpoint per model added by hand, with
the model chosen from what that provider advertises right now.

Setup (async_step_user):
- Adds a Name field. With one entry per provider the title matters, and it
  was hardcoded to "ChatGPT" regardless of where the entry pointed. Blank
  falls back to the endpoint host via url_util.title_from_base_url.
  Deliberately absent from the reauth schema (now split out as
  STEP_REAUTH_DATA_SCHEMA): that step writes its input back into entry.data
  via data_updates, so a name field there would persist the title as
  connection data on every key rotation.
- Stops auto-creating four subentries. conversation/ai_task_data/stt/tts were
  all created up front carrying RECOMMENDED_* options, which pin OpenAI model
  names (gpt-4o-mini-tts, gpt-4o-mini-transcribe). Against a third-party
  endpoint those entities are dead on arrival -- the reported symptom was an
  install that "loads bits, it's all janky".
- Drops _async_abort_entries_match, so several entries may point at one
  server (one per provider-side key, for instance). Upstream aborts with
  already_configured on matching url+key.

Model discovery (new model_list.py, kept out of the vendored files like
url_util.py):
- async_fetch_model_ids asks the endpoint's GET /v1/models. It calls
  with_options(max_retries=0), because this runs while the user waits on a
  dialog and the SDK otherwise retries with backoff -- visible in the test
  run as repeated "Retrying request to /models" and a suite that went from
  5s to minutes.
- Returns [] on any OpenAIError, and model_field() then yields a plain text
  field instead of a dropdown, so an endpoint that serves /v1/responses but
  not /v1/models is still configurable by hand. The dropdown sets
  custom_value=True for the same reason (LiteLLM wildcard routes).
- Wired into all four types: conversation and ai_task_data on the additional
  step, stt (which hardcoded OpenAI's three transcribe models) and tts on
  init. TTS had no model field at all -- it silently used gpt-4o-mini-tts.

A new endpoint now starts with "recommended" unticked. Ticked, the flow ends
on the first step and never shows a model field, which is why the model
looked unpickable; reconfigure still keeps whatever was saved.

The model field stays on the additional step rather than moving to init. The
init position reads better, but 71 ported tests drive the model through the
additional step, several from parametrized option dicts that no mechanical
edit could relocate. Rewriting the only regression net against upstream to
save one click was the wrong trade.

Also: the setup description no longer says "your OpenAI API key", and
instructions_url pointed at a README anchor (#generate-an-api-key) that does
not exist -- now #configuration. strings.json re-verified against core's
RE_URL: 0 violations.

Local: 167 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 22:45:36 -04:00
1 parent 13c60c242a
commit e7fcb1d7a1
10 files changed
+583 -98

No files matched your search

+41 -13
View File
@@ -19,10 +19,15 @@ control, routing, key management or privacy, or you self-host models, there is n
tell the core integration about it. This fork adds a **Base URL** field to the config
flow and threads it to every client it creates.
## What you get
## How it is organised
Everything the core integration provides, as config **subentries** you can add more than
one of:
**One entry per server or provider**, and **one endpoint per model** underneath it.
Setup asks only for the connection; nothing is created on your behalf. You then add
endpoints yourself, picking the type and the model each time — so a single LiteLLM entry
can carry a conversation agent on one model, another on a second, and a TTS endpoint on
a third.
Each endpoint is one of four types, and each becomes its own Home Assistant entity:
- **Conversation agent** — an Assist conversation entity, with the LLM Assist API,
tool calling, and the full upstream option set (model, temperature, top-p, max tokens,
@@ -30,7 +35,9 @@ one of:
- **AI Task** — for `ai_task.generate_data` / image generation
- **Speech-to-text** — an STT entity
- **Text-to-speech** — a TTS entity, with speed control
- **Actions** — `openai_compatible.generate_content` and `openai_compatible.generate_image`
Plus two actions on the entry itself: `openai_compatible.generate_content` and
`openai_compatible.generate_image`.
## Requirements
@@ -53,15 +60,32 @@ Copy `custom_components/openai_compatible/` into your Home Assistant
## Configuration
The initial dialog asks for two things:
### 1. Add the provider
| Field | Notes |
| --- | --- |
| **Name** | Label for this provider, e.g. `LiteLLM`. Leave blank to use the endpoint's host. |
| **Base URL** | Full URL including any version path, e.g. `https://api.openai.com/v1`. Passed to the OpenAI SDK as-is. |
| **API key** | Optional — **leave blank** for an endpoint that does not authenticate. |
Then add one subentry per capability you want (conversation, AI Task, STT, TTS), each
with its own model and options.
Submitting it checks the connection with `GET /v1/models` and creates the entry. No
entities are created yet, deliberately: guessing them would mean pointing STT and TTS at
OpenAI model names your provider probably does not serve.
You can add **several entries for the same server** — one per provider-side key, say.
Upstream refuses this as a duplicate; this fork does not.
### 2. Add endpoints for the models you want
On the entry, use **Add conversation agent** / **Add AI task** / **Add speech-to-text** /
**Add text-to-speech**. Each flow offers a **model dropdown populated from that
provider's own `GET /v1/models`**, read when you open the form, so it lists what is
actually available right then. The dropdown also accepts a typed-in name, for a provider
that routes models it does not advertise (LiteLLM wildcard routes, for instance), and
falls back to a plain text box if the endpoint will not list models at all.
Repeat per model. Name each endpoint something you will recognise in Assist — the
subentry title becomes the entity name.
### Base URL rules
@@ -109,12 +133,16 @@ versions; several popular local servers still do not.
### Model names
The default and "recommended" model names come from upstream and are OpenAI's
(`gpt-4o-mini`, `gpt-4o-mini-tts`, `gpt-4o-mini-transcribe`, …). Set the model your
endpoint actually serves in each subentry's options. Upstream's lists of models that
don't support web search, image generation, and so on are also keyed to OpenAI names, so
they won't match a third-party model string — the endpoint's own error is what you'll
see if you ask for something it can't do.
Pick from the dropdown and this mostly takes care of itself. Two upstream behaviours to
know about anyway:
- The fallback defaults are OpenAI's (`gpt-4o-mini`, `gpt-4o-mini-tts`,
`gpt-4o-mini-transcribe`), used only if you never choose a model. A new endpoint starts
with **Recommended settings** unticked so the flow always asks.
- Upstream's lists of models that don't support web search, image generation, reasoning
effort and so on are keyed to OpenAI names, so they won't match a third-party model
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.
## Relationship to Home Assistant core