Discover AI Pass Models at Runtime by Method and Capability

Discover a usable method, not a familiar model name

Hardcoding a model identifier turns a catalog change into an application release. An agent integrating AI Pass should instead express what an action requires, retrieve the current catalog, and select among compatible entries. A remembered model name is neither a runtime dependency contract nor evidence that the action can use it today.

Consider an illustrative accessibility tool called Readback. Its first action converts text into speech. The requirement is an audio output through the speech method, not merely a model with “audio” in its description. Transcription models may advertise audio capabilities too, while accepting an entirely different request shape.

During preparation on September 15, 2026, a read-only request to the public model catalog returned HTTP 200 without credentials. Its top-level object was list, with entries under data. Observed entry fields included id, object, created, owned_by, name, description, type, capabilities, and methods. Some descriptions were null. This is an observed contract snapshot, not a guarantee that every field remains unchanged forever.

Keep discovery separate from authenticated inference

A minimal read-only inspection is:

curl --fail --silent --show-error https://aipass.one/v1/models

This command retrieves catalog metadata. It does not connect a wallet, authorize model use, or prove that an inference request will succeed. Use the canonical integration skill and its selected path references for connection and setup. The REST documentation defines the inference surface; the catalog is not a replacement for method-specific request documentation.

Observed methods distinguished audio_speech from audio_transcription and audio_translation. Other entries advertised methods such as chat_completions, responses, embeddings, image_generation, or video_generation. For Readback, require audio_speech plus the relevant advertised audio capability. Do not infer speech support from a broad type value alone.

Normalize defensively and retain runtime identifiers

This standalone Python function accepts a parsed catalog and returns runtime IDs. Its fixture is intentionally synthetic and demonstrates filtering rather than claiming to reproduce the live inventory.

def candidates(catalog, method, required):
    if not isinstance(catalog, dict) or catalog.get("object") != "list":
        raise ValueError("Unexpected catalog envelope")
    rows = catalog.get("data")
    if not isinstance(rows, list):
        raise ValueError("Missing model list")
    matches = []
    for row in rows:
        if not isinstance(row, dict):
            continue
        model_id = row.get("id")
        methods = row.get("methods")
        caps = row.get("capabilities")
        if not isinstance(model_id, str) or not model_id:
            continue
        if not isinstance(methods, list) or not isinstance(caps, list):
            continue
        if not all(isinstance(value, str) for value in methods + caps):
            continue
        if method in methods and set(required).issubset(caps):
            matches.append(model_id)
    return sorted(set(matches))

fixture = {"object": "list", "data": [
    {"id": "fixture-speaker", "methods": ["audio_speech"],
     "capabilities": ["audio", "text"]},
    {"id": "fixture-listener", "methods": ["audio_transcription"],
     "capabilities": ["audio", "text"]}
]}
assert candidates(fixture, "audio_speech", {"audio"}) == ["fixture-speaker"]

The fixture labels are not deployable model defaults. In application code, the chosen identifier comes from the current compatible set. Present readable names where available, but retain the exact returned identifier for selection. Do not rewrite it into a guessed provider prefix.

Separate compatibility from ranking

Alphabetical ordering makes this example deterministic; it does not identify the cheapest or highest-quality model. Readback should ask the user to choose among compatible candidates or apply an explicit, separately evidenced policy. The observed catalog fields do not establish a complete pricing schedule, latency guarantee, voice list, input limit, or permission to use private data.

Persist the chosen ID with the required method and a catalog observation time. Refresh discovery at a defined application boundary, and revalidate a persisted choice before a new action. If it disappears or loses the required method, show an unavailable-selection state rather than silently changing models and cost expectations.

Test change, absence, and malformed data

Use fixtures for an empty catalog, absent methods, null descriptions, malformed capability arrays, duplicate IDs, and a selected model removed on refresh. A fetch failure should produce an explicit catalog-unavailable state. A bounded cache can support display, but stale metadata must be labeled and should not be mistaken for current availability.

Consult the SDK documentation if Readback uses the browser path. Keep the model selector independent of the actual inference adapter so these compatibility tests run without spending. The finished artifact is a validated discovery boundary, a capability-and-method selection policy, and tests for catalog evolution, not a frozen list of fashionable model IDs.

---
name: aipass-runtime-model-selection
description: Use when implementing model discovery. Validate the observed catalog and select by method and capabilities without fixed model IDs.
---

# Runtime model discovery integration

## Scope
Build a read-only catalog boundary and local selection tests. Public discovery is not authenticated inference and does not authorize spending. Never embed a historical model identifier as the deployment default.

## Observation
Fetch `https://aipass.one/v1/models` with a bounded timeout and record observation time and HTTP status. Do not include credentials in this public read. The September 2026 observed envelope was `object: list` and a `data` array; entries exposed `id`, `methods`, `capabilities`, and descriptive fields including nullable descriptions. Verify the current response rather than assuming the snapshot is permanent.

## Procedure
1. Specify the action's required method and capabilities. Speech output requires a different method from audio transcription; broad modality labels are insufficient.
2. Validate the envelope and array shape. Reject or exclude malformed rows with an explicit policy. Accept unknown extra fields without giving them authority.
3. Filter using exact advertised method membership and required capability inclusion. Keep exact returned IDs; never synthesize prefixes or infer compatibility from display names.
4. Separate compatibility from ranking. Require user choice or an independently evidenced ranking policy; the catalog does not prove cheapest price, quality, input limits, or legal suitability.
5. Persist selection with requirements and observation time. Define refresh and stale-cache behavior. Revalidate saved choices and show unavailability rather than silently switching model or payer.
6. Test empty data, nullable descriptions, absent methods, malformed arrays, duplicate IDs, fetch failure, and selection removal using synthetic fixtures.
7. Run the parser against a captured public response without invoking any model.

## Deliverables
- `catalog-observation.json`: source URL, timestamp, status, schema summary; no secrets.
- Discovery parser and capability/method selector in the app's language.
- Runnable fixtures and `selection-policy.md` covering refresh, unavailable choices, and ranking.

## Boundaries
Read the [canonical integration skill](https://aipass.one/skills/aipass-integration/SKILL.md) for exact OAuth and setup procedures. Use [REST docs](https://aipass.one/docs/rest) for request semantics and [SDK docs](https://aipass.one/docs/sdk) when applicable. Completion means discovery and local selection are tested, not that inference or wallet funding was verified.