horde-model-reference 2.1.3__tar.gz → 3.0.0__tar.gz

horde_model_reference-3.0.0/.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
+
+# URL of PRIMARY server API for REPLICA clients to fetch model references from. If None, REPLICA clients will only use GitHub. Example: https://stablehorde.net/api/model_references/
+# HORDE_MODEL_REFERENCE_PRIMARY_API_URL=https://stablehorde.net/api/model_references/
+
+# 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
+
+# URL of PRIMARY server API for REPLICA clients to fetch model references from. If None, REPLICA clients will only use GitHub. Example: https://stablehorde.net/api/model_references/
+# HORDE_MODEL_REFERENCE_PRIMARY_API_URL=https://stablehorde.net/api/model_references/
+
+# 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-2.1.3 → horde_model_reference-3.0.0}/.env.primary.example

@@ -22,7 +22,7 @@ HORDE_MODEL_REFERENCE_CACHE_TTL_SECONDS=60
 # - 'legacy': v1 API has CRUD, v2 API is read-only (converts from legacy to v2)
 # - 'v2': v2 API has CRUD, v1 API is read-only (converts from v2 to legacy)
 # Default is 'v2' but set to 'legacy' during transition period
-HORDE_MODEL_REFERENCE_CANONICAL_FORMAT=legacy
+HORDE_MODEL_REFERENCE_CANONICAL_FORMAT=LEGACY
 
 # ============================================================================
 # GitHub Seeding (First-Time Setup)
@@ -37,19 +37,19 @@ HORDE_MODEL_REFERENCE_GITHUB_SEED_ENABLED=false
 # ============================================================================
 
 # Enable Redis for distributed caching (required for multi-worker setups)
-# HORDE_MODEL_REFERENCE_REDIS_USE_REDIS=true
+# HORDE_MODEL_REFERENCE_REDIS__USE_REDIS=true
 
 # Redis connection URL
-# HORDE_MODEL_REFERENCE_REDIS_URL=redis://redis:6379/0
+# HORDE_MODEL_REFERENCE_REDIS__URL=redis://redis:6379/0
 
 # Redis connection pool size
-# HORDE_MODEL_REFERENCE_REDIS_POOL_SIZE=10
+# HORDE_MODEL_REFERENCE_REDIS__POOL_SIZE=10
 
 # Redis TTL (uses cache_ttl_seconds if not specified)
-# HORDE_MODEL_REFERENCE_REDIS_TTL_SECONDS=60
+# HORDE_MODEL_REFERENCE_REDIS__TTL_SECONDS=60
 
 # Enable pub/sub for cache invalidation across workers
-# HORDE_MODEL_REFERENCE_REDIS_USE_PUBSUB=true
+# HORDE_MODEL_REFERENCE_REDIS__USE_PUBSUB=true
 
 # ============================================================================
 # Data Directory

{horde_model_reference-2.1.3 → horde_model_reference-3.0.0}/.github/workflows/codeql.yml

@@ -53,7 +53,7 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v4
+      uses: actions/checkout@v6
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL

{horde_model_reference-2.1.3 → horde_model_reference-3.0.0}/.github/workflows/docker-validation.yml

@@ -24,7 +24,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Run hadolint
         uses: hadolint/hadolint-action@v3.1.0
@@ -35,6 +35,14 @@ jobs:
           output-file: hadolint-results.sarif
           no-fail: false
 
+      - name: Ensure valid SARIF file
+        if: always()
+        run: |
+          if [ ! -s hadolint-results.sarif ] || ! python3 -c "import json,sys; json.load(open(sys.argv[1]))" hadolint-results.sarif 2>/dev/null; then
+            rm -f hadolint-results.sarif
+            echo '{"version":"2.1.0","$schema":"https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json","runs":[{"tool":{"driver":{"name":"hadolint","rules":[]}},"results":[]}]}' > hadolint-results.sarif
+          fi
+
       - name: Upload hadolint SARIF results
         if: always()
         uses: github/codeql-action/upload-sarif@v3
@@ -47,7 +55,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
@@ -99,7 +107,7 @@ jobs:
           - docker-compose.redis.yml
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Validate ${{ matrix.compose-file }}
         run: |
@@ -125,7 +133,7 @@ jobs:
           - 6379:6379
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
@@ -240,10 +248,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Run Trivy vulnerability scanner on Dockerfile
-        uses: aquasecurity/trivy-action@0.28.0
+        uses: aquasecurity/trivy-action@0.35.0
         with:
           scan-type: 'config'
           scan-ref: 'Dockerfile'
@@ -263,7 +271,7 @@ jobs:
     needs: docker-build-check
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
@@ -279,7 +287,7 @@ jobs:
           cache-from: type=gha
 
       - name: Run Trivy vulnerability scanner on image
-        uses: aquasecurity/trivy-action@0.28.0
+        uses: aquasecurity/trivy-action@0.35.0
         with:
           scan-type: 'image'
           image-ref: 'horde-model-reference:scan'