Model Catalog
Relevant source files
The following files were used as context for generating this wiki page:
The Model Catalog is a centralized system within the Oh My Pi (omp) ecosystem responsible for managing Large Language Model (LLM) metadata, provider discovery, and model identity. It serves as a bundled database providing essential information such as pricing, context windows, modalities, and reasoning/thinking support for a wide variety of AI models. Sources: packages/catalog/README.md:1-5, AGENTS.md:14
This system ensures that the project can accurately identify models across different providers, handle model equivalence (collapsing provider-specific variants), and apply specific reasoning policies. It is used by the coding-agent and other packages to resolve model references and manage model-specific behaviors during runtime. Sources: packages/catalog/README.md:7-18, AGENTS.md:14
System Architecture
The Model Catalog is organized into specialized modules that handle different aspects of model management. The core of the catalog is a generated models.json file which acts as the primary database. Sources: packages/catalog/README.md:21-25
Core Components
| Module | Responsibility |
|---|---|
models | The bundled database containing pricing, context windows, and modalities. |
identity | Model ID parsing, family/version classification, and equivalence resolution. |
discovery | Runtime discovery for OpenAI-compatible, Gemini, Ollama, and other endpoints. |
model-manager | Runtime registry that handles discovery refresh and on-disk caching. |
provider-models | Provider catalog descriptors and per-provider resolution rules. |
model-thinking | Metadata and generated policies for reasoning/thinking models. |
Sources: packages/catalog/README.md:7-18
Data Flow for Model Generation
The models.json file is never edited manually. It is generated through a specific pipeline that aggregates data from upstream sources.
The diagram shows how generate-models.ts synthesizes data from external documentation, discovery services, and local overrides to produce the final bundled catalog. Sources: packages/catalog/README.md:21-30
Model Identity and Classification
The identity module is critical for normalizing model names across different providers. It performs classification based on model family and version. Sources: packages/catalog/README.md:11, AGENTS.md:158
Classification Logic
- Family/Version Parsing: Identifies the base model (e.g., GPT-4, Claude 3) regardless of the provider suffix.
- Variant Collapse: Collapses provider-specific variants of the same underlying model into a single identity to ensure consistent behavior.
- Equivalence: Determines if two model IDs from different sources represent the same capabilities.
Sources: packages/catalog/README.md:11-14, AGENTS.md:158
Provider Management
Provider management involves descriptors and resolvers that define how to interact with various AI backends. Sources: packages/catalog/README.md:8-10
Discovery and Compatibility
The catalog supports runtime discovery for several major API shapes and specific providers:
- OpenAI-compatible: Standard discovery for endpoints following the OpenAI spec.
- Specialized Providers: Native support for Gemini, Codex, Cursor, Antigravity, and Ollama.
- Compatibility Fixups: The
compatmodule handles request/response translation for OpenAI- and Anthropic-shaped APIs to ensure uniform internal processing.
Sources: packages/catalog/README.md:9-17
External Scrapers (Hugging Face)
While the core catalog is bundled, the system includes handlers for external model repositories like Hugging Face. These scrapers extract metadata directly from the web to augment model cards. Sources: packages/coding-agent/src/web/scrapers/huggingface.ts:100-140
Reasoning and Thinking Policies
The model-thinking module manages metadata for models that support reasoning or "thinking" steps. It applies generated policies that govern how these models should be treated by the agent. Sources: packages/catalog/README.md:12, AGENTS.md:158
Key elements include:
- Thinking Config: Configuration types (e.g.,
ThinkingConfig) used in model signatures. Sources: AGENTS.md:17 - Effort Levels: Definitions for reasoning effort (Low, Medium, High). Sources: packages/catalog/README.md:18, scripts/rewrite-changelog.ts:182
- Policy Application: The
applyGeneratedModelPoliciesfunction is used during the generation process to bake thinking constraints into the bundled catalog. Sources: AGENTS.md:157
Development and Maintenance
The catalog uses Bun for execution and requires Bun ≥ 1.3.14. It is designed to ship TypeScript source directly without a build step. Sources: packages/catalog/README.md:32-34
Maintenance Commands
| Task | Command |
|---|---|
| Regenerate Catalog | bun run gen:models |
| Add Dependency | bun add @oh-my-pi/pi-catalog |
Sources: packages/catalog/README.md:27-36
Implementation Guidelines
- Import Convention: Catalog values must be imported from
@oh-my-pi/pi-catalog/<module>rather than through general AI packages to avoid circularity and ensure use of the bundled database. Sources: AGENTS.md:16-20 - No Manual Edits: Any changes to
models.jsonmust be performed by updating the resolvers inprovider-models/or the generation script. Sources: packages/catalog/README.md:21-25, AGENTS.md:150-155
Summary
The Model Catalog acts as the "source of truth" for all LLM-related capabilities in the Oh My Pi project. By centralizing model metadata, reasoning policies, and provider discovery, it allows the rest of the system to remain model-agnostic while still leveraging specific features like thinking modes and optimized pricing data. Sources: packages/catalog/README.md:1-5, packages/coding-agent/DEVELOPMENT.md:46