OpenAI Model Registry

A Python package that provides information about OpenAI models and validates parameters before API calls.

📚 View the Documentation 🤖 AI Assistant Documentation - LLM-optimized reference following llmstxt.org

Why Use OpenAI Model Registry?

OpenAI's models have different context-window sizes, parameter ranges, and feature support. If you guess wrong, the API returns an error—often in production.

OpenAI Model Registry keeps an up-to-date, local catalog of every model's limits and capabilities, letting you validate calls before you send them.

Typical benefits:

• Catch invalid temperature, top_p, and max_tokens values locally.
• Swap models confidently by comparing context windows and features.
• Work fully offline—perfect for CI or air-gapped environments.

What This Package Does

• Helps you avoid invalid API calls by validating parameters ahead of time
• Provides accurate information about model capabilities (context windows, token limits)
• Handles model aliases and different model versions
• Works offline with locally stored model information
• Keeps model information up-to-date with optional updates
• Programmatic model cards: structured access to each model's capabilities, parameters, pricing (including per-image tiers), and deprecation metadata (OpenAI and Azure providers)
• Coverage and freshness: includes all OpenAI models as of 2025-08-16; pricing and data are kept current automatically via CI using ostruct

Installation

Core Library (Recommended)

bash pip install openai-model-registry

With CLI Tools

bash pip install openai-model-registry[cli]

The core library provides all programmatic functionality. Add the [cli] extra if you want to use the omr command-line tools.

💡 Which installation should I choose?

• Core only (pip install openai-model-registry) - Perfect for programmatic use in applications, scripts, or libraries
• With CLI (pip install openai-model-registry[cli]) - Adds command-line tools for interactive exploration and debugging

Simple Example

```python from openaimodelregistry import ModelRegistry

Get information about a model

registry = ModelRegistry.getdefault() model = registry.getcapabilities("gpt-4o")

Access model limits

print(f"Context window: {model.contextwindow} tokens") print(f"Max output: {model.maxoutput_tokens} tokens")

Expected output: Context window: 128000 tokens

Max output: 16384 tokens

Check if parameter values are valid

model.validateparameter("temperature", 0.7) # Valid - no error try: model.validateparameter("temperature", 3.0) # Invalid - raises ValueError except ValueError as e: print(f"Error: {e}")

Expected output: Error: Parameter 'temperature' must be between 0 and 2...

Check model features

if model.supports_structured: print("This model supports Structured Output")

Expected output: This model supports Structured Output

```

➡️ Keeping it fresh: run openai-model-registry-update (CLI) or registry.refresh_from_remote() whenever OpenAI ships new models.

🔵 Azure OpenAI Users: If you're using Azure OpenAI endpoints, be aware of platform-specific limitations, especially for web search capabilities. See our Azure OpenAI documentation for guidance.

Practical Use Cases

Validating Parameters Before API Calls

```python import openai from openaimodelregistry import ModelRegistry

Initialize registry and client

registry = ModelRegistry.getdefault() client = openai.OpenAI() # Requires OPENAIAPI_KEY environment variable

def callopenai(model, messages, **params): # Validate parameters before making API call capabilities = registry.getcapabilities(model) for paramname, value in params.items(): capabilities.validateparameter(param_name, value)

# Now make the API call
return client.chat.completions.create(model=model, messages=messages, **params)

Example usage

messages = [{"role": "user", "content": "Hello!"}] response = callopenai("gpt-4o", messages, temperature=0.7, maxtokens=100)

Expected output: Successful API call with validated parameters

```

Managing Token Limits

```python from openaimodelregistry import ModelRegistry

Initialize registry

registry = ModelRegistry.get_default()

def truncateprompt(prompt, maxtokens): """Simple truncation function (you'd implement proper tokenization)""" # This is a simplified example - use tiktoken for real tokenization words = prompt.split() if len(words) <= maxtokens: return prompt return " ".join(words[:maxtokens])

def prepareprompt(modelname, prompt, maxoutput=None): capabilities = registry.getcapabilities(model_name)

# Use model's max output if not specified
max_output = max_output or capabilities.max_output_tokens

# Calculate available tokens for input
available_tokens = capabilities.context_window - max_output

# Ensure prompt fits within available tokens
return truncate_prompt(prompt, available_tokens)

Example usage

longprompt = "This is a very long prompt that might exceed token limits..." safeprompt = prepareprompt("gpt-4o", longprompt, max_output=1000)

Expected output: Truncated prompt that fits within token limits

```

Key Features

• Model Information: Get context window size, token limits, and supported features
• Parameter Validation: Check if parameter values are valid for specific models
• Version Support: Works with date-based models (e.g., "o3-mini-2025-01-31")
• Offline Usage: Functions without internet using local registry data
• Updates: Optional updates to keep model information current

Command Line Usage

OMR CLI

The omr CLI provides comprehensive tools for inspecting and managing your model registry.

Note: CLI tools require the [cli] extra: pip install openai-model-registry[cli]

```bash

List all models

omr models list

Show data source paths

omr data paths

Check for updates

omr update check

Get detailed model info

omr models get gpt-4o ```

See the CLI Reference for complete documentation.

Note on updates: omr update apply and omr update refresh write updated data files to your user data directory by default (or OMR_DATA_DIR if set). The OMR_MODEL_REGISTRY_PATH environment variable is a read-only override for loading models.yaml and is never modified by update commands.

Legacy Update Command

Update your local registry data:

bash openai-model-registry-update

Configuration

The registry uses local files for model information:

```text

Default locations (XDG Base Directory spec)

Linux: ~/.local/share/openai-model-registry/ macOS: ~/Library/Application Support/openai-model-registry/ Windows: %LOCALAPPDATA%\openai-model-registry\ ```

You can specify custom locations:

```python import os

Use custom registry files

os.environ["OMRMODELREGISTRYPATH"] = "/path/to/custom/models.yaml" os.environ["OMRPARAMETERCONSTRAINTSPATH"] = ( "/path/to/custom/parameter_constraints.yml" )

Then initialize registry

from openaimodelregistry import ModelRegistry

registry = ModelRegistry.get_default() ```

Environment variables

text OMR_DATA_DIR # Override user data dir where updates are written OMR_MODEL_REGISTRY_PATH # Read-only override for models.yaml load path OMR_DISABLE_DATA_UPDATES # Set to 1/true to disable automatic data update checks

Documentation

For more details, see:

• Getting Started Guide
• API Reference
• Examples
• ostruct pricing automation

Development

```bash

Install dependencies with CLI tools (requires Poetry)

poetry install --extras cli

Run tests

poetry run pytest

Run linting

poetry run pre-commit run --all-files ```

Next Steps

• 📚 Examples – real-world scripts in examples/.
• 🤝 Contributing – see CONTRIBUTING.md.
• 📝 Changelog – see CHANGELOG.md for recent updates.

Contributing

We 💜 external contributions! Start with CONTRIBUTING.md and our Code of Conduct.

Need Help?

Open an issue or start a discussion—questions, ideas, and feedback are welcome!

License

MIT License - See LICENSE for details.