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

horde_model_reference-5.3.2/.env.example

@@ -0,0 +1,514 @@
+# 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-03-26 22:29:13
+
+# 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
+
+# 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`
+# 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 in seconds for category audit results. Uses Redis if available, otherwise in-memory caching.
+# HORDE_MODEL_REFERENCE_AUDIT_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, audit_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
+
+
+# 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-03-26 22:29:13
+
+# 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
+
+# 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`
+# 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 in seconds for category audit results. Uses Redis if available, otherwise in-memory caching.
+# HORDE_MODEL_REFERENCE_AUDIT_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, audit_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.3.0/src/horde_model_reference.egg-info → horde_model_reference-5.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: horde_model_reference
-Version: 5.3.0
+Version: 5.3.2
 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.3.0 → horde_model_reference-5.3.2}/src/horde_model_reference/__init__.py

@@ -586,11 +586,13 @@ from .model_reference_records import (  # noqa: E402
 )
 from .on_disk_layout import (  # noqa: E402
     COMPONENT_PURPOSE_FOLDERS,
+    PresenceSummary,
     category_folder,
     component_relative_path,
     file_paths_for,
     free_bytes_for,
     is_present,
+    presence_summary,
     resolve_weights_root,
 )
 from .download_engine import (  # noqa: E402
@@ -671,6 +673,7 @@ __all__ = [
     "PopularModelResult",
     "Predicate",
     "PrefetchStrategy",
+    "PresenceSummary",
     "SafetyCheckerFields",
     "SourceSelector",
     "StaticModelProvider",
@@ -699,6 +702,7 @@ __all__ = [
     "horde_model_reference_paths",
     "is_present",
     "md5_of",
+    "presence_summary",
     "register_category",
     "register_image_baseline",
     "register_record_type",

{horde_model_reference-5.3.0 → horde_model_reference-5.3.2}/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.3.0'
-__version_tuple__ = version_tuple = (5, 3, 0)
+__version__ = version = '5.3.2'
+__version_tuple__ = version_tuple = (5, 3, 2)
 
-__commit_id__ = commit_id = 'gea166d555'
+__commit_id__ = commit_id = 'g98dc41d57'

{horde_model_reference-5.3.0 → horde_model_reference-5.3.2}/src/horde_model_reference/backends/http_backend.py

@@ -6,6 +6,7 @@ with fallback to GitHub if the PRIMARY is unavailable.
 
 from __future__ import annotations
 
+import json
 from pathlib import Path
 from typing import Any, override
 
@@ -13,7 +14,7 @@ import httpx
 from loguru import logger
 from tenacity import RetryError
 
-from horde_model_reference import ReplicateMode, horde_model_reference_settings
+from horde_model_reference import ReplicateMode, horde_model_reference_paths, horde_model_reference_settings
 from horde_model_reference.backends.github_backend import GitHubBackend
 from horde_model_reference.backends.replica_backend_base import ReplicaBackendBase
 from horde_model_reference.http_retry import (
@@ -87,6 +88,28 @@ class HTTPBackend(ReplicaBackendBase):
         """Get the PRIMARY API URL for a category."""
         return f"{self._primary_api_url}/model_references/v2/{category.value}"
 
+    def _persist_to_disk(self, category: MODEL_REFERENCE_CATEGORY, data: dict[str, Any]) -> None:
+        """Write fetched v2 data to disk so offline replicas and restarts can read it.
+
+        The GitHub fallback already writes converted files to disk; this materializes the (otherwise
+        memory-only) PRIMARY-API responses too, so an offline LocalReadOnlyBackend (e.g. a worker
+        subprocess) reading the same base_path sees the references the parent fetched.
+        """
+        base_path = getattr(self._github_backend, "base_path", None)
+        if base_path is None:
+            return
+        try:
+            file_path = horde_model_reference_paths.get_model_reference_file_path(
+                category,
+                base_path=base_path,
+            )
+            if file_path is None:
+                return
+            file_path.parent.mkdir(parents=True, exist_ok=True)
+            file_path.write_text(json.dumps(data), encoding="utf-8")
+        except OSError as e:
+            logger.warning(f"HTTPBackend failed to persist {category} to disk: {e}")
+
     def _legacy_category_api_url(self, category: MODEL_REFERENCE_CATEGORY) -> str:
         """Get the legacy PRIMARY API URL for a category."""
         return f"{self._primary_api_url}/model_references/v1/{category.value}"
@@ -259,7 +282,10 @@ class HTTPBackend(ReplicaBackendBase):
         if force_refresh or self.should_fetch_data(category):
             data = self._fetch_from_primary(category)
 
-            if data is None and self._enable_github_fallback:
+            if data is not None:
+                # The GitHub fallback writes converted files itself; persist PRIMARY hits too.
+                self._persist_to_disk(category, data)
+            elif self._enable_github_fallback:
                 logger.info(f"Falling back to GitHub for {category}")
                 self._github_fallbacks += 1
                 data = self._github_backend.fetch_category(category, force_refresh=force_refresh)
@@ -316,7 +342,10 @@ class HTTPBackend(ReplicaBackendBase):
                 async with httpx.AsyncClient() as client:
                     data = await self._fetch_from_primary_async(category, client)
 
-            if data is None and self._enable_github_fallback:
+            if data is not None:
+                # The GitHub fallback writes converted files itself; persist PRIMARY hits too.
+                self._persist_to_disk(category, data)
+            elif self._enable_github_fallback:
                 logger.info(f"Falling back to GitHub for {category} (async)")
                 self._github_fallbacks += 1
                 data = await self._github_backend.fetch_category_async(