openrouter-insights 0.6.0

Professional, unified, and enhanced index for LLM models based on OpenRouter with ArtificialAnalysis intelligence.

📊 OpenRouter Insights

OpenRouter Insights is a professional, unified LLM registry that supercharges the official OpenRouter catalog with high-fidelity intelligence and benchmarks.

It provides a "Single Source of Truth" for model capabilities, pricing, and performance, designed for production-grade AI agents and high-performance applications.

---

📖 Table of Contents

• 🔥 OpenRouter with Superpowers
• 🛠️ Installation
• 💡 Quick Start
• 🧠 Data Intelligence (Providers)
• 🕒 Data Freshness & Automation
• ✨ Smart Query Methods
• 🔄 Model Substitution
• 🧪 Verified Reliability
• 🔮 Future Roadmap
• 🤝 Contributing

---

🔥 OpenRouter with "Superpowers"

Why use this instead of the raw OpenRouter API?

Feature	Raw OpenRouter API	OpenRouter Insights
Model Catalog	✅ Yes	✅ Yes (Auto-synced)
Pricing	✅ Yes	✅ Yes (Normalized)
Intelligence Scores	❌ No	✅ Yes (ArtificialAnalysis)
Performance Tiers	❌ No	✅ Yes (Frontier/Pro/Lite)
Smart Discovery	❌ No	✅ Yes (get_smartest, get_cheapest)
Virtual Filtering	❌ No	✅ Yes (Excludes auto-routers by default)
Substitution Engine	❌ No	✅ Yes (get_best_alternative)
Fuzzy Search	❌ Limited	✅ Yes (RapidFuzz integrated)
Sync/Async Facades	❌ No	✅ Yes (Plug & Play)

---

🛠️ Installation

# Basic installation (Library only)
pip install openrouter-insights

# With API support (FastAPI + Uvicorn)
pip install "openrouter-insights[api]"

---

💡 Quick Start

⚡ Async Facade (For FastAPI / High Performance)

import asyncio
from openrouter_insights import LLMIndex

async def main():
    # Uses local JSON registry (no DB setup required)
    client = LLMIndex(mode="json")
    
    # Smart Discovery: Get the smartest model for coding
    models = await client.get_best_for_coding(limit=1)
    if models:
        print(f"Best: {models[0].name} (Score: {models[0].intelligence_score})")
        
    # NEW: Find the best substitute for GPT-4 within budget
    alt = await client.get_best_alternative("openai/gpt-4o", max_price=10.0)
    if alt:
        print(f"Fallback to: {alt.id}")

asyncio.run(main())

🕒 Sync Facade (For Scripts / Notebooks)

from openrouter_insights import LLMIndexSync

client = LLMIndexSync(mode="json")

# Get the absolute cheapest frontier model
cheap_pro = client.get_cheapest(tier="frontier", limit=3)
for m in cheap_pro:
    print(f"{m.name}: ${m.pricing.input}/1M tokens")

---

🧠 Data Intelligence (Providers)

OpenRouter Insights aggregates data from world-class sources to provide high-fidelity metrics:

• ArtificialAnalysis.ai: Our primary source for model performance. We integrate their independent benchmarks for Intelligence, Quality (V2 ELO), and Speed (TPS) to power our ranking logic.
• OpenRouter.ai: Our core model catalog. We sync directly with their API to provide real-time pricing and availability for hundreds of models.

---

🕒 Data Freshness & Automation (Git-Ops)

OpenRouter Insights is not a static file. We run an automated 24-hour synchronization job via GitHub Actions (CRON) that:

1. Fetches the latest models and pricing from OpenRouter.
2. Unifies benchmark data from ArtificialAnalysis.
3. Processes the results via our Matching Engine.
4. Commits the fresh openrouter_insights.sqlite and .json back to the repository.

This ensures you always have access to the latest frontier models as they are released.

---

✨ Smart Query Methods

OpenRouter Insights comes with pre-built logic to discover models based on real-world capabilities:

• .get_smartest(): Highest intelligence scores first.
• .get_cheapest(): Lowest cost-to-output first (excludes virtual routers).
• .get_best_for_coding(): Top-tier coding performers.
• .get_top_frontier(): Only the best models in the world.
• .get_by_tier("pro"): Native DB-level filtering by performance tiers.
• .get_fastest(): Highest Tokens Per Second (TPS).

---

🔄 Model Substitution

One of the most powerful features is the Substitution Engine. It allows you to find valid fallbacks when a model is unavailable or exceeds your budget, ensuring your agents stay operational:

# Seek the highest performing alternative in the same tier
fallback = client.get_best_alternative(
    model_id="anthropic/claude-3.5-sonnet", 
    max_price=15.0  # Optional cost ceiling
)

---

We take production stability seriously. Every release is validated against a comprehensive test suite (Unit, Integration, Persistence, and Facade tests).

Current Status: 61 tests passed (95% global coverage).

---

🔮 Future Roadmap

We are committed to making this the most comprehensive LLM index in the industry. Future data sources planned for integration include:

• Hugging Face: Open LLM Leaderboard scores.
• Vercel AI: Comprehensive provider metrics.
• LMSYS Chatbot Arena: Live ELO ratings.

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

---

📄 License

Distributed under the MIT License. See LICENSE for more information.

---

Luis Eduardo Farfan Melgar - [e-mail]
Project Link: https://github.com/luisfarfan/openrouter-insights