horde-model-reference 5.2.0__tar.gz → 5.3.0__tar.gz

horde_model_reference-5.3.0/.env.example

@@ -0,0 +1,261 @@
+# Auto-generated example environment file for Horde Model Reference
+# This file is generated by the settings_doc package.
+# Do not edit this file manually.
+
+# Generated on (UTC): 2026-06-16 14:58:18
+
+# DEPLOYMENT QUICK START GUIDE
+
+# Choose your deployment scenario and uncomment the relevant settings below:
+
+# 1. REPLICA MODE (Default) - Client/Worker nodes
+#    - Uses GitHub or PRIMARY API to fetch model references
+#    - Set: HORDE_MODEL_REFERENCE_REPLICATE_MODE=REPLICA
+#    - Optionally set: HORDE_MODEL_REFERENCE_PRIMARY_API_URL=<your-primary-url>
+
+# 2. PRIMARY MODE - Single Worker (No Redis)
+#    - Authoritative source for model references
+#    - Set: HORDE_MODEL_REFERENCE_REPLICATE_MODE=PRIMARY
+#    - No Redis configuration needed
+#   - Ideal for: Development, testing, low-traffic deployments
+
+# 3. PRIMARY MODE - Multi-Worker (With Redis)
+#   - Authoritative source with distributed caching
+#   - Set: HORDE_MODEL_REFERENCE_REPLICATE_MODE=PRIMARY
+#   - Configure all HORDE_MODEL_REFERENCE_REDIS_* settings
+#   - Ideal for: Production, high-traffic deployments
+
+# For detailed deployment instructions, see:
+#   - Docker: docker-compose.yml (single-worker)
+#   - Docker + Redis: docker-compose.redis.yml (multi-worker)
+#   - Non-Docker: DEPLOYMENT.md
+
+
+################################################################################
+# Horde Model Reference Settings
+################################################################################
+
+# Indicates if copies of the model reference are canonical or replicated. Clients should always be replicas.
+# Possible values:
+#   `PRIMARY`, `REPLICA`
+# HORDE_MODEL_REFERENCE_REPLICATE_MODE=REPLICA
+
+# Read references straight from local disk and never download (no GitHub / PRIMARY API / Redis). Intended for subprocesses whose parent already downloaded and wrote the converted reference files. When True, primary_api_url, github_seed, and redis are ignored and a LocalReadOnlyBackend is used.
+# HORDE_MODEL_REFERENCE_OFFLINE=False
+
+# Whether to create the default model reference folders on initialization.
+# HORDE_MODEL_REFERENCE_MAKE_FOLDERS=False
+
+# The GitHub owner of the repository.
+# HORDE_MODEL_REFERENCE_IMAGE_GITHUB_REPO__OWNER=Haidra-Org
+
+# The name of the GitHub repository used for image model references.
+# HORDE_MODEL_REFERENCE_IMAGE_GITHUB_REPO__NAME=AI-Horde-image-model-reference
+
+# The GitHub branch of the repository.
+# HORDE_MODEL_REFERENCE_IMAGE_GITHUB_REPO__BRANCH=main
+
+# Settings for the GitHub proxy, if any.
+# HORDE_MODEL_REFERENCE_IMAGE_GITHUB_REPO__PROXY_SETTINGS=
+
+# The GitHub owner of the repository.
+# HORDE_MODEL_REFERENCE_TEXT_GITHUB_REPO__OWNER=Haidra-Org
+
+# The name of the GitHub repository used for text model references.
+# HORDE_MODEL_REFERENCE_TEXT_GITHUB_REPO__NAME=AI-Horde-text-model-reference
+
+# The GitHub branch of the repository.
+# HORDE_MODEL_REFERENCE_TEXT_GITHUB_REPO__BRANCH=main
+
+# Settings for the GitHub proxy, if any.
+# HORDE_MODEL_REFERENCE_TEXT_GITHUB_REPO__PROXY_SETTINGS=
+
+# The time-to-live for in memory caches of model reference files, in seconds.
+# HORDE_MODEL_REFERENCE_CACHE_TTL_SECONDS=60
+
+# The maximum number of attempts to retry downloading a legacy model reference file.
+# HORDE_MODEL_REFERENCE_LEGACY_DOWNLOAD_RETRY_MAX_ATTEMPTS=3
+
+# The backoff time in seconds between retry attempts when downloading a legacy model reference file.
+# HORDE_MODEL_REFERENCE_LEGACY_DOWNLOAD_RETRY_BACKOFF_SECONDS=2
+
+# Whether to use Redis for distributed caching. Only should be used in PRIMARY mode.
+# HORDE_MODEL_REFERENCE_REDIS__USE_REDIS=False
+
+# Redis connection URL. Format: redis://[:password]@host:port/db
+# HORDE_MODEL_REFERENCE_REDIS__URL=redis://localhost:6379/0
+
+# Connection pool size for Redis connections.
+# HORDE_MODEL_REFERENCE_REDIS__POOL_SIZE=10
+
+# Socket timeout in seconds for Redis operations.
+# HORDE_MODEL_REFERENCE_REDIS__SOCKET_TIMEOUT=5
+
+# Connection timeout in seconds when establishing Redis connection.
+# HORDE_MODEL_REFERENCE_REDIS__SOCKET_CONNECT_TIMEOUT=5
+
+# Maximum number of retry attempts for failed Redis operations.
+# HORDE_MODEL_REFERENCE_REDIS__RETRY_MAX_ATTEMPTS=3
+
+# Backoff time in seconds between retry attempts for Redis operations.
+# HORDE_MODEL_REFERENCE_REDIS__RETRY_BACKOFF_SECONDS=0.5
+
+# Prefix for all Redis keys to namespace model reference data.
+# HORDE_MODEL_REFERENCE_REDIS__KEY_PREFIX=horde:model_ref
+
+# TTL for cached entries in seconds. If None, uses cache_ttl_seconds from main settings.
+# HORDE_MODEL_REFERENCE_REDIS__TTL_SECONDS=
+
+# Enable pub/sub for cache invalidation across multiple PRIMARY workers.
+# HORDE_MODEL_REFERENCE_REDIS__USE_PUBSUB=True
+
+# Base URL of the PRIMARY server API for REPLICA clients to fetch model references from. This must include the service's ``/api`` root path; the backend appends ``/model_references/v2/{category}``. If None, REPLICA clients will only use GitHub. Example: https://models.aihorde.net/api
+# HORDE_MODEL_REFERENCE_PRIMARY_API_URL=https://models.aihorde.net/api
+
+# Timeout in seconds for HTTP requests to PRIMARY API.
+# HORDE_MODEL_REFERENCE_PRIMARY_API_TIMEOUT=10
+
+# Whether REPLICA clients should fallback to GitHub if PRIMARY API is unavailable.
+# HORDE_MODEL_REFERENCE_ENABLE_GITHUB_FALLBACK=True
+
+# Whether PRIMARY mode should seed from GitHub on first initialization if local files don't exist. Only used in PRIMARY mode. If True, will download and convert legacy references once on startup.
+# HORDE_MODEL_REFERENCE_GITHUB_SEED_ENABLED=False
+
+# Which format is the canonical source of truth. Controls which API has write access. 'v2' (default): v2 API has CRUD, v1 API is read-only (converts from v2 to legacy). 'LEGACY': v1 API has CRUD, v2 API is read-only (converts from legacy to v2).
+# Possible values:
+#   `legacy`, `v2`, `legacy`
+# HORDE_MODEL_REFERENCE_CANONICAL_FORMAT=v2
+
+# Timeout in seconds for Horde API requests to fetch model status, statistics, and worker information.
+# HORDE_MODEL_REFERENCE_HORDE_API_TIMEOUT=30
+
+# Cache TTL in seconds for Horde API responses. Uses Redis if available, otherwise in-memory caching.
+# HORDE_MODEL_REFERENCE_HORDE_API_CACHE_TTL=60
+
+# Cache TTL in seconds for category statistics. Uses Redis if available, otherwise in-memory caching.
+# HORDE_MODEL_REFERENCE_STATISTICS_CACHE_TTL=300
+
+# Cache TTL for deletion risk analysis results. Uses Redis if available, otherwise in-memory caching.
+# HORDE_MODEL_REFERENCE_DELETION_RISK_CACHE_TTL=300
+
+# Enable background pre-computation of statistics. Currently not implemented (future feature).
+# HORDE_MODEL_REFERENCE_ENABLE_STATISTICS_PRECOMPUTE=False
+
+# Preferred file hosts for deletion risk analysis in audit endpoints.
+# HORDE_MODEL_REFERENCE_PREFERRED_FILE_HOSTS=
+
+# Percentage threshold for low usage flag in audit analysis. Default 0.0065% flags bottom ~10% of models. Set lower (e.g., 0.005%) to flag fewer models or higher (e.g., 0.01%) to flag more models.
+# HORDE_MODEL_REFERENCE_LOW_USAGE_THRESHOLD_PERCENTAGE=0.0065
+
+# Low usage threshold for text_generation models (2% - more lenient than image models at 0.65%).
+# HORDE_MODEL_REFERENCE_TEXT_GEN_LOW_USAGE_THRESHOLD_PERCENTAGE=0.02
+
+# Skip download host validation for text_generation models completely.
+# HORDE_MODEL_REFERENCE_TEXT_GEN_IGNORE_DOWNLOAD_HOSTS=True
+
+# Minimum monthly usage for text_generation to be flagged as critical (allows some usage).
+# HORDE_MODEL_REFERENCE_TEXT_GEN_CRITICAL_USAGE_THRESHOLD=10
+
+# Minimum worker count for text_generation to be flagged as critical (allows some workers).
+# HORDE_MODEL_REFERENCE_TEXT_GEN_CRITICAL_WORKER_THRESHOLD=1
+
+# Whether audit trail writes are enabled in PRIMARY deployments.
+# HORDE_MODEL_REFERENCE_AUDIT__ENABLED=True
+
+# Maximum size in bytes for each JSONL segment before rolling over to a new file.
+# HORDE_MODEL_REFERENCE_AUDIT__MAX_SEGMENT_BYTES=5242880
+
+# Subdirectory name (relative to cache home) for storing audit logs when no override is provided.
+# HORDE_MODEL_REFERENCE_AUDIT__RELATIVE_SUBDIR=audit
+
+# Absolute path override for audit log storage. When set, relative_subdir is ignored.
+# HORDE_MODEL_REFERENCE_AUDIT__ROOT_PATH_OVERRIDE=
+
+# Whether the pending queue workflow is enabled (PRIMARY deployments only).
+# HORDE_MODEL_REFERENCE_PENDING_QUEUE__ENABLED=True
+
+# Relative folder under cache home used for queue persistence when no override is set.
+# HORDE_MODEL_REFERENCE_PENDING_QUEUE__RELATIVE_SUBDIR=pending_queue
+
+# Absolute path override for queue persistence. When set, relative_subdir is ignored.
+# HORDE_MODEL_REFERENCE_PENDING_QUEUE__ROOT_PATH_OVERRIDE=
+
+# Horde user IDs allowed to submit pending changes.
+# HORDE_MODEL_REFERENCE_PENDING_QUEUE__REQUESTOR_IDS=
+
+# Horde user IDs allowed to approve/reject pending batches (superset of requestors).
+# HORDE_MODEL_REFERENCE_PENDING_QUEUE__APPROVER_IDS=
+
+# Reserved for future rotation support (matches audit defaults).
+# HORDE_MODEL_REFERENCE_PENDING_QUEUE__MAX_SEGMENT_BYTES=5242880
+
+# Enable background cache hydration to keep audit/statistics caches warm. When enabled, caches are proactively refreshed before TTL expiry so clients always get fast cached responses.
+# HORDE_MODEL_REFERENCE_CACHE_HYDRATION_ENABLED=False
+
+# Interval in seconds between cache hydration refreshes. Should be less than cache TTLs (statistics_cache_ttl, deletion_risk_cache_ttl) to ensure caches stay warm. Default 240s (4 min) with 300s TTLs.
+# HORDE_MODEL_REFERENCE_CACHE_HYDRATION_INTERVAL_SECONDS=240
+
+# Maximum age in seconds before stale cached data is discarded. While hydration is running, clients receive stale data instead of waiting for fresh data. Default 1 hour.
+# HORDE_MODEL_REFERENCE_CACHE_HYDRATION_STALE_TTL_SECONDS=3600
+
+# Delay in seconds before first hydration run after service startup. Allows service to fully initialize before background tasks begin.
+# HORDE_MODEL_REFERENCE_CACHE_HYDRATION_STARTUP_DELAY_SECONDS=5
+
+# List of allowed origins for CORS. Warns if unset or empty, as it falls back to the FastAPI default behavior.         See https://fastapi.tiangolo.com/tutorial/cors/#use-corsmiddleware for details.
+# HORDE_MODEL_REFERENCE_CORS_ALLOWED_ORIGINS=
+
+
+
+################################################################################
+# AI Horde Client+Worker Settings
+################################################################################
+
+# Alternative API endpoints for the AI Horde. These should all lead to the same logical AI Horde.
+# ALT_HORDE_URLS=[HttpUrl('https://stablehorde.net/api/')]
+
+# The API key used for authenticating requests to the AI Horde.
+# API_KEY=**********
+
+# The API endpoint for AI Horde ratings.
+# RATINGS_URL=https://ratings.aihorde.net/api/
+
+# The folder where application logs are stored.
+# LOGS_FOLDER=./logs
+
+# The folder where AI worker (or client) files are stored, most notably models and checkpoints.
+# AIWORKER_CACHE_HOME=./models
+
+# The hugging face home directory.
+# HF_HOME=~/.cache/huggingface
+
+# The standard XDG cache directory.
+# XDG_CACHE_HOME=~/.cache/
+
+
+
+################################################################################
+# Github Proxying Settings
+################################################################################
+
+# The base URL for a http(s) GitHub proxy. If None, no proxy is used. This is intended for users where github        may be blocked.
+# GITHUB_PROXY_URL_BASE=
+
+
+
+################################################################################
+# AI Horde CI Settings
+################################################################################
+
+# Indicates if any CI/CD pipeline is ongoing.
+# TESTS_ONGOING=False
+
+# Indicates if the hordelib CI/CD pipeline is ongoing.
+# HORDELIB_CI_ONGOING=False
+
+# Indicates if the AI Horde SDK is currently being tested.
+# HORDE_SDK_TESTING=False
+
+# Indicates if the AI Horde is currently being tested.
+# AI_HORDE_TESTING=False
+
+

{horde_model_reference-5.2.0 → horde_model_reference-5.3.0}/.env.sync.example

@@ -16,8 +16,11 @@
 # METHOD 2: GitHub App (recommended for production)
 # Required scopes: Contents (Read & Write), Pull Requests (Read & Write)
 # Setup instructions in SYNC_README.md
+# Uses GitHub App *installation* auth (app id + installation id + private key PEM).
+# A GitHub App client_id/client_secret are NOT usable here.
 GITHUB_APP_ID=1234567
-GITHUB_APP_INSTALLATION_ID=12345678
+# Optional: if omitted, the installation id is auto-discovered from the target repo.
+# GITHUB_APP_INSTALLATION_ID=12345678
 
 # Private Key: Choose ONE option
 # Option A: Path to mounted PEM file (recommended for Docker)

{horde_model_reference-5.2.0 → horde_model_reference-5.3.0}/MANIFEST.in

@@ -2,6 +2,7 @@ include *.md
 recursive-include horde_model_reference *.py
 recursive-include horde_model_reference *.md
 recursive-include horde_model_reference *.typed
+recursive-include horde_model_reference *.json
 
 recursive-include tests *.py
 recursive-include tests *.json

{horde_model_reference-5.2.0/src/horde_model_reference.egg-info → horde_model_reference-5.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: horde_model_reference
-Version: 5.2.0
+Version: 5.3.0
 Summary: A helper library providing a way to work with the lists of generation models, utility models, and any other related files required for the AI-Horde ecosystem.
 Author-email: tazlin <tazlin.on.github@gmail.com>, db0 <mail@dbzer0.com>
 License:                     GNU AFFERO GENERAL PUBLIC LICENSE

{horde_model_reference-5.2.0 → horde_model_reference-5.3.0}/pyproject.toml

@@ -63,6 +63,13 @@ version_file = "src/horde_model_reference/_version.py"
 # include = ["horde_model_reference*", "horde_model_reference.*"]
 # exclude = ["horde_model_reference.showcase*", "horde_model_reference.tests*"]
 
+# Bundle the text-generation data files (defaults.json, generation_params.json) into the
+# wheel. Without this they are only present in editable installs, so the GitHub sync's
+# text_generation path fails in the --no-editable Docker image with
+# "Cannot find defaults.json in package data or scripts/legacy_text/".
+[tool.setuptools.package-data]
+"horde_model_reference" = ["data/*.json", "py.typed"]
+
 [tool.setuptools.exclude-package-data]
 "*" = ["*.webp", "*.png", "*.jpg", "*.ckpt", "*.pt", "*.safetensors"]
 

{horde_model_reference-5.2.0 → horde_model_reference-5.3.0}/scripts/sync/sync_github_references.py

@@ -386,6 +386,21 @@ def main() -> int:
         )
         return 1
 
+    # Fail fast on missing GitHub authentication *before* entering the watch loop or a
+    # one-shot run, so a misconfigured deployment exits loudly at startup instead of
+    # silently polling and only erroring when the first change appears. Skipped for
+    # dry-run / offline (--no-pr) runs, which never push or open PRs.
+    if not github_sync_settings.dry_run and not github_sync_settings.no_pr:
+        from horde_model_reference.sync.config import github_app_settings
+
+        if not (github_app_settings.is_configured() or github_sync_settings.github_token):
+            logger.error(
+                "No GitHub authentication configured. Set HORDE_GITHUB_SYNC_GITHUB_TOKEN (a PAT), "
+                "or GITHUB_APP_ID + GITHUB_APP_PRIVATE_KEY_PATH/GITHUB_APP_PRIVATE_KEY (GitHub App). "
+                "Refusing to start to avoid a watch loop that cannot create PRs."
+            )
+            return 1
+
     # Watch mode
     if github_sync_settings.watch_mode:
         watch_manager = WatchModeManager(

{horde_model_reference-5.2.0 → horde_model_reference-5.3.0}/src/horde_model_reference/__init__.py

@@ -290,6 +290,11 @@ class HordeModelReferenceSettings(BaseSettings):
     replicate_mode: ReplicateMode = ReplicateMode.REPLICA
     """Indicates if copies of the model reference are canonical or replicated. Clients should always be replicas."""
 
+    offline: bool = False
+    """Read references straight from local disk and never download (no GitHub / PRIMARY API / Redis). \
+Intended for subprocesses whose parent already downloaded and wrote the converted reference files. \
+When True, primary_api_url, github_seed, and redis are ignored and a LocalReadOnlyBackend is used."""
+
     make_folders: bool = False
     """Whether to create the default model reference folders on initialization."""
 
@@ -469,6 +474,16 @@ Allows service to fully initialize before background tasks begin."""
             f"Validating settings for replicate_mode={self.replicate_mode} and "
             f"canonical_format={self.canonical_format}"
         )
+        if self.offline:
+            logger.info(
+                "offline=True: reading model references from local disk only. "
+                "primary_api_url, github_seed_enabled, and redis are ignored; no network access will occur."
+            )
+            if self.redis.use_redis is True:
+                self.redis.use_redis = False
+            if self.github_seed_enabled:
+                self.github_seed_enabled = False
+
         if self.replicate_mode == ReplicateMode.REPLICA and self.redis.use_redis is True:
             logger.warning(
                 "Redis settings detected in REPLICA mode. "

{horde_model_reference-5.2.0 → horde_model_reference-5.3.0}/src/horde_model_reference/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '5.2.0'
-__version_tuple__ = version_tuple = (5, 2, 0)
+__version__ = version = '5.3.0'
+__version_tuple__ = version_tuple = (5, 3, 0)
 
-__commit_id__ = commit_id = 'g252799263'
+__commit_id__ = commit_id = 'gea166d555'

{horde_model_reference-5.2.0 → horde_model_reference-5.3.0}/src/horde_model_reference/backends/__init__.py

@@ -6,6 +6,7 @@ for fetching model reference data from different sources:
 - FileSystemBackend: PRIMARY mode - reads/writes local JSON files
 - GitHubBackend: REPLICA mode - downloads from GitHub with legacy conversion
 - HTTPBackend: REPLICA mode - fetches from PRIMARY API with GitHub fallback
+- LocalReadOnlyBackend: REPLICA mode - reads local JSON files, never downloads (offline subprocesses)
 - RedisBackend: PRIMARY mode wrapper - adds distributed caching (requires `redis` extra)
 
 Each backend is designed for specific replication modes and use cases.
@@ -19,6 +20,7 @@ from .base import ModelReferenceBackend
 from .filesystem_backend import FileSystemBackend
 from .github_backend import GitHubBackend
 from .http_backend import HTTPBackend
+from .local_readonly_backend import LocalReadOnlyBackend
 from .replica_backend_base import ReplicaBackendBase
 
 if TYPE_CHECKING:
@@ -28,6 +30,7 @@ __all__ = [
     "FileSystemBackend",
     "GitHubBackend",
     "HTTPBackend",
+    "LocalReadOnlyBackend",
     "ModelReferenceBackend",
     "RedisBackend",
     "ReplicaBackendBase",

horde_model_reference-5.3.0/src/horde_model_reference/backends/local_readonly_backend.py

@@ -0,0 +1,144 @@
+"""Offline, read-only backend that serves model references straight from local disk.
+
+This backend exists for the worker -> multi-subprocess paradigm. The parent process owns *all*
+reference downloading (via a REPLICA backend) and writes the converted v2 JSON to ``base_path``;
+every subprocess then constructs a :class:`LocalReadOnlyBackend` that reads those files and is
+structurally incapable of reaching the network. This removes the per-subprocess
+download/convert pipeline that otherwise runs once in every spawned interpreter.
+
+It is a REPLICA-mode backend with ``supports_writes() == False`` so the manager skips the
+write-path machinery (pending queue, group stores, audit). Staleness is purely mtime/TTL based
+(inherited from :class:`ReplicaBackendBase`), so a parent refresh that rewrites a category file is
+picked up on the next reload without any network access.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, override
+
+import httpx
+from loguru import logger
+
+from horde_model_reference import ReplicateMode, horde_model_reference_paths
+from horde_model_reference.backends.replica_backend_base import ReplicaBackendBase
+from horde_model_reference.meta_consts import MODEL_REFERENCE_CATEGORY
+
+
+class LocalReadOnlyBackend(ReplicaBackendBase):
+    """Read converted v2 references from ``base_path`` on disk; never download or convert."""
+
+    def __init__(
+        self,
+        *,
+        base_path: str | Path = horde_model_reference_paths.base_path,
+        cache_ttl_seconds: int = 60,
+    ) -> None:
+        """Initialize the offline read-only backend.
+
+        Args:
+            base_path: Base path the parent process wrote converted reference files to.
+            cache_ttl_seconds: TTL for the in-memory cache. mtime changes also invalidate.
+
+        """
+        super().__init__(mode=ReplicateMode.REPLICA, cache_ttl_seconds=cache_ttl_seconds)
+        self.base_path = Path(base_path)
+        logger.debug(f"LocalReadOnlyBackend initialized with base_path={self.base_path}")
+
+    @override
+    def _get_file_path_for_validation(self, category: MODEL_REFERENCE_CATEGORY) -> Path | None:
+        return horde_model_reference_paths.get_model_reference_file_path(category, base_path=self.base_path)
+
+    @override
+    def _get_legacy_file_path_for_validation(self, category: MODEL_REFERENCE_CATEGORY) -> Path | None:
+        return horde_model_reference_paths.get_legacy_model_reference_file_path(category, base_path=self.base_path)
+
+    def _read_json_from_disk(self, file_path: Path | None) -> dict[str, Any] | None:
+        if not file_path or not file_path.exists():
+            return None
+        try:
+            return json.loads(file_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as e:
+            logger.error(f"LocalReadOnlyBackend failed to read {file_path}: {e}")
+            return None
+
+    @override
+    def fetch_category(
+        self,
+        category: MODEL_REFERENCE_CATEGORY,
+        *,
+        force_refresh: bool = False,
+    ) -> dict[str, Any] | None:
+        with self._lock:
+            return self._fetch_with_cache(
+                category,
+                lambda: self._read_json_from_disk(self._get_file_path_for_validation(category)),
+                force_refresh=force_refresh,
+            )
+
+    @override
+    def fetch_all_categories(
+        self,
+        *,
+        force_refresh: bool = False,
+    ) -> dict[MODEL_REFERENCE_CATEGORY, dict[str, Any] | None]:
+        return {
+            category: self.fetch_category(category, force_refresh=force_refresh)
+            for category in MODEL_REFERENCE_CATEGORY
+        }
+
+    @override
+    async def fetch_category_async(
+        self,
+        category: MODEL_REFERENCE_CATEGORY,
+        *,
+        httpx_client: httpx.AsyncClient | None = None,
+        force_refresh: bool = False,
+    ) -> dict[str, Any] | None:
+        # Reads are local disk; there is no benefit to async file I/O for these small JSON files.
+        return self.fetch_category(category, force_refresh=force_refresh)
+
+    @override
+    async def fetch_all_categories_async(
+        self,
+        *,
+        httpx_client: httpx.AsyncClient | None = None,
+        force_refresh: bool = False,
+    ) -> dict[MODEL_REFERENCE_CATEGORY, dict[str, Any] | None]:
+        return {
+            category: await self.fetch_category_async(category, force_refresh=force_refresh)
+            for category in MODEL_REFERENCE_CATEGORY
+        }
+
+    @override
+    def get_category_file_path(self, category: MODEL_REFERENCE_CATEGORY) -> Path | None:
+        return self._get_file_path_for_validation(category)
+
+    @override
+    def get_all_category_file_paths(self) -> dict[MODEL_REFERENCE_CATEGORY, Path | None]:
+        return {category: self.get_category_file_path(category) for category in MODEL_REFERENCE_CATEGORY}
+
+    @override
+    def get_legacy_json(
+        self,
+        category: MODEL_REFERENCE_CATEGORY,
+        redownload: bool = False,
+    ) -> dict[str, Any] | None:
+        # Offline: redownload is a no-op; serve whatever the parent left on disk.
+        return self._read_json_from_disk(self._get_legacy_file_path_for_validation(category))
+
+    @override
+    def get_legacy_json_string(
+        self,
+        category: MODEL_REFERENCE_CATEGORY,
+        redownload: bool = False,
+    ) -> str | None:
+        file_path = self._get_legacy_file_path_for_validation(category)
+        if not file_path or not file_path.exists():
+            return None
+        try:
+            return file_path.read_text(encoding="utf-8")
+        except OSError as e:
+            logger.error(f"LocalReadOnlyBackend failed to read legacy {file_path}: {e}")
+            return None

{horde_model_reference-5.2.0 → horde_model_reference-5.3.0}/src/horde_model_reference/model_reference_manager.py

@@ -18,6 +18,7 @@ from horde_model_reference.backends import (
     FileSystemBackend,
     GitHubBackend,
     HTTPBackend,
+    LocalReadOnlyBackend,
     ModelReferenceBackend,
 )
 from horde_model_reference.group_aliases import GroupAliasStore
@@ -114,6 +115,7 @@ class ModelReferenceManager:
 
     _instance: ModelReferenceManager | None = None
     _replicate_mode: ReplicateMode = ReplicateMode.REPLICA
+    _offline: bool = False
     _prefetch_strategy: PrefetchStrategy = PrefetchStrategy.SYNC
     _deferred_prefetch_handle: DeferredPrefetchHandle | None = None
     _async_prefetch_task: asyncio.Task[None] | None = None
@@ -179,6 +181,7 @@ class ModelReferenceManager:
         base_path: str | Path,
         replicate_mode: ReplicateMode,
         audit_writer: AuditTrailWriter | None,
+        offline: bool = False,
     ) -> ModelReferenceBackend:
         """Create the appropriate backend based on mode and settings.
 
@@ -186,12 +189,23 @@ class ModelReferenceManager:
             base_path: Base path for model reference files.
             replicate_mode: The replication mode.
             audit_writer: Optional audit writer used by write-capable backends.
+            offline: If True, return a read-only local-disk backend that never downloads,
+                regardless of replicate_mode. Used by subprocesses whose parent owns downloading.
 
         Returns:
             ModelReferenceBackend: The configured backend instance.
 
         """
-        logger.debug(f"Creating backend with replicate_mode={replicate_mode}, base_path={base_path}")
+        logger.debug(
+            f"Creating backend with replicate_mode={replicate_mode}, base_path={base_path}, offline={offline}",
+        )
+        if offline:
+            logger.info("Using LocalReadOnlyBackend (offline=True); references are read from disk, never downloaded")
+            return LocalReadOnlyBackend(
+                base_path=base_path,
+                cache_ttl_seconds=horde_model_reference_settings.cache_ttl_seconds,
+            )
+
         if replicate_mode == ReplicateMode.PRIMARY:
             logger.debug("Creating backend for PRIMARY mode")
 
@@ -276,6 +290,7 @@ class ModelReferenceManager:
         base_path: str | Path = horde_model_reference_paths.base_path,
         replicate_mode: ReplicateMode = horde_model_reference_settings.replicate_mode,
         prefetch_strategy: PrefetchStrategy = PrefetchStrategy.LAZY,
+        offline: bool = horde_model_reference_settings.offline,
     ) -> ModelReferenceManager:
         """Create a new instance of ModelReferenceManager.
 
@@ -298,6 +313,10 @@ class ModelReferenceManager:
             prefetch_strategy: Controls whether initial cache warm-up is skipped (LAZY/NONE),
                 performed synchronously, deferred, or executed via background async task.
                 Defaults to PrefetchStrategy.LAZY.
+            offline: If True, read references from local disk only via LocalReadOnlyBackend and never
+                download (no GitHub / PRIMARY API / Redis), regardless of replicate_mode. Intended for
+                subprocesses whose parent already downloaded the reference files.
+                Defaults to horde_model_reference_settings.offline.
 
         Returns:
             ModelReferenceManager: The singleton instance of ModelReferenceManager.
@@ -330,8 +349,15 @@ class ModelReferenceManager:
                         base_path=base_path,
                         replicate_mode=replicate_mode,
                         audit_writer=audit_writer,
+                        offline=offline,
                     )
 
+                # Offline backends are REPLICA-shaped regardless of the requested mode; align the
+                # manager's recorded mode to the backend so the mode-match assertion below holds and
+                # downstream code does not assume PRIMARY write capability.
+                if offline:
+                    replicate_mode = backend.replicate_mode
+
                 backend_mode = backend.replicate_mode
                 if backend_mode != replicate_mode:
                     raise RuntimeError(
@@ -341,6 +367,7 @@ class ModelReferenceManager:
 
                 cls._instance.backend = backend
                 cls._instance._replicate_mode = replicate_mode
+                cls._instance._offline = offline
                 if backend.supports_writes():
                     cls._instance._audit_writer = audit_writer
                     cls._instance._pending_queue_service = cls._build_pending_queue_service(
@@ -377,7 +404,12 @@ class ModelReferenceManager:
                         "ModelReferenceManager is a singleton and has already been instantiated "
                         "with a different backend."
                     )
-                if replicate_mode != cls._instance._replicate_mode:
+                if offline != cls._instance._offline:
+                    raise RuntimeError(
+                        "ModelReferenceManager is a singleton and has already been instantiated with a different "
+                        f"offline setting.\nExisting offline={cls._instance._offline}; new offline={offline}."
+                    )
+                if not offline and replicate_mode != cls._instance._replicate_mode:
                     raise RuntimeError(
                         "ModelReferenceManager is a singleton and has already been instantiated with different "
                         "settings.\nExisting settings: "
@@ -511,6 +543,11 @@ class ModelReferenceManager:
         """Return the prefetch strategy originally configured for this manager."""
         return self._prefetch_strategy
 
+    @property
+    def offline(self) -> bool:
+        """Return whether this manager reads from local disk only (never downloads)."""
+        return self._offline
+
     @property
     def pending_queue_service(self) -> PendingQueueService | None:
         """Return the pending queue service when queueing is enabled."""

{horde_model_reference-5.2.0 → horde_model_reference-5.3.0/src/horde_model_reference.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: horde_model_reference
-Version: 5.2.0
+Version: 5.3.0
 Summary: A helper library providing a way to work with the lists of generation models, utility models, and any other related files required for the AI-Horde ecosystem.
 Author-email: tazlin <tazlin.on.github@gmail.com>, db0 <mail@dbzer0.com>
 License:                     GNU AFFERO GENERAL PUBLIC LICENSE