> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Catalogue

> Discover, describe, and validate LLM models from the praisonai CLI

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(name="model-agent", instructions="Manage and switch LLM models via CLI.")
agent.start("List all available models and switch to gpt-4o.")
```

The user lists or switches models from the terminal; the agent uses the catalogue the CLI exposes.

Discover which models you can use, what they cost, and whether they support tools or vision — all from the terminal.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Model Catalogue"
        Terminal[💻 Terminal] --> CLI[praisonai models]
        CLI --> Cat[Model Catalogue]
        Cat --> LiteLLM[litellm live data]
        Cat --> Cache[~/.praison/cache\n1h TTL]
        Cat --> Fallback[Static fallback\nOpenAI · Anthropic · Google · Groq · Ollama]
        Cat --> Out[✅ Capabilities\nLimits · Costs]
    end

    classDef input fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef data fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class Terminal input
    class CLI,Cat process
    class LiteLLM,Cache,Fallback data
    class Out output
```

## Quick Start

<Note>
  As of PraisonAI 4.6.106 (PR #2549), `ModelCatalogue` is a first-class module of the standalone `praisonai-code` package. The `models` commands work without installing the full `praisonai` wrapper:

  ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  # Works with pip install praisonai-code only
  praisonai models list
  praisonai models describe gpt-4o
  praisonai models validate gpt-4o-mini
  ```
</Note>

<Steps>
  <Step title="Browse all models">
    List every available model grouped by provider:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai models list
    ```

    Filter to a single provider:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai models list --provider openai
    ```

    Search by name substring:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai models list gpt
    ```
  </Step>

  <Step title="Inspect a model">
    Get full capabilities, limits, and cost for one model:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai models describe gpt-4o
    ```

    Sample output:

    ```
    Model: gpt-4o
    Provider: openai
    Description: Most capable GPT-4 model, multimodal

    Capabilities:
      • Tool calling: ✅
      • Vision: ✅
      • Reasoning: ✅
      • Streaming: ✅

    Limits:
      • Context window: 128,000 tokens
      • Max output: 16,384 tokens
    ```
  </Step>

  <Step title="Validate a model ID">
    Check whether an ID is valid — and get suggestions on a typo:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai models validate gpt-4o-mni
    ```

    Output on a typo:

    ```
    ❌ 'gpt-4o-mni' is not a valid model
    Did you mean one of these?
      • gpt-4o-mini
      • gpt-4o
    ```

    Output on a valid ID:

    ```
    ✅ 'gpt-4o' is a valid model
    Capabilities: tool-calling, vision, reasoning
    ```
  </Step>
</Steps>

## Agent-Centric Example

Use the catalogue to pick the right model for your agent before you run it:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(
    name="Writer",
    instructions="Write concise summaries.",
    llm="gpt-4o",
)
agent.start("Summarise the latest release notes")
```

YAML equivalent — invalid `llm:` values emit a warning at load time, and pairing `tools:` with a non-tool-calling model (like `o1`) triggers a compatibility warning:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
framework: praisonai
topic: Summarise release notes
agents:
  writer:
    role: Writer
    instructions: Write concise summaries.
    llm: gpt-4o          # validated against catalogue on load
    tools:
      - InternetSearchTool
    tasks:
      summarise:
        description: Summarise the latest release notes.
        expected_output: A short summary paragraph.
```

<Note>
  YAML aliases defined under a top-level `models:` key are accepted even if they are not in the catalogue. This lets you point to custom or private deployments without triggering warnings.
</Note>

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant CLI
    participant ModelCatalogue
    participant LiteLLM
    participant Cache

    User->>CLI: praisonai models list
    CLI->>ModelCatalogue: list_models()
    ModelCatalogue->>Cache: load (~/.praison/cache/models.json)
    alt Cache hit (< 1h old)
        Cache-->>ModelCatalogue: model list
    else Cache miss
        ModelCatalogue->>LiteLLM: model_list + model_cost
        alt litellm installed
            LiteLLM-->>ModelCatalogue: live data
            ModelCatalogue->>Cache: save
        else litellm not available
            ModelCatalogue-->>ModelCatalogue: static fallback list
        end
    end
    ModelCatalogue-->>CLI: models[]
    CLI-->>User: formatted table / JSON
```

**Data sources — priority order:**

| Source                                | When used                     | What it provides                          |
| ------------------------------------- | ----------------------------- | ----------------------------------------- |
| `~/.praison/cache/models.json`        | Cache \< 1 h old              | Full list saved from previous live call   |
| litellm (`model_list` + `model_cost`) | Cache miss, litellm installed | Live data: 100+ models with cost & limits |
| Curated static list                   | litellm unavailable / error   | OpenAI, Anthropic, Google, Groq, Ollama   |

## Commands Reference

### `praisonai models list`

List available models, grouped by provider.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai models list [SEARCH] [OPTIONS]
```

| Flag / Argument    | Type               | Description                                                            |
| ------------------ | ------------------ | ---------------------------------------------------------------------- |
| `search`           | `str` (positional) | Filter by substring in the model ID (e.g. `gpt`, `claude`)             |
| `--provider`, `-p` | `str`              | Filter by provider (`openai`, `anthropic`, `google`, `groq`, `ollama`) |
| `--json`           | `bool`             | Machine-readable JSON output                                           |

**Examples:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# All models
praisonai models list

# Only Anthropic models
praisonai models list --provider anthropic

# Models containing "flash"
praisonai models list flash

# JSON output for scripting / CI
praisonai models list --json
```

### `praisonai models describe <model>`

Show full metadata for one model, including capabilities, limits, and cost.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai models describe <MODEL_ID>
```

**Examples:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai models describe gpt-4o
praisonai models describe claude-3-5-sonnet-latest
praisonai models describe gemini-1.5-pro
```

### `praisonai models validate <model>`

Validate a model ID. Exits with code `1` and shows close matches if the ID is unknown.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai models validate <MODEL_ID>
```

**Examples:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Valid ID
praisonai models validate gpt-4o

# Deliberate typo — shows suggestions
praisonai models validate cluade-3-opus
```

**When to use which command:**

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Q{What do you need?} --> A[Browse available models]
    Q --> B[I have a model ID]
    Q --> C[My YAML/config rejected an ID]

    A --> L[praisonai models list\noptionally filter by provider/search]
    B --> D[praisonai models describe ID\nfull capabilities + cost]
    C --> V[praisonai models validate ID\ngets suggestions on typo]

    classDef question fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef action fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef cmd fill:#10B981,stroke:#7C90A0,color:#fff

    class Q question
    class A,B,C action
    class L,D,V cmd
```

## Capabilities & Limits Reference

Every model in the catalogue exposes these fields:

| Field                | Type    | Default | Description                                                    |
| -------------------- | ------- | ------- | -------------------------------------------------------------- |
| `id`                 | `str`   | —       | Model identifier (e.g. `gpt-4o`)                               |
| `provider`           | `str`   | —       | `openai`, `anthropic`, `google`, `groq`, `ollama`, `cohere`, … |
| `description`        | `str`   | `None`  | Short human description                                        |
| `max_context`        | `int`   | `None`  | Max context window (tokens)                                    |
| `max_output`         | `int`   | `None`  | Max output tokens                                              |
| `input_cost`         | `float` | `None`  | Cost per 1K input tokens (USD)                                 |
| `output_cost`        | `float` | `None`  | Cost per 1K output tokens (USD)                                |
| `supports_tools`     | `bool`  | `False` | Tool-calling support                                           |
| `supports_vision`    | `bool`  | `False` | Image input support                                            |
| `supports_reasoning` | `bool`  | `False` | Reasoning-class model                                          |
| `supports_streaming` | `bool`  | `True`  | Token streaming                                                |
| `notes`              | `str`   | `None`  | Caveats (e.g. "Requires Ollama running locally")               |

## Configuration Options

`ModelCatalogue` accepts two constructor arguments:

| Option      | Type           | Default            | Description                        |
| ----------- | -------------- | ------------------ | ---------------------------------- |
| `cache_dir` | `Path \| None` | `~/.praison/cache` | Directory for the model cache file |
| `cache_ttl` | `int`          | `3600`             | Cache TTL in seconds (1 hour)      |

**Import paths:**

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# New canonical import (works with pip install praisonai-code alone)
from praisonai_code.llm.catalogue import ModelCatalogue

# Legacy path still works — same object via a PEP 562 / sys.modules shim
from praisonai.llm.catalogue import ModelCatalogue
```

Both paths resolve to the same class object; you don't have to migrate existing code. The unit test `test_c5_backward_compat.py::test_module_identity` asserts `praisonai.llm.catalogue is praisonai_code.llm.catalogue`.

**Cache file location:** `~/.praison/cache/models.json`

**Force refresh:** delete the cache file, then run any `praisonai models` command:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
rm ~/.praison/cache/models.json
praisonai models list
```

## Validation Behaviour

<Note>
  * **YAML local aliases** — if your YAML file defines model aliases under a top-level `models:` key, those aliases are accepted even when absent from the catalogue.
  * **Tool-compatibility warnings** — if an agent has `tools:` configured but its `llm` does not advertise `supports_tools` (e.g. `o1`, `o1-mini`), a warning is emitted at load time.
  * **Opt-out** — pass `validate_model=False` to `resolve_llm_endpoint` (or `resolve_llm_endpoint_with_credentials`) to skip validation entirely and make the call unconditionally.
</Note>

## Best Practices

<AccordionGroup>
  <Accordion title="Install litellm for the full catalogue">
    The static fallback covers \~15 models. Installing `litellm` unlocks 100+ models with live pricing data:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install 'praisonai[litellm]'
    ```
  </Accordion>

  <Accordion title="Refresh the cache when providers release new models">
    The cache is valid for 1 hour. To pull the latest model list immediately:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    rm ~/.praison/cache/models.json
    praisonai models list
    ```
  </Accordion>

  <Accordion title="Use --json in CI to pin your model selection">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai models list --provider openai --json | jq '.[].id'
    ```

    Parse the JSON output in scripts or pipelines to programmatically choose a model.
  </Accordion>

  <Accordion title="Pick a tool-calling model when your agent uses tools">
    Before adding `tools:` to an agent, verify the model supports them:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai models describe gpt-4o
    # Look for: Tool calling: ✅
    ```

    Models like `o1` and `o1-mini` do **not** support tool calling.
  </Accordion>
</AccordionGroup>

## Offline / Fallback Behaviour

When `litellm` is not installed or the network is unavailable, the catalogue degrades gracefully to a curated static list covering:

* **OpenAI** — `gpt-4o`, `gpt-4o-mini`, `gpt-3.5-turbo`, `o1`, `o1-mini`
* **Anthropic** — `claude-3-5-sonnet-latest`, `claude-3-5-haiku-latest`, `claude-3-opus-latest`
* **Google** — `gemini-1.5-pro`, `gemini-1.5-flash`, `gemini-2.0-flash-exp`
* **Groq** — `llama-3.3-70b-versatile`, `mixtral-8x7b-32768`
* **Ollama** — `llama3.2` (requires Ollama running locally)

All three CLI commands (`list`, `describe`, `validate`) work against the static list without any external calls.

## Related

<CardGroup cols={2}>
  <Card title="Standalone LLM Modules" icon="plug" href="/docs/features/standalone-llm-modules">
    All four LLM modules available without the wrapper package
  </Card>

  <Card title="AutoGen Config List" icon="list-tree" href="/docs/features/llm-autogen-config-list">
    Build AutoGen config\_list from the resolved endpoint
  </Card>

  <Card title="LLM Endpoint Config" icon="plug" href="/docs/features/llm-endpoint-config">
    Configure model and base URL via environment variables
  </Card>

  <Card title="Model Capabilities" icon="microchip" href="/docs/features/model-capabilities">
    Model capability flags and how to use them
  </Card>
</CardGroup>

*C7 note: As of PR #2550, the tool-discovery pipeline (`tool_resolver`), safe loader (`_safe_loader`), framework probes (`_framework_availability`), and plugin registry (`tool_registry`) all live in `praisonai_code` — the same C7 arc that moved LLM config here. See [Tool Discovery Order](/docs/features/tool-discovery-order) and [Local Tools Loading](/docs/features/local-tools-loading).*