# Provider Catalogue

> What the provider catalogue lists, how LLM, ASR, and TTS entries are grouped, what the base URL governs, and how an agent pipeline references an entry.

The Providers screen in the inference console is a **read-only reference** of
the vendors the ClutchCall inference fabric can route to. It answers one
question: "what is routable right now, and under what name?" It does not test
connectivity, and it does not store or edit credentials.

Every row on that screen is tagged `configure in admin`. That tag is literal:
the catalogue is populated and credentialed from the authenticated admin
surface, and the operator console only reads the result.

## What the catalogue contains

The screen calls a single procedure, `providers.list`, and renders whatever it
returns. Each catalogue entry carries:

| Field     | Shown as                    | Meaning                                                                 |
| --------- | --------------------------- | ----------------------------------------------------------------------- |
| `id`      | (not displayed)             | The stable identifier you reference from an agent config.               |
| `name`    | Row title                   | Human-readable vendor label, e.g. `ClutchCall GPU · Qwen (vLLM)`.      |
| `cat`     | Section the row appears in  | One of `LLM`, `ASR`, `TTS`.                                             |
| `baseUrl` | The `BASE URL` column       | The HTTP endpoint the fabric routes requests to. Renders `—` if unset.   |
| `note`    | Sub-label under the name    | Free-form operator note. Renders `—` if unset.                           |

An entry appears in this catalogue because it exists in the provider catalogue
maintained in the admin surface. Nothing in the operator console creates,
edits, or removes entries — there is no write path on this screen. If a vendor
you expect is missing, it has not been added in admin; if a vendor is listed
but calls to it fail, the entry exists but its credentials or base URL need
attention in admin.

The three summary cards at the top of the screen are derived, not stored: each
one counts the entries whose `cat` matches that category. The count in a
section header is the same number, computed the same way. A category card
reading `0` means no entries of that category are in the catalogue at all.

## Categories: LLM, ASR, TTS

The catalogue groups entries into exactly three categories. The grouping is
what the console uses to decide which section a row is drawn in, and it is the
same axis an agent pipeline uses when it picks a provider for a pipeline stage.

| Category | Section heading            | What these entries serve                    |
| -------- | -------------------------- | ------------------------------------------- |
| `LLM`    | LLM providers              | Chat / completion / embeddings routing      |
| `ASR`    | Speech-to-text (ASR)       | Transcription vendors for voice pipelines   |
| `TTS`    | Text-to-speech (TTS)       | Synthesis vendors for voice pipelines       |

Categories are not hierarchical and an entry belongs to one category only. A
vendor that offers both transcription and synthesis appears as two separate
catalogue entries, one per category, each with its own `id`, `baseUrl`, and
credentials.

## Base URL and routing

`baseUrl` is the endpoint the fabric sends requests to for that entry. It is
the field that decides *where* traffic goes; the category decides *what shape*
the request has.

This is the field that lets one catalogue entry point at a hosted vendor API
and another point at your own deployment. A self-hosted OpenAI-compatible
server — for example a vLLM instance — is a normal `LLM` entry whose `baseUrl`
is your server's address rather than the vendor's. The console does not
distinguish the two cases: both render as ordinary rows in the LLM section.

Two consequences worth knowing:

- **Moving a workload between vendors or between hosted and self-hosted is a
  base-URL change on the catalogue entry**, not a change to every agent config
  that references it. Agents reference the entry, not the URL.
- **A blank base URL renders as `—`.** The console shows this without
  complaint, because it performs no validation and no reachability check. An
  entry with no base URL is listed as present but has no route.

The console has no live health test on this screen. Routing failures surface
where the traffic actually happens — in agent runs and in the fabric's own
telemetry — not here. See [Telemetry](/platform/telemetry).

## Where credentials are configured

Credentials are held in the admin surface and are never read by, rendered in,
or writable from this console. That is why each row's status column is a fixed
`configure in admin` tag rather than a per-provider state: the operator console
has no visibility into whether a key is present, valid, or expired, so it
asserts nothing about it.

The practical split:

| Task                                              | Where            |
| ------------------------------------------------- | ---------------- |
| Add a vendor to the catalogue                     | Admin surface    |
| Set or rotate a vendor's API credential           | Admin surface    |
| Set or change a vendor's base URL                 | Admin surface    |
| Set the operator note shown under the vendor name  | Admin surface    |
| See which vendors are routable, and under what id | This console     |

This follows the same principle as the rest of the platform: powerful,
long-lived credentials stay on the authenticated surface that owns them, and
read surfaces get names and identifiers only. See
[Authentication](/concepts/authentication).

## Referencing a provider from an agent config

An agent pipeline does not embed a vendor URL or a key. It names a catalogue
entry by its `id`, per pipeline stage, and the fabric resolves that id to the
entry's category, base URL, and credentials at call time.

Because the resolution happens at call time, a credential rotation or a base
URL change made in admin applies to every agent that references the entry,
with no agent-side edit.

When you are wiring up an agent and need the id for a vendor you can see on
this screen, the id is the value in the entry's `id` field — the row label is
the `name`, which is a display string and may change. Pin configs to `id`.

Two things to check when an agent's stage fails to resolve:

1. **The id exists in the catalogue.** If `providers.list` does not return it,
   the entry has not been added in admin.
2. **The id's category matches the stage.** An `ASR` entry cannot serve a
   synthesis stage, and an `LLM` entry cannot serve a transcription stage. The
   category on the row is the authoritative answer.

## Related

- [Authentication](/concepts/authentication) — where credentials live and how they are scoped
- [Telemetry](/platform/telemetry) — where provider-facing request behaviour is observable