Model Catalogue

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

python

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.

Diagram

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

# Works with pip install praisonai-code only
praisonai models list
praisonai models describe gpt-4o
praisonai models validate gpt-4o-mini

Browse all models
List every available model grouped by provider:
bash
```
praisonai models list
```
Filter to a single provider:
bash
```
praisonai models list --provider openai
```
Search by name substring:
bash
```
praisonai models list gpt
```

Inspect a model

Get full capabilities, limits, and cost for one model:

bash

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

On a non-UTF-8 terminal (Windows cp1252, redirected pipes), the same command prints ASCII labels instead of emoji:

text

Model: gpt-4o
Provider: openai

Capabilities:
  - Tool calling: yes
  - Vision: yes
  - Reasoning: yes
  - Streaming: yes

Validate a model ID

Check whether an ID is valid — and get suggestions on a typo:

bash

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

On a non-UTF-8 terminal the same checks drop the emoji markers:

text

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

Refresh the catalogue
Rebuild the capability cache now, bypassing the 1 h TTL, so a newly released flagship is recognised without upgrading litellm:
bash
```
praisonai models refresh
praisonai models refresh --json
```
Success output:
```
Refreshed catalogue: 128 models cached
```
When litellm is not installed, the built-in table is shown and the cache is not rewritten:
```
litellm unavailable — showing 15 built-in models; cache not updated. Install litellm to refresh: pip install 'praisonai[litellm]'
```

Agent-Centric Example

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

python

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

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.

How It Works

Diagram

Data sources — priority order:

Source	When used	What it provides
`~/.praisonai/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

Encoding-aware Output

As of PraisonAI PR #3661, the models subcommands render ASCII labels on any terminal whose stdout cannot encode emoji (Windows cp1252/cp850, redirected pipes, minimal SSH sessions). UTF-8 terminals still get the emoji output shown above.

Diagram

Subcommand	UTF-8 stdout	Non-UTF-8 stdout (cp1252, redirected pipes, SSH)
`models list` capability column	`🔧 tools 👁️ vision 🧠 reasoning`	`tools vision reasoning`
`models describe` capabilities section	`- Tool calling: ✅ / ❌`	`- Tool calling: yes / no`
`models validate` success marker	`✅ '<id>' is a valid model`	`'<id>' is a valid model`
`models validate` failure marker	`❌ '<id>' is not a valid model`	`'<id>' is not a valid model`
`--json` output	unchanged	unchanged

The probe encodes "\U0001f527" in sys.stdout.encoding; a UnicodeEncodeError or LookupError triggers the ASCII fallback. The probe is automatic — there is no flag, environment variable, or config toggle. On legacy Windows consoles, opt back into emoji with chcp 65001.

Extend downstream commands with the same probe:

python

from praisonai_code.cli.output.console import stdout_supports_unicode

yes, no = ("✅", "❌") if stdout_supports_unicode() else ("yes", "no")
print(f"Tool calling: {yes}")

Pick the output that fits where you run:

Diagram

When rich is not installed, models list renders a plain-text table via the same encoding-aware helper, so ASCII labels apply there too.

Commands Reference

`praisonai models list`

List available models, grouped by provider.

bash

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

# 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

praisonai models describe <MODEL_ID>

Examples:

bash

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

praisonai models validate <MODEL_ID>

Examples:

bash

# Valid ID
praisonai models validate gpt-4o

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

`praisonai models refresh`

Rebuild the capability cache now, bypassing the 1 h TTL, so a newly released flagship model is recognised without upgrading litellm.

bash

praisonai models refresh [OPTIONS]

Flag	Type	Description
`--json`	`bool`	Output the refreshed model list as JSON

The on-disk cache is only rewritten when litellm data loaded successfully. If litellm is unavailable, the built-in fallback table is returned and no cache file is written — the command never claims a refresh that did not happen.

Examples:

bash

# Force a fresh capability catalogue from litellm
praisonai models refresh

# Refreshed list as JSON for scripting
praisonai models refresh --json

When to use which command:

Diagram

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`	`~/.praisonai/cache`	Directory for the model cache file (honours `PRAISONAI_HOME`)
`cache_ttl`	`int`	`3600`	Cache TTL in seconds (1 hour)

Import paths:

python

# 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: ~/.praisonai/cache/models.json (honours PRAISONAI_HOME)

Force refresh: prefer the dedicated command, which rebuilds the cache in place:

bash

praisonai models refresh

If litellm is not installed, delete the cache file and re-run any praisonai models command instead:

bash

rm ~/.praisonai/cache/models.json
praisonai models list

Python helpers: ModelCatalogue exposes three public helpers for the same ranking and refresh the CLI uses. The authoritative parameter list lives in the auto-generated SDK docs.

python

from praisonai_code.llm.catalogue import ModelCatalogue

cat = ModelCatalogue()
cat.rank_models(provider="openai")   # ordered best-first
cat.best_available("openai")          # top id for a provider
cat.refresh()                          # {"cached": bool, "models": [...]}

Validation Behaviour

Best Practices

Install litellm for the full catalogue

The static fallback covers ~15 models. Installing litellm unlocks 100+ models with live pricing data:

bash

pip install 'praisonai[litellm]'

Refresh the cache when providers release new models

The cache is valid for 1 hour. To pull the latest model list immediately:

bash

praisonai models refresh

The cache is rewritten only when litellm data loaded. Without litellm installed, delete the cache file and re-run a models command instead:

bash

rm ~/.praisonai/cache/models.json
praisonai models list

Use –json in CI to pin your model selection

bash

praisonai models list --provider openai --json | jq '.[].id'

Parse the JSON output in scripts or pipelines to programmatically choose a model.

Pick a tool-calling model when your agent uses tools

Before adding tools: to an agent, verify the model supports them:

bash

praisonai models describe gpt-4o
# Look for: Tool calling: ✅

Models like o1 and o1-mini do not support tool calling.

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.

Standalone LLM Modules

All four LLM modules available without the wrapper package

AutoGen Config List

Build AutoGen config_list from the resolved endpoint

LLM Endpoint Config

Configure model and base URL via environment variables

Model Capabilities

Model capability flags and how to use them

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 and Local Tools Loading.

Model Catalogue

Quick Start

Agent-Centric Example

How It Works

Encoding-aware Output

Commands Reference

praisonai models list

praisonai models describe <model>

praisonai models validate <model>

praisonai models refresh

Capabilities & Limits Reference

Configuration Options

Validation Behaviour

Best Practices

Offline / Fallback Behaviour

Related

`praisonai models list`

`praisonai models describe <model>`

`praisonai models validate <model>`

`praisonai models refresh`