Model Catalogue

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.

Quick Start

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:

# 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:

praisonai models list

Filter to a single provider:

praisonai models list --provider openai

Search by name substring:

praisonai models list gpt

Inspect a model

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

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:

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:

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:

'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:

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]'

models validate confirms the model is in LiteLLM’s chat/cost catalogue — it does not probe modality-specific backends. A model id can pass models validate and still fail inside VideoAgent or ImageAgent because the modality-specific backend is missing. VideoAgent surfaces this as a clear ValueError with supported alternatives (see Video Overview → Supported models).

Agent-Centric Example

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

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:

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.

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.

How It Works

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.

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:

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: 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.

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:

# 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.

praisonai models describe <MODEL_ID>

Examples:

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.

praisonai models validate <MODEL_ID>

Examples:

# 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.

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:

# 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:

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:

# 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:

praisonai models refresh

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

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.

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

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.

Best Practices

Install litellm for the full catalogue

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

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:

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:

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

Use --json in CI to pin your model selection

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:

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.

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

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

Standalone LLM Modules

AutoGen Config List

LLM Endpoint Config

Model Capabilities

​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

Standalone LLM Modules

AutoGen Config List

LLM Endpoint Config

Model Capabilities

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