{"id":26562919,"url":"https://github.com/yaniv-golan/openai-model-registry","last_synced_at":"2026-04-29T11:03:36.046Z","repository":{"id":282636315,"uuid":"949205435","full_name":"yaniv-golan/openai-model-registry","owner":"yaniv-golan","description":"🤖 Production-ready Python registry for OpenAI models with parameter validation, pricing data, and CLI tools. Supports GPT-5, Azure OpenAI, automated updates, and enterprise deployment.","archived":false,"fork":false,"pushed_at":"2025-09-22T06:28:21.000Z","size":1438,"stargazers_count":0,"open_issues_count":15,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-25T01:55:29.587Z","etag":null,"topics":["cost-optimization","gpt-5","gpt-5-api","gpt-models","model-cards","model-metadata","openai","openai-api","openai-api-azure","openai-api-client","openai-api-python","parameter-validation","pricing-billing"],"latest_commit_sha":null,"homepage":"https://yaniv-golan.github.io/openai-model-registry/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yaniv-golan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-15T22:55:01.000Z","updated_at":"2025-08-16T17:38:43.000Z","dependencies_parsed_at":"2025-08-13T23:21:01.599Z","dependency_job_id":"a9b710db-6f4a-4595-986c-f57a6516b2d2","html_url":"https://github.com/yaniv-golan/openai-model-registry","commit_stats":null,"previous_names":["yaniv-golan/openai-model-registry"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/yaniv-golan/openai-model-registry","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yaniv-golan%2Fopenai-model-registry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yaniv-golan%2Fopenai-model-registry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yaniv-golan%2Fopenai-model-registry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yaniv-golan%2Fopenai-model-registry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yaniv-golan","download_url":"https://codeload.github.com/yaniv-golan/openai-model-registry/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yaniv-golan%2Fopenai-model-registry/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32422540,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T06:29:02.080Z","status":"ssl_error","status_checked_at":"2026-04-29T06:29:00.631Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cost-optimization","gpt-5","gpt-5-api","gpt-models","model-cards","model-metadata","openai","openai-api","openai-api-azure","openai-api-client","openai-api-python","parameter-validation","pricing-billing"],"created_at":"2025-03-22T15:29:15.582Z","updated_at":"2026-04-29T11:03:36.040Z","avatar_url":"https://github.com/yaniv-golan.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenAI Model Registry\n\n[![PyPI version](https://img.shields.io/pypi/v/openai-model-registry.svg)](https://pypi.org/project/openai-model-registry/)\n[![Python Versions](https://img.shields.io/pypi/pyversions/openai-model-registry.svg)](https://pypi.org/project/openai-model-registry/)\n[![CI Status](https://github.com/yaniv-golan/openai-model-registry/workflows/Python%20CI/badge.svg)](https://github.com/yaniv-golan/openai-model-registry/actions)\n[![codecov](https://codecov.io/gh/yaniv-golan/openai-model-registry/branch/main/graph/badge.svg)](https://codecov.io/gh/yaniv-golan/openai-model-registry)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA Python package that provides information about OpenAI models and validates parameters before API calls.\n\n📚 **[View the Documentation](https://yaniv-golan.github.io/openai-model-registry/)**\n🤖 **[AI Assistant Documentation](llms.txt)** - LLM-optimized reference following [llmstxt.org](https://llmstxt.org/)\n\n## Why Use OpenAI Model Registry?\n\nOpenAI's models have different context-window sizes, parameter ranges, and feature support. If you guess wrong, the API returns an error—often in production.\n\n**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.**\n\nTypical benefits:\n\n- Catch invalid `temperature`, `top_p`, and `max_tokens` values locally.\n- Swap models confidently by comparing context windows and features.\n- Work fully offline—perfect for CI or air-gapped environments.\n\n## What This Package Does\n\n- Helps you avoid invalid API calls by validating parameters ahead of time\n- Provides accurate information about model capabilities (context windows, token limits)\n- Handles model aliases and different model versions\n- Works offline with locally stored model information\n- Keeps model information up-to-date with optional updates\n- Programmatic model cards: structured access to each model's capabilities, parameters, pricing (including per-image tiers), and deprecation metadata (OpenAI and Azure providers)\n- Coverage and freshness: includes all OpenAI models as of 2025-08-16; pricing and data are kept current automatically via CI using [ostruct](https://github.com/yaniv-golan/ostruct)\n\n## Installation\n\n### Core Library (Recommended)\n\n```bash\npip install openai-model-registry\n```\n\n### With CLI Tools\n\n```bash\npip install openai-model-registry[cli]\n```\n\nThe core library provides all programmatic functionality. Add the `[cli]` extra if you want to use the `omr` command-line tools.\n\n\u003e **💡 Which installation should I choose?**\n\u003e\n\u003e - **Core only** (`pip install openai-model-registry`) - Perfect for programmatic use in applications, scripts, or libraries\n\u003e - **With CLI** (`pip install openai-model-registry[cli]`) - Adds command-line tools for interactive exploration and debugging\n\n## Simple Example\n\n```python\nfrom openai_model_registry import ModelRegistry\n\n# Get information about a model\nregistry = ModelRegistry.get_default()\nmodel = registry.get_capabilities(\"gpt-4o\")\n\n# Access model limits\nprint(f\"Context window: {model.context_window} tokens\")\nprint(f\"Max output: {model.max_output_tokens} tokens\")\n# Expected output: Context window: 128000 tokens\n#                  Max output: 16384 tokens\n\n# Check if parameter values are valid\nmodel.validate_parameter(\"temperature\", 0.7)  # Valid - no error\ntry:\n    model.validate_parameter(\"temperature\", 3.0)  # Invalid - raises ValueError\nexcept ValueError as e:\n    print(f\"Error: {e}\")\n# Expected output: Error: Parameter 'temperature' must be between 0 and 2...\n\n# Check model features\nif model.supports_structured:\n    print(\"This model supports Structured Output\")\n# Expected output: This model supports Structured Output\n```\n\n➡️ **Keeping it fresh:** run `openai-model-registry-update` (CLI) or `registry.refresh_from_remote()` whenever OpenAI ships new models.\n\n\u003e **🔵 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](docs/user-guide/azure-openai.md) for guidance.\n\n## Practical Use Cases\n\n### Validating Parameters Before API Calls\n\n```python\nimport openai\nfrom openai_model_registry import ModelRegistry\n\n# Initialize registry and client\nregistry = ModelRegistry.get_default()\nclient = openai.OpenAI()  # Requires OPENAI_API_KEY environment variable\n\ndef call_openai(model, messages, **params):\n    # Validate parameters before making API call\n    capabilities = registry.get_capabilities(model)\n    for param_name, value in params.items():\n        capabilities.validate_parameter(param_name, value)\n\n    # Now make the API call\n    return client.chat.completions.create(model=model, messages=messages, **params)\n\n# Example usage\nmessages = [{\"role\": \"user\", \"content\": \"Hello!\"}]\nresponse = call_openai(\"gpt-4o\", messages, temperature=0.7, max_tokens=100)\n# Expected output: Successful API call with validated parameters\n```\n\n### Managing Token Limits\n\n```python\nfrom openai_model_registry import ModelRegistry\n\n# Initialize registry\nregistry = ModelRegistry.get_default()\n\n\ndef truncate_prompt(prompt, max_tokens):\n    \"\"\"Simple truncation function (you'd implement proper tokenization)\"\"\"\n    # This is a simplified example - use tiktoken for real tokenization\n    words = prompt.split()\n    if len(words) \u003c= max_tokens:\n        return prompt\n    return \" \".join(words[:max_tokens])\n\n\ndef prepare_prompt(model_name, prompt, max_output=None):\n    capabilities = registry.get_capabilities(model_name)\n\n    # Use model's max output if not specified\n    max_output = max_output or capabilities.max_output_tokens\n\n    # Calculate available tokens for input\n    available_tokens = capabilities.context_window - max_output\n\n    # Ensure prompt fits within available tokens\n    return truncate_prompt(prompt, available_tokens)\n\n\n# Example usage\nlong_prompt = \"This is a very long prompt that might exceed token limits...\"\nsafe_prompt = prepare_prompt(\"gpt-4o\", long_prompt, max_output=1000)\n# Expected output: Truncated prompt that fits within token limits\n```\n\n## Key Features\n\n- **Model Information**: Get context window size, token limits, and supported features\n- **Parameter Validation**: Check if parameter values are valid for specific models\n- **Version Support**: Works with date-based models (e.g., \"o3-mini-2025-01-31\")\n- **Offline Usage**: Functions without internet using local registry data\n- **Updates**: Optional updates to keep model information current\n\n## Command Line Usage\n\n### OMR CLI\n\nThe `omr` CLI provides comprehensive tools for inspecting and managing your model registry.\n\n**Note:** CLI tools require the `[cli]` extra: `pip install openai-model-registry[cli]`\n\n```bash\n# List all models\nomr models list\n\n# Show data source paths\nomr data paths\n\n# Check for updates\nomr update check\n\n# Get detailed model info\nomr models get gpt-4o\n```\n\nSee the [CLI Reference](docs/user-guide/cli.md) for complete documentation.\n\n\u003e 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.\n\n### Legacy Update Command\n\nUpdate your local registry data:\n\n```bash\nopenai-model-registry-update\n```\n\n## Configuration\n\nThe registry uses local files for model information:\n\n```text\n# Default locations (XDG Base Directory spec)\nLinux: ~/.local/share/openai-model-registry/\nmacOS: ~/Library/Application Support/openai-model-registry/\nWindows: %LOCALAPPDATA%\\openai-model-registry\\\n```\n\nYou can specify custom locations:\n\n```python\nimport os\n\n# Use custom registry files\nos.environ[\"OMR_MODEL_REGISTRY_PATH\"] = \"/path/to/custom/models.yaml\"\nos.environ[\"OMR_PARAMETER_CONSTRAINTS_PATH\"] = (\n    \"/path/to/custom/parameter_constraints.yml\"\n)\n\n# Then initialize registry\nfrom openai_model_registry import ModelRegistry\n\nregistry = ModelRegistry.get_default()\n```\n\n### Environment variables\n\n```text\nOMR_DATA_DIR                # Override user data dir where updates are written\nOMR_MODEL_REGISTRY_PATH     # Read-only override for models.yaml load path\nOMR_DISABLE_DATA_UPDATES    # Set to 1/true to disable automatic data update checks\n```\n\n## Documentation\n\nFor more details, see:\n\n- [Getting Started Guide](https://yaniv-golan.github.io/openai-model-registry/user-guide/getting-started/)\n- [API Reference](https://yaniv-golan.github.io/openai-model-registry/api/)\n- [Examples](./examples/)\n- [ostruct pricing automation](scripts/ostruct/README.md)\n\n## Development\n\n```bash\n# Install dependencies with CLI tools (requires Poetry)\npoetry install --extras cli\n\n# Run tests\npoetry run pytest\n\n# Run linting\npoetry run pre-commit run --all-files\n```\n\n## Next Steps\n\n- 📚 **Examples** – real-world scripts in [`examples/`](examples).\n- 🤝 **Contributing** – see [CONTRIBUTING.md](CONTRIBUTING.md).\n- 📝 **Changelog** – see [CHANGELOG.md](CHANGELOG.md) for recent updates.\n\n## Contributing\n\nWe 💜 external contributions! Start with [CONTRIBUTING.md](CONTRIBUTING.md) and our Code of Conduct.\n\n## Need Help?\n\nOpen an [issue](../../issues) or start a discussion—questions, ideas, and feedback are welcome!\n\n## License\n\nMIT License - See [LICENSE](./LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyaniv-golan%2Fopenai-model-registry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyaniv-golan%2Fopenai-model-registry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyaniv-golan%2Fopenai-model-registry/lists"}