Skip to main content
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
1

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
2

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
3

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

​
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:
SourceWhen usedWhat it provides
~/.praison/cache/models.jsonCache < 1 h oldFull list saved from previous live call
litellm (model_list + model_cost)Cache miss, litellm installedLive data: 100+ models with cost & limits
Curated static listlitellm unavailable / errorOpenAI, Anthropic, Google, Groq, Ollama

​
Commands Reference

​
praisonai models list

List available models, grouped by provider. 
praisonai models list [SEARCH] [OPTIONS]
Flag / ArgumentTypeDescription
searchstr (positional)Filter by substring in the model ID (e.g. gpt, claude)
--provider, -pstrFilter by provider (openai, anthropic, google, groq, ollama)
--jsonboolMachine-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
When to use which command:

​
Capabilities & Limits Reference

Every model in the catalogue exposes these fields:
FieldTypeDefaultDescription
idstr—Model identifier (e.g. gpt-4o)
providerstr—openai, anthropic, google, groq, ollama, cohere, …
descriptionstrNoneShort human description
max_contextintNoneMax context window (tokens)
max_outputintNoneMax output tokens
input_costfloatNoneCost per 1K input tokens (USD)
output_costfloatNoneCost per 1K output tokens (USD)
supports_toolsboolFalseTool-calling support
supports_visionboolFalseImage input support
supports_reasoningboolFalseReasoning-class model
supports_streamingboolTrueToken streaming
notesstrNoneCaveats (e.g. “Requires Ollama running locally”)

​
Configuration Options

ModelCatalogue accepts two constructor arguments:
OptionTypeDefaultDescription
cache_dirPath | None~/.praison/cacheDirectory for the model cache file
cache_ttlint3600Cache 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: ~/.praison/cache/models.json Force refresh: delete the cache file, then run any praisonai models command: 
rm ~/.praison/cache/models.json
praisonai models list

​
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

The static fallback covers ~15 models. Installing litellm unlocks 100+ models with live pricing data:
pip install 'praisonai[litellm]'
The cache is valid for 1 hour. To pull the latest model list immediately:
rm ~/.praison/cache/models.json
praisonai models list

praisonai models list --provider openai --json | jq '.[].id'
Parse the JSON output in scripts or pipelines to programmatically choose a model.
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.