Data Flow
This page describes the primary data flows in OpenModels — how data moves from community contributions through validation into the registry, how users discover models via the API, and how telemetry is collected from providers.
Registry Contribution Flow
When a contributor adds or updates a model, provider, or mapping in the registry, the following sequence occurs:
Validation Steps
The validation pipeline performs the following checks on every pull request:
| Step | Check | Failure Behavior |
|---|---|---|
| 1 | YAML syntax parsing | Rejects malformed YAML files |
| 2 | JSON Schema validation | Rejects files that don’t match schema definitions |
| 3 | Referential integrity | Rejects mappings referencing non-existent models or providers |
| 4 | Duplicate detection | Rejects duplicate model or provider IDs |
Model Discovery Flow
When a user searches for models or retrieves model details through the API:
API Endpoints
| Endpoint Pattern | Description |
|---|---|
/api/models | List and search models with filtering |
/api/models/{id} | Get full model details |
/api/models/{id}/providers | List providers for a model with pricing |
/api/models/{id}/compare | Compare providers side-by-side |
/api/models/popular | Popular models ranked by relevance |
/api/providers | List all providers |
/api/search | Unified search across models and providers |
/api/providers/{id}/health, /api/providers/{id}/latency | Provider health and latency data |
Telemetry Collection Flow
The telemetry system continuously monitors provider health and latency:
Telemetry Metrics
| Metric | Collection Interval | Retention |
|---|---|---|
| Health status | Hourly at minute 00 UTC | 30 days |
| Time to first token (TTFT) | At 06:15 and 18:15 UTC | 30 days |
| Total response time | At 06:15 and 18:15 UTC | 30 days |
| Availability (uptime %) | Computed from health records | Rolling 7 days |
| Freshness | Health older than 90 minutes is unknown | Missing metrics are null |
Probe Policies
Each provider can have a custom probe policy controlling:
- Enabled/disabled — Whether probes run for this provider
- Schedule — Celery beat controls the global cadence above; the policy’s
interval_minutessetting does not reschedule the beat task - Daily limit — Maximum probes per day to control costs (default: 96)
Policies are tracked in Redis with daily counters that auto-expire after 24 hours.
Provider Ranking Algorithm
When a user requests ranked providers for a model via GET /api/models/{id}/providers/ranked, the API computes a composite score:
| Factor | Weight | Source |
|---|---|---|
| Uptime percentage (24-hour rolling) | 40% | Usable health probe records |
| Mean latency (TTFT) | 35% | Provider-wide valid samples in the last 24 hours |
| Mean input/output price per million tokens | 25% | Registry mapping data |
Unknown health/latency earns no credit for that factor but stays null in the response. Model provider lists and comparisons use model-specific latency; this ranked endpoint currently uses provider-wide latency. Local TLS trust failures are excluded from uptime rather than counted as provider outages.
End-to-End Data Lifecycle
The complete lifecycle of data in OpenModels from contribution to user consumption:
Related Pages
- Architecture Overview — High-level system architecture and component descriptions
- Schemas — YAML schema definitions for models, providers, and mappings