ai-provider-tracker 0.7.0__tar.gz

ai_provider_tracker-0.7.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luis Eduardo Farfan Melgar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ai_provider_tracker-0.7.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: ai-provider-tracker
+Version: 0.7.0
+Summary: Unified usage and cost tracking for AI providers such as FAL.AI and OpenRouter.
+License-File: LICENSE
+Author: Luis Eduardo Farfan Melgar
+Author-email: lucho.farfan9@gmail.com
+Requires-Python: >=3.11,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Provides-Extra: api
+Requires-Dist: aiohttp (>=3.9.3,<4.0.0)
+Requires-Dist: fastapi (>=0.110.0,<0.111.0) ; extra == "api"
+Requires-Dist: pydantic (>=2.6.4,<3.0.0)
+Requires-Dist: pydantic-settings (>=2.2.1,<3.0.0)
+Requires-Dist: python-dotenv (>=1.0.1,<2.0.0)
+Requires-Dist: rapidfuzz (>=3.6.2,<4.0.0)
+Requires-Dist: sqlmodel (>=0.0.16,<0.0.17)
+Requires-Dist: uvicorn (>=0.29.0,<0.30.0) ; extra == "api"
+Project-URL: Documentation, https://github.com/luisfarfan/ai-provider-tracker#readme
+Project-URL: Homepage, https://github.com/luisfarfan/ai-provider-tracker
+Project-URL: Repository, https://github.com/luisfarfan/ai-provider-tracker
+Description-Content-Type: text/markdown
+
+# AI Provider Tracker
+
+[![PyPI version](https://img.shields.io/pypi/v/ai-provider-tracker.svg)](https://pypi.org/project/ai-provider-tracker/)
+[![Python versions](https://img.shields.io/pypi/pyversions/ai-provider-tracker.svg)](https://pypi.org/project/ai-provider-tracker/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**AI Provider Tracker** is a Python library for tracking AI provider usage and estimating per-generation costs across heterogeneous providers.
+
+It is designed for apps that already call providers such as **FAL.AI** and **OpenRouter**, but need a centralized way to:
+
+- normalize usage metadata
+- calculate request/generation costs
+- store raw request/response payloads for auditability
+- persist optional local analytics in SQLite
+- use bundled pricing snapshots without calling pricing APIs at runtime
+
+## Installation
+
+```bash
+pip install ai-provider-tracker
+```
+
+Optional FastAPI dependencies for the legacy model registry API:
+
+```bash
+pip install "ai-provider-tracker[api]"
+```
+
+## Cost Tracking
+
+Use your provider SDK as usual, then pass the request and response to the tracker.
+
+```python
+from ai_provider_tracker import CostTracker
+
+tracker = CostTracker()
+
+event = tracker.track_generation(
+    provider="fal",
+    model="fal-ai/flux/dev",
+    request={"prompt": "A cyberpunk city", "num_images": 2},
+    response={"images": [{"url": "a"}, {"url": "b"}]},
+)
+
+print(event.cost.total)       # 0.050
+print(event.cost.source)      # public_snapshot
+print(event.cost.confidence)  # high
+print(event.cost.breakdown)
+```
+
+Enable local SQLite persistence:
+
+```python
+tracker = CostTracker(sqlite_path="ai_usage.sqlite")
+```
+
+This stores generation events with normalized usage, cost breakdown, raw request, raw response, and metadata.
+
+## OpenRouter
+
+For OpenRouter, provider-reported usage cost is preferred when present:
+
+```python
+event = tracker.track_generation(
+    provider="openrouter",
+    model="anthropic/claude-sonnet-4.5",
+    request={"messages": [{"role": "user", "content": "Hello"}]},
+    response={
+        "usage": {
+            "prompt_tokens": 1200,
+            "completion_tokens": 800,
+            "cost": "0.015",
+        }
+    },
+)
+
+print(event.cost.total)   # provider-reported cost
+print(event.cost.source)  # provider_reported
+```
+
+If `usage.cost` is not present, the tracker falls back to token-based calculation using the bundled pricing catalog when possible.
+
+## Pricing Catalog
+
+The package ships with a bundled JSON pricing catalog:
+
+```text
+ai_provider_tracker/data/pricing_catalog.json
+```
+
+Runtime requests do not call pricing APIs. Pricing sync is handled by:
+
+```bash
+python scripts/sync_pricing_catalog.py
+```
+
+The GitHub Actions workflow `.github/workflows/pricing_sync.yml` runs daily and commits the catalog only when prices actually change.
+
+## Legacy Model Registry
+
+This package still includes the original OpenRouter model registry APIs:
+
+```python
+from ai_provider_tracker import LLMIndexSync
+
+client = LLMIndexSync(mode="json")
+models = client.get_cheapest(limit=5)
+```
+
+The old import path remains available temporarily:
+
+```python
+from openrouter_insights import CostTracker
+```
+
+New code should use:
+
+```python
+from ai_provider_tracker import CostTracker
+```
+
+## Accuracy Contract
+
+Cost values are intended for product analytics, internal attribution, and budget monitoring.
+
+- FAL.AI costs are locally estimated from pricing snapshots and normalized request/response metadata.
+- OpenRouter costs use provider-reported cost when available.
+- Public bundled pricing is a reference snapshot, not a guarantee of account-specific billing.
+
+For invoice-grade accounting, reconcile against provider billing/usage APIs.
+
+## License
+
+MIT
+

ai_provider_tracker-0.7.0/README.md

@@ -0,0 +1,134 @@
+# AI Provider Tracker
+
+[![PyPI version](https://img.shields.io/pypi/v/ai-provider-tracker.svg)](https://pypi.org/project/ai-provider-tracker/)
+[![Python versions](https://img.shields.io/pypi/pyversions/ai-provider-tracker.svg)](https://pypi.org/project/ai-provider-tracker/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**AI Provider Tracker** is a Python library for tracking AI provider usage and estimating per-generation costs across heterogeneous providers.
+
+It is designed for apps that already call providers such as **FAL.AI** and **OpenRouter**, but need a centralized way to:
+
+- normalize usage metadata
+- calculate request/generation costs
+- store raw request/response payloads for auditability
+- persist optional local analytics in SQLite
+- use bundled pricing snapshots without calling pricing APIs at runtime
+
+## Installation
+
+```bash
+pip install ai-provider-tracker
+```
+
+Optional FastAPI dependencies for the legacy model registry API:
+
+```bash
+pip install "ai-provider-tracker[api]"
+```
+
+## Cost Tracking
+
+Use your provider SDK as usual, then pass the request and response to the tracker.
+
+```python
+from ai_provider_tracker import CostTracker
+
+tracker = CostTracker()
+
+event = tracker.track_generation(
+    provider="fal",
+    model="fal-ai/flux/dev",
+    request={"prompt": "A cyberpunk city", "num_images": 2},
+    response={"images": [{"url": "a"}, {"url": "b"}]},
+)
+
+print(event.cost.total)       # 0.050
+print(event.cost.source)      # public_snapshot
+print(event.cost.confidence)  # high
+print(event.cost.breakdown)
+```
+
+Enable local SQLite persistence:
+
+```python
+tracker = CostTracker(sqlite_path="ai_usage.sqlite")
+```
+
+This stores generation events with normalized usage, cost breakdown, raw request, raw response, and metadata.
+
+## OpenRouter
+
+For OpenRouter, provider-reported usage cost is preferred when present:
+
+```python
+event = tracker.track_generation(
+    provider="openrouter",
+    model="anthropic/claude-sonnet-4.5",
+    request={"messages": [{"role": "user", "content": "Hello"}]},
+    response={
+        "usage": {
+            "prompt_tokens": 1200,
+            "completion_tokens": 800,
+            "cost": "0.015",
+        }
+    },
+)
+
+print(event.cost.total)   # provider-reported cost
+print(event.cost.source)  # provider_reported
+```
+
+If `usage.cost` is not present, the tracker falls back to token-based calculation using the bundled pricing catalog when possible.
+
+## Pricing Catalog
+
+The package ships with a bundled JSON pricing catalog:
+
+```text
+ai_provider_tracker/data/pricing_catalog.json
+```
+
+Runtime requests do not call pricing APIs. Pricing sync is handled by:
+
+```bash
+python scripts/sync_pricing_catalog.py
+```
+
+The GitHub Actions workflow `.github/workflows/pricing_sync.yml` runs daily and commits the catalog only when prices actually change.
+
+## Legacy Model Registry
+
+This package still includes the original OpenRouter model registry APIs:
+
+```python
+from ai_provider_tracker import LLMIndexSync
+
+client = LLMIndexSync(mode="json")
+models = client.get_cheapest(limit=5)
+```
+
+The old import path remains available temporarily:
+
+```python
+from openrouter_insights import CostTracker
+```
+
+New code should use:
+
+```python
+from ai_provider_tracker import CostTracker
+```
+
+## Accuracy Contract
+
+Cost values are intended for product analytics, internal attribution, and budget monitoring.
+
+- FAL.AI costs are locally estimated from pricing snapshots and normalized request/response metadata.
+- OpenRouter costs use provider-reported cost when available.
+- Public bundled pricing is a reference snapshot, not a guarantee of account-specific billing.
+
+For invoice-grade accounting, reconcile against provider billing/usage APIs.
+
+## License
+
+MIT

ai_provider_tracker-0.7.0/ai_provider_tracker/__init__.py

@@ -0,0 +1,206 @@
+import asyncio
+from typing import List, Optional, Literal
+
+__version__ = "0.1.0"
+from ai_provider_tracker.domain.entities import LLMModel, Pricing, Benchmarks
+from ai_provider_tracker.adapters.persistence.sqlite_repository import SQLiteModelRepository
+from ai_provider_tracker.adapters.persistence.json_repository import JSONModelRepository
+from ai_provider_tracker.use_cases.sync_registry import SyncRegistryUseCase
+from ai_provider_tracker.adapters.gateways.openrouter_fetcher import OpenRouterFetcher
+from ai_provider_tracker.adapters.gateways.artificial_analysis_fetcher import ArtificialAnalysisFetcher
+from ai_provider_tracker.domain.services.matching_engine import MatchingEngine
+from ai_provider_tracker.adapters.persistence.json_exporter import JSONExporter
+from ai_provider_tracker.cost_tracking import (
+    CostBreakdownLine,
+    CostResult,
+    CostTracker,
+    GenerationUsageEvent,
+    NormalizedUsage,
+    PricingCatalog,
+    PricingEntry,
+    UsageUnit,
+)
+
+class LLMIndexSync:
+    """
+    Synchronous entry point for LLMIndex. 
+    Perfect for scripts, notebooks, and CLI tools. No 'await' required.
+    """
+    
+    def __init__(self, mode: Literal["sqlite", "json"] = "sqlite", path: Optional[str] = None):
+        self.mode = mode
+        if mode == "sqlite":
+            self.repository = SQLiteModelRepository(database_url=path)
+        else:
+            self.repository = JSONModelRepository(file_path=path or "ai_provider_tracker.json")
+
+    def get_models(self, filter_virtual: bool = True, **kwargs) -> List[LLMModel]:
+        """Base query method. Excludes routers like openrouter/auto by default."""
+        return self.repository.get_all(filter_virtual=filter_virtual, **kwargs)
+
+    def get_model(self, model_id: str) -> Optional[LLMModel]:
+        return self.repository.get_by_id(model_id)
+
+    # --- Smart Query Methods ---
+
+    def get_smartest(self, limit: int = 10) -> List[LLMModel]:
+        """Top models by overall intelligence score."""
+        return self.get_models(sort_by="intelligence", page_size=limit)
+
+    def get_cheapest(self, best_for: Optional[str] = None, filter_virtual: bool = True, limit: int = 10) -> List[LLMModel]:
+        """Models sorted by price (input + output) ascending."""
+        return self.get_models(best_for=best_for, filter_virtual=filter_virtual, sort_by="price", sort_order="asc", page_size=limit)
+
+    def get_fastest(self, limit: int = 10) -> List[LLMModel]:
+        """Top models by Output TPS (Tokens Per Second)."""
+        return self.get_models(sort_by="speed", page_size=limit)
+
+    def get_best_for_coding(self, limit: int = 5) -> List[LLMModel]:
+        return self.get_models(best_for="coding", sort_by="intelligence", page_size=limit)
+
+    def get_best_for_reasoning(self, limit: int = 5) -> List[LLMModel]:
+        return self.get_models(best_for="reasoning", sort_by="intelligence", page_size=limit)
+
+    def get_best_for_rag(self, limit: int = 5) -> List[LLMModel]:
+        """Models with high context and solid intelligence."""
+        return self.get_models(best_for="rag", sort_by="intelligence", page_size=limit)
+
+    def get_best_for_multimodal(self, limit: int = 5) -> List[LLMModel]:
+        """Models with vision/media capabilities and high ELO."""
+        return self.get_models(best_for="multimodal", sort_by="elo", page_size=limit)
+
+    def get_free_models(self) -> List[LLMModel]:
+        """All models with zero input cost."""
+        return self.get_models(is_free=True)
+
+    def get_top_frontier(self, limit: int = 3) -> List[LLMModel]:
+        """The absolute SOTA models (Frontier tier)."""
+        # Filter by tier in memory for consistency across repos
+        all_models = self.get_models(sort_by="intelligence", page_size=50)
+        return [m for m in all_models if m.performance_tier == "frontier"][:limit]
+
+    def get_by_tier(self, tier: Literal["frontier", "pro", "lite"], filter_virtual: bool = True, limit: int = 10) -> List[LLMModel]:
+        """Get models from a specific performance tier (using native DB filtering)."""
+        return self.get_models(best_for=tier, filter_virtual=filter_virtual, sort_by="intelligence", page_size=limit)
+
+    def get_best_alternative(self, model_id: str, max_price: Optional[float] = None) -> Optional[LLMModel]:
+        """Find the best substitute for a given model (same tier, under budget)."""
+        return self.repository.get_best_alternative(model_id, max_price)
+
+    def get_by_provider(self, provider: str, limit: int = 10) -> List[LLMModel]:
+        return self.get_models(provider=provider, page_size=limit)
+
+    def search(self, query: str, limit: int = 10) -> List[LLMModel]:
+        """Fuzzy search models by name, provider or ID."""
+        return self.repository.search(query, limit=limit)
+
+    def sync(self) -> List[LLMModel]:
+        """Synchronize registry (Sync wrapper for the async use case)."""
+        if self.mode == "json":
+            raise ValueError("Sync is not supported in JSON mode.")
+        return asyncio.run(self._async_sync())
+
+    async def _async_sync(self):
+        fetchers = [OpenRouterFetcher(), ArtificialAnalysisFetcher()]
+        use_case = SyncRegistryUseCase(
+            repository=self.repository, 
+            gateways=fetchers, 
+            matching_engine=MatchingEngine(85.0),
+            exporter=JSONExporter("ai_provider_tracker.json")
+        )
+        return await use_case.execute()
+
+
+class LLMIndex:
+    """
+    Asynchronous entry point for LLMIndex. 
+    Ideal for FastAPI, Discord bots, and async apps.
+    """
+    
+    def __init__(self, mode: Literal["sqlite", "json"] = "sqlite", path: Optional[str] = None):
+        self.mode = mode
+        if mode == "sqlite":
+            self.repository = SQLiteModelRepository(database_url=path)
+        else:
+            self.repository = JSONModelRepository(file_path=path or "ai_provider_tracker.json")
+
+    async def get_models(self, filter_virtual: bool = True, **kwargs) -> List[LLMModel]:
+        return self.repository.get_all(filter_virtual=filter_virtual, **kwargs)
+
+    async def get_model(self, model_id: str) -> Optional[LLMModel]:
+        return self.repository.get_by_id(model_id)
+
+    # --- Smart Query Methods (Async) ---
+
+    async def get_smartest(self, limit: int = 10) -> List[LLMModel]:
+        return await self.get_models(sort_by="intelligence", page_size=limit)
+
+    async def get_cheapest(self, best_for: Optional[str] = None, filter_virtual: bool = True, limit: int = 10) -> List[LLMModel]:
+        return await self.get_models(best_for=best_for, filter_virtual=filter_virtual, sort_by="price", sort_order="asc", page_size=limit)
+
+    async def get_fastest(self, limit: int = 10) -> List[LLMModel]:
+        return await self.get_models(sort_by="speed", page_size=limit)
+
+    async def get_best_for_coding(self, limit: int = 5) -> List[LLMModel]:
+        return await self.get_models(best_for="coding", sort_by="intelligence", page_size=limit)
+
+    async def get_best_for_reasoning(self, limit: int = 5) -> List[LLMModel]:
+        return await self.get_models(best_for="reasoning", sort_by="intelligence", page_size=limit)
+
+    async def get_best_for_rag(self, limit: int = 5) -> List[LLMModel]:
+        return await self.get_models(best_for="rag", sort_by="intelligence", page_size=limit)
+
+    async def get_best_for_multimodal(self, limit: int = 5) -> List[LLMModel]:
+        return await self.get_models(best_for="multimodal", sort_by="elo", page_size=limit)
+
+    async def get_free_models(self) -> List[LLMModel]:
+        return await self.get_models(is_free=True)
+
+    async def get_top_frontier(self, limit: int = 3) -> List[LLMModel]:
+        all_models = await self.get_models(sort_by="intelligence", page_size=50)
+        return [m for m in all_models if m.performance_tier == "frontier"][:limit]
+
+    async def get_by_tier(self, tier: Literal["frontier", "pro", "lite"], filter_virtual: bool = True, limit: int = 10) -> List[LLMModel]:
+        return await self.get_models(best_for=tier, filter_virtual=filter_virtual, sort_by="intelligence", page_size=limit)
+
+    async def get_best_alternative(self, model_id: str, max_price: Optional[float] = None) -> Optional[LLMModel]:
+        return self.repository.get_best_alternative(model_id, max_price)
+
+    async def get_by_provider(self, provider: str, limit: int = 10) -> List[LLMModel]:
+        return await self.get_models(provider=provider, page_size=limit)
+
+    async def search(self, query: str, limit: int = 10) -> List[LLMModel]:
+        return self.repository.search(query, limit=limit)
+
+    async def sync(self) -> List[LLMModel]:
+        if self.mode == "json":
+            raise ValueError("Sync is not supported in JSON mode.")
+        fetchers = [OpenRouterFetcher(), ArtificialAnalysisFetcher()]
+        use_case = SyncRegistryUseCase(
+            repository=self.repository, 
+            gateways=fetchers, 
+            matching_engine=MatchingEngine(85.0),
+            exporter=JSONExporter("ai_provider_tracker.json")
+        )
+        return await use_case.execute()
+
+__all__ = [
+    "LLMIndex",
+    "LLMIndexSync",
+    "LLMModel", 
+    "Pricing", 
+    "Benchmarks", 
+    "SQLiteModelRepository", 
+    "JSONModelRepository",
+    "SyncRegistryUseCase", 
+    "OpenRouterFetcher",
+    "ArtificialAnalysisFetcher",
+    "CostBreakdownLine",
+    "CostResult",
+    "CostTracker",
+    "GenerationUsageEvent",
+    "NormalizedUsage",
+    "PricingCatalog",
+    "PricingEntry",
+    "UsageUnit",
+]

ai_provider_tracker-0.7.0/ai_provider_tracker/adapters/api/main.py

@@ -0,0 +1,147 @@
+from typing import List, Optional
+from pydantic import BaseModel
+from enum import Enum
+
+from fastapi import FastAPI, Query, HTTPException, Depends
+from fastapi.middleware.cors import CORSMiddleware
+from ai_provider_tracker import LLMIndex, LLMModel
+
+
+# Enum Definitions for better Swagger UI
+class Provider(str, Enum):
+    OPENAI = "OpenAI"
+    ANTHROPIC = "Anthropic"
+    GOOGLE = "Google"
+    META = "Meta"
+    MISTRAL = "Mistral"
+    XAI = "xAI"
+    DEEPSEEK = "DeepSeek"
+    MICROSOFT = "Microsoft"
+    COHERE = "Cohere"
+
+class BestFor(str, Enum):
+    CODING = "coding"
+    REASONING = "reasoning"
+    REAL_TIME = "real-time"
+    MULTIMODAL_HIGH_FIDELITY = "multimodal-high-fidelity"
+    MULTIMODAL = "multimodal"
+    RAG = "rag"
+
+class SortBy(str, Enum):
+    PRICE = "price"
+    INTELLIGENCE = "intelligence"
+    SPEED = "speed"
+    ELO = "elo"
+
+class Order(str, Enum):
+    ASC = "asc"
+    DESC = "desc"
+
+
+class PaginatedModelsResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: List[LLMModel]
+
+app = FastAPI(
+    title="LLMIndex API",
+    description="The Unified Open-Source LLM Registry API.",
+    version="0.1.0"
+)
+
+# CORS Middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Dependency Injection Setup
+def get_index():
+    return LLMIndex(mode="sqlite")
+
+@app.get("/", tags=["Health"])
+async def root():
+    return {"status": "ok", "message": "LLMIndex API is live."}
+
+@app.get("/api/v1/models", response_model=PaginatedModelsResponse, tags=["Models"])
+async def get_models(
+    provider: Provider = Query(None, description="Filter by provider (e.g., OpenAI, Anthropic)"),
+    best_for: BestFor = Query(None, description="Filter by strength (coding, rag, real-time, multimodal)"),
+    is_free: bool = Query(False, description="Show only free models"),
+    min_intelligence: float = Query(None, description="Minimum benchmark score"),
+    sort_by: SortBy = Query(None, description="Sort order (price, intelligence, speed)"),
+    order: Order = Query(Order.DESC, description="Sorting direction (asc, desc)"),
+    page: int = Query(1, ge=1, description="Page number"),
+    page_size: int = Query(20, ge=1, le=100, description="Items per page"),
+    index: LLMIndex = Depends(get_index)
+):
+    """
+    Query the unified LLM registry with high-fidelity filters.
+    """
+    p_val = provider.value if provider else None
+    b_val = best_for.value if best_for else None
+    s_val = sort_by.value if sort_by else None
+    o_val = order.value
+
+    total = await index.get_count(
+        provider=p_val,
+        best_for=b_val,
+        is_free=is_free,
+        min_intelligence=min_intelligence
+    )
+
+    models = await index.get_models(
+        provider=p_val,
+        best_for=b_val,
+        is_free=is_free,
+        min_intelligence=min_intelligence,
+        sort_by=s_val,
+        sort_order=o_val,
+        page=page,
+        page_size=page_size
+    )
+
+    return PaginatedModelsResponse(
+        total=total,
+        page=page,
+        page_size=page_size,
+        results=models
+    )
+
+
+@app.get("/api/v1/models/{model_id:path}", response_model=LLMModel, tags=["Models"])
+async def get_model_detail(
+    model_id: str,
+    index: LLMIndex = Depends(get_index)
+):
+    """Get a detailed view of a specific model in the registry."""
+    model = await index.get_model(model_id)
+    if not model:
+        raise HTTPException(status_code=404, detail="Model not found in registry.")
+    return model
+
+@app.get("/api/v1/search", response_model=List[LLMModel], tags=["Models"])
+async def search_models(
+    q: str = Query(..., min_length=2, description="Search term for model name or provider"),
+    limit: int = Query(10, ge=1, le=50),
+    index: LLMIndex = Depends(get_index)
+):
+    """Fuzzy search models by name or provider."""
+    return await index.search(q, limit=limit)
+
+@app.post("/api/v1/sync", tags=["Admin"])
+async def trigger_sync(index: LLMIndex = Depends(get_index)):
+    """
+    Trigger a manual synchronization of the registry.
+    """
+    models = await index.sync()
+    return {"status": "success", "synced_models": len(models)}
+
+
+def run_server():
+    import uvicorn
+    uvicorn.run("ai_provider_tracker.adapters.api.main:app", host="0.0.0.0", port=8000, reload=True)