Horde Model Reference
The Horde Model Reference is the authoritative source for AI model metadata in the AI-Horde ecosystem. It provides validated metadata: download URLs, checksums, baselines, NSFW flags, capabilities: for image generation, text generation, and utility models used by workers, clients, and services.
New to the project? The Glossary defines the recurring terms (PRIMARY/REPLICA, canonical data, GitHub fallback, backends, providers) in plain language.
Where do I start?
This project is three things in one: a Python library, a public HTTP API, and a FastAPI service you can run yourself. Each serves the same data, but is optimized for different use cases:
| You want to... | Use | Start here |
|---|---|---|
| Read model metadata from Python (worker, client, script) | The library (pip install horde-model-reference), runs in-process |
Getting Started |
| Read metadata from a non-Python app, or without adding a dependency | The HTTP API on the public PRIMARY server (https://models.aihorde.net/api) |
Using the HTTP API |
| Surface your own / third-party models alongside the canonical set | A read-only provider (library feature) | Registering & Consuming Providers |
| Host a replica of the canonical dataset for local reads and redundancy | Run the FastAPI service in REPLICA mode | API Deployments |
| Host the canonical dataset for others (uncommon, for AI-Horde forks or custom deployments) | Run the FastAPI service in PRIMARY mode | Primary Deployments |
Library or HTTP API? If you are already in Python, prefer the library: it caches in-process, returns typed records, and automatically falls back to GitHub if the PRIMARY server is down. Reach for the HTTP API when you are not in Python, want zero install footprint, or are integrating against a central server you do not operate. Both read the same data.
As a reader you never choose PRIMARY vs REPLICA: consumers are REPLICA (read-only) by default, with no configuration required. See the Glossary.
Getting Started
I want to learn by doing.
- Getting Started: Install, run your first query, understand the singleton pattern and prefetch strategies
- Querying Models: Filter, sort, and aggregate models with the fluent query API
- Using the HTTP API: Call the live service: list, fetch, search, and rank models over HTTP
- Registering & Consuming Providers: Contribute and read records from third-party sources
- Working with Records: Record types, fields, type narrowing, serialization
- Configuration & Troubleshooting: Environment variables, debugging, common issues
Prefer working code? The examples/ directory has runnable scripts for each topic.
How-To Guides
I have a specific task to accomplish.
- Filter Models for a Worker: Narrow the reference to the models your node should serve
- Read Resiliently: Caching, GitHub fallback, and graceful degradation when offline
- Consume the HTTP API: Integrate the read API into a worker or client; detect changes cheaply
- Submit Models via the API: The authenticated propose / approve / apply write workflow
- Write a Live Provider: Expose a remote catalog as a read-only source
Concepts
I want to understand how the system works.
- Architecture Overview: Three usage modes, backbone modules, subsystem map
- The HTTP Service: What the FastAPI service is for, who calls it, and where it fits in the AI-Horde ecosystem
- Request Lifecycle: How the FastAPI service processes read and write requests end-to-end
- Sync System: How PRIMARY changes propagate to legacy GitHub repositories
- Analytics Pipeline: Statistics, audit analysis, text model grouping, and cache hydration
- Integrations: Live Horde API data fetching, caching, and merging with model references
- Canonical Format: API versioning (v1/v2) and canonical format configuration
- Design Decisions: Trade-offs and known limitations explained
Reference
I need to look something up.
- Glossary: Plain-language definitions of PRIMARY/REPLICA, canonical data, backends, providers, and more
- Model Reference Backend: Backend ABC, capability checks, implementation checklist
- Model Providers: Provider ABC, registry, source selection and collision rules
- Model Reference Records: Record hierarchy, validation, registration pattern
- HTTP API: Full REST reference: conventions, v2 & v1 endpoints, text utilities, pending queue
- Primary Deployments: Backend selection, Redis multi-worker setup, cache warming
- Replica Backend Base: TTL caching and staleness tracking infrastructure
- Audit Trail: Append-only operation logging and state replay
- Pending Queue: Propose / approve / apply change workflow
- Legacy CSV Conversion: Converting from legacy text generation CSV format
Code Reference
Auto-generated API documentation from source code docstrings. Browse the package reference in the Code Reference nav section. For the HTTP API, see the HTTP API reference or visit the live /api/docs Swagger UI.