ai-model-registry 0.1.1
Single source of truth for AI model availability
Requires Python: >=3.8
Keywords: ai, anthropic, llm, models, openai, registry

# AI Model Registry

**Your single source of truth for AI model IDs across all major providers.**

Stop your code from breaking when AI providers update, rename, or deprecate models. AI Model Registry tracks the latest model IDs so your applications and agents stay up-to-date automatically.

[![Python Package](https://img.shields.io/badge/pip-ai--model--registry-blue)](https://pypi.org/project/ai-model-registry/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## 🎯 Why AI Model Registry?

AI providers constantly update their models:
- ✅ **New models** released (GPT-4o, Claude Sonnet 4, Gemini 2.0)
- ⚠️ **Models renamed** (gpt-4-turbo-preview → gpt-4-turbo)
- 🔄 **Models deprecated** (gpt-3.5-turbo → gpt-4o-mini)
- 📅 **Model IDs change** (claude-3-opus-20240229 → claude-opus-4-20250514)

**Without AI Model Registry:**
- ❌ Your code breaks when providers update model IDs
- ❌ You manually track which models are available
- ❌ You hardcode model IDs that become outdated
- ❌ Your AI agents use deprecated models

**With AI Model Registry:**
- ✅ Always use the latest recommended model IDs
- ✅ Get notified when models are deprecated
- ✅ Track model status (active, legacy, deprecated)
- ✅ Prevent breaking changes in production

---

## 🚀 Quick Start

### Installation

#### Python Package
```bash
pip install ai-model-registry
```

#### REST API
No installation needed! Use the REST API directly:
```bash
curl https://ai-model-registry.vercel.app/latest/openai
```

---

## 📦 Usage

### Python Package

```python
from ai_model_registry import get_latest_model, get_all_models

# Get the recommended model for a provider
model = get_latest_model("anthropic")
print(model)  # claude-sonnet-4-20250514

# Get all models with status
models = get_all_models(provider="openai", status="active")
```

### REST API

```bash
# Get recommended model for a provider
curl https://ai-model-registry.vercel.app/latest/anthropic

# Get all models
curl https://ai-model-registry.vercel.app/models

# Get OpenAI models only
curl https://ai-model-registry.vercel.app/models?provider=openai

# Get only active models
curl https://ai-model-registry.vercel.app/models?status=active

# Get specific model details
curl https://ai-model-registry.vercel.app/models/openai/gpt-4o
```

---

## 🌐 API Endpoints

| Endpoint | Description |
|----------|-------------|
| `GET /` | API info and available endpoints |
| `GET /providers` | List all supported providers |
| `GET /models` | Get all models (optional: `?provider=` `?status=`) |
| `GET /models/{provider}/{model_id}` | Get specific model details |
| `GET /latest/{provider}` | Get recommended model for provider |
| `GET /health` | Health check |

### Response Example

```json
{
  "provider": "anthropic",
  "model_id": "claude-sonnet-4-20250514",
  "status": "active",
  "context": 200000,
  "updated": "2025-01-24"
}
```

### Status Values

| Status | Description |
|--------|-------------|
| `active` | Current, recommended for use |
| `legacy` | Still works, but newer version available |
| `deprecated` | Will be removed soon |

---

## 🎨 Supported Providers

- **OpenAI** - GPT-4o, GPT-4 Turbo, o1, o3-mini
- **Anthropic** - Claude 4 (Opus, Sonnet, Haiku)
- **Google** - Gemini 2.0 Flash, Gemini 1.5 Pro
- **Mistral** - Mistral Large, Codestral
- **Groq** - Llama 3.3, Mixtral

---

## 🎯 Integration with Cursor AI

### Setup .cursorrules for Your Project

Create a `.cursorrules` file in your project root to ensure Cursor AI always uses the latest model IDs:

```
# AI Model Registry Integration
# This ensures all AI API calls use current model IDs

Before writing any code that calls AI provider APIs (OpenAI, Anthropic, Google, Mistral, Groq):
1. Check ai-model-registry for the latest model IDs
2. Use: curl https://ai-model-registry.vercel.app/latest/{provider}
3. Never hardcode model IDs - always verify they are current

Providers to check:
- OpenAI: https://ai-model-registry.vercel.app/latest/openai
- Anthropic: https://ai-model-registry.vercel.app/latest/anthropic
- Google: https://ai-model-registry.vercel.app/latest/google
- Mistral: https://ai-model-registry.vercel.app/latest/mistral
- Groq: https://ai-model-registry.vercel.app/latest/groq
```

### 🌟 Pro Tip: Website Integration

**Add to your documentation site or developer portal:**

Create a button: **"Generate .cursorrules for my project"**

This button generates a `.cursorrules` file that:
- Automatically configures Cursor AI to check AI Model Registry
- Ensures developers always use current model IDs
- Prevents API errors from deprecated models
- Works across all AI providers

**Example Implementation:**
```javascript
// When button clicked, generate and download .cursorrules file
function generateCursorRules() {
  const content = `# AI Model Registry Integration
Before writing code with AI APIs, check: https://ai-model-registry.vercel.app/latest/{provider}`;
  
  const blob = new Blob([content], { type: 'text/plain' });
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = '.cursorrules';
  a.click();
}
```

---

## 🔧 Development

### Run Locally

```bash
# Clone the repository
git clone https://github.com/Venkatesh188/ai_model_registry.git
cd ai_model_registry

# Install dependencies
pip install -r requirements.txt

# Run the API
uvicorn api.index:app --reload
```

Open `http://localhost:8000/docs` for interactive API documentation (Swagger UI).

---

## 🤝 Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

**How to contribute:**
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

**What to contribute:**
- Add new AI providers (Cohere, Perplexity, etc.)
- Update model information (new releases, deprecations)
- Improve documentation
- Add client libraries (JavaScript, Go, Rust, etc.)

---

## 📄 License

MIT - See [LICENSE](LICENSE) for details.

---

## 🔗 Links

- **PyPI Package:** [ai-model-registry](https://pypi.org/project/ai-model-registry/)
- **REST API:** [https://ai-model-registry.vercel.app/](https://ai-model-registry.vercel.app/)
- **GitHub:** [Venkatesh188/ai_model_registry](https://github.com/Venkatesh188/ai_model_registry)
- **Issues:** [Report a bug or request a feature](https://github.com/Venkatesh188/ai_model_registry/issues)

---

**Made with ❤️ for the AI developer community**