feat(models): add db-backed model access overrides

.env.template

@@ -9,6 +9,12 @@
 # Accepts values like "10M", "1G", "500K" (default: 10M)
 # BODY_SIZE_LIMIT=10M
 
+# Enable/disable Swagger UI at /swagger/index.html (default: true)
+# SWAGGER_ENABLED=true
+
+# Enable/disable pprof profiling routes at /debug/pprof/* (default: false)
+# PPROF_ENABLED=false
+
 # Enable/disable provider-native passthrough routes under /p/{provider}/{endpoint} (default: true)
 # ENABLE_PASSTHROUGH_ROUTES=true
 
@@ -37,27 +43,93 @@
 # METRICS_ENDPOINT=/metrics
 
 # Cache Configuration
-# Type:
-# - "local" (default) for single instance,
-# - "redis" for multiple instances
-# CACHE_TYPE=local
+# Model cache uses the local filesystem by default.
+# Set REDIS_URL to use Redis-backed caching instead.
 
-# Redis Configuration (only used when CACHE_TYPE=redis)
+# Redis Configuration
 # REDIS_URL=redis://localhost:6379
 # REDIS_KEY_MODELS=gomodel:models
 # REDIS_TTL_MODELS=86400
+# How often to refresh the model registry cache in seconds (default: 3600)
+# CACHE_REFRESH_INTERVAL=3600
 # REDIS_KEY_RESPONSES=gomodel:response:
 # REDIS_TTL_RESPONSES=3600
 # Opt-in when config.yaml has no cache.response.simple block (e.g. env-only deploys). Omit otherwise.
 # RESPONSE_CACHE_SIMPLE_ENABLED=true
 
+# Opt-in when config.yaml has no cache.response.semantic block (e.g. env-only deploys). Omit otherwise.
+# SEMANTIC_CACHE_ENABLED=true
+# Similarity threshold between 0 and 1 (default: 0.92)
+# SEMANTIC_CACHE_THRESHOLD=0.92
+# Semantic cache entry TTL in seconds (default: 3600)
+# SEMANTIC_CACHE_TTL=3600
+# Number of recent conversation messages to embed (default: 3)
+# SEMANTIC_CACHE_MAX_CONV_MESSAGES=3
+# Exclude the system prompt from semantic cache keys (default: false)
+# SEMANTIC_CACHE_EXCLUDE_SYSTEM_PROMPT=false
+# Embedding provider name used for semantic cache
+# SEMANTIC_CACHE_EMBEDDER_PROVIDER=openai
+# Optional embedding model override
+# SEMANTIC_CACHE_EMBEDDER_MODEL=text-embedding-3-small
+# Vector store backend: qdrant, pgvector, pinecone, or weaviate
+# SEMANTIC_CACHE_VECTOR_STORE_TYPE=qdrant
+# Qdrant
+# SEMANTIC_CACHE_QDRANT_URL=http://localhost:6333
+# SEMANTIC_CACHE_QDRANT_COLLECTION=gomodel_semantic
+# SEMANTIC_CACHE_QDRANT_API_KEY=
+# pgvector
+# SEMANTIC_CACHE_PGVECTOR_URL=postgres://user:pass@localhost:5432/gomodel
+# SEMANTIC_CACHE_PGVECTOR_TABLE=gomodel_semantic_cache
+# SEMANTIC_CACHE_PGVECTOR_DIMENSION=1536
+# Pinecone
+# SEMANTIC_CACHE_PINECONE_HOST=https://your-index.svc.region.pinecone.io
+# SEMANTIC_CACHE_PINECONE_API_KEY=
+# SEMANTIC_CACHE_PINECONE_NAMESPACE=
+# SEMANTIC_CACHE_PINECONE_DIMENSION=1536
+# Weaviate
+# SEMANTIC_CACHE_WEAVIATE_URL=http://localhost:8080
+# SEMANTIC_CACHE_WEAVIATE_CLASS=GomodelSemanticCache
+# SEMANTIC_CACHE_WEAVIATE_API_KEY=
+
 # Optional: Custom cache directory for local file cache
 # GOMODEL_CACHE_DIR=.cache
 
 # External model metadata registry (provides pricing, capabilities, context window, etc.)
 # Set to empty string to disable (default: ENTERPILOT/ai-model-list on GitHub)
 # MODEL_LIST_URL=https://raw.githubusercontent.com/ENTERPILOT/ai-model-list/refs/heads/main/models.min.json
 
+# Model Access Configuration
+# Process-wide default for concrete provider models when no persisted override exists (default: true)
+# Set to false to keep models unavailable until explicitly enabled by a model override
+# MODELS_ENABLED_BY_DEFAULT=true
+
+# Fallback & Workflow Configuration
+# Default translated-route fallback mode: auto, manual, or off (default: auto)
+# FEATURE_FALLBACK_MODE=auto
+# JSON file mapping model selectors to ordered fallback lists
+# Required when FEATURE_FALLBACK_MODE=manual (default example: config/fallback.example.json)
+# FALLBACK_MANUAL_RULES_PATH=config/fallback.example.json
+# How often to refresh persisted execution plans from storage (default: 1m)
+# EXECUTION_PLAN_REFRESH_INTERVAL=1m
+
+# LLM Client Resilience Configuration
+# Retry attempts for upstream provider calls (default: 3)
+# RETRY_MAX_RETRIES=3
+# Initial retry backoff duration (default: 1s)
+# RETRY_INITIAL_BACKOFF=1s
+# Maximum retry backoff duration (default: 30s)
+# RETRY_MAX_BACKOFF=30s
+# Exponential backoff factor (default: 2.0)
+# RETRY_BACKOFF_FACTOR=2.0
+# Random jitter factor applied to retry delays (default: 0.1)
+# RETRY_JITTER_FACTOR=0.1
+# Consecutive failures before opening the circuit breaker (default: 5)
+# CIRCUIT_BREAKER_FAILURE_THRESHOLD=5
+# Consecutive successes required to close the circuit breaker (default: 2)
+# CIRCUIT_BREAKER_SUCCESS_THRESHOLD=2
+# Circuit breaker open-state timeout duration (default: 30s)
+# CIRCUIT_BREAKER_TIMEOUT=30s
+
 # =============================================================================
 # Admin API & Dashboard Configuration
 # =============================================================================
@@ -160,18 +232,23 @@
 # =============================================================================
 # OpenAI
 # OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com/v1
 
 # Anthropic
 # ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=https://api.anthropic.com/v1
 
 # Google Gemini
 # GEMINI_API_KEY=...
+# GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
 
 # xAI (Grok)
 # XAI_API_KEY=...
+# XAI_BASE_URL=https://api.x.ai/v1
 
 # Groq
 # GROQ_API_KEY=gsk_...
+# GROQ_BASE_URL=https://api.groq.com/openai/v1
 
 # OpenRouter (default base URL: https://openrouter.ai/api/v1)
 # OPENROUTER_API_KEY=sk-or-...
@@ -189,6 +266,7 @@
 # ORACLE_BASE_URL=https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/v1
 
 # Ollama (local LLM server)
-# Note: Ollama doesn't require an API key
+# Note: Ollama doesn't require an API key, but one can be sent for secured deployments
+# OLLAMA_API_KEY=...
 # Set base URL to enable (default: http://localhost:11434/v1)
 # OLLAMA_BASE_URL=http://localhost:11434/v1

CLAUDE.md

@@ -109,7 +109,7 @@ Full reference: `.env.template` and `config/config.yaml`
 - **Storage:** `STORAGE_TYPE` (sqlite), `SQLITE_PATH` (data/gomodel.db), `POSTGRES_URL`, `MONGODB_URL`
 - **Audit logging:** `LOGGING_ENABLED` (false), `LOGGING_LOG_BODIES` (false), `LOGGING_LOG_HEADERS` (false), `LOGGING_RETENTION_DAYS` (30)
 - **Usage tracking:** `USAGE_ENABLED` (true), `ENFORCE_RETURNING_USAGE_DATA` (true), `USAGE_RETENTION_DAYS` (90)
-- **Cache:** `CACHE_TYPE` (local), `CACHE_REFRESH_INTERVAL` (3600s), `REDIS_URL`, `REDIS_KEY_MODELS`, `REDIS_TTL_MODELS`. Exact response cache uses `cache.response.simple` in `config.yaml` (optional `enabled`); `REDIS_KEY_RESPONSES`, `REDIS_TTL_RESPONSES`, and `REDIS_URL` apply only when that block exists or when `RESPONSE_CACHE_SIMPLE_ENABLED=true`. Semantic response cache uses `cache.response.semantic` (optional `enabled`); when enabled, `embedder.provider` must name a key in the top-level `providers` map (no default embedder). At runtime that key is resolved against the same env-merged, credential-filtered provider set as routing (not YAML-only), so env-only credentials apply. `vector_store.type` must be set explicitly to one of `qdrant`, `pgvector`, `pinecone`, `weaviate` (each has its own nested config and `SEMANTIC_CACHE_*` env vars). Tuning via `SEMANTIC_CACHE_*` applies when the semantic block exists or `SEMANTIC_CACHE_ENABLED=true`.
+- **Cache:** `CACHE_REFRESH_INTERVAL` (3600s), `REDIS_URL`, `REDIS_KEY_MODELS`, `REDIS_TTL_MODELS`. Exact response cache uses `cache.response.simple` in `config.yaml` (optional `enabled`); `REDIS_KEY_RESPONSES`, `REDIS_TTL_RESPONSES`, and `REDIS_URL` apply only when that block exists or when `RESPONSE_CACHE_SIMPLE_ENABLED=true`. Semantic response cache uses `cache.response.semantic` (optional `enabled`); when enabled, `embedder.provider` must name a key in the top-level `providers` map (no default embedder). At runtime that key is resolved against the same env-merged, credential-filtered provider set as routing (not YAML-only), so env-only credentials apply. `vector_store.type` must be set explicitly to one of `qdrant`, `pgvector`, `pinecone`, `weaviate` (each has its own nested config and `SEMANTIC_CACHE_*` env vars). Tuning via `SEMANTIC_CACHE_*` applies when the semantic block exists or `SEMANTIC_CACHE_ENABLED=true`.
 - **HTTP client:** `HTTP_TIMEOUT` (600s), `HTTP_RESPONSE_HEADER_TIMEOUT` (600s)
 - **Resilience:** Configured via `config/config.yaml` — global `resilience.retry.*` and `resilience.circuit_breaker.*` defaults with optional per-provider overrides under `providers.<name>.resilience.retry.*` and `providers.<name>.resilience.circuit_breaker.*`. Retry defaults: `max_retries` (3), `initial_backoff` (1s), `max_backoff` (30s), `backoff_factor` (2.0), `jitter_factor` (0.1). Circuit breaker defaults: `failure_threshold` (5), `success_threshold` (2), `timeout` (30s)
 - **Metrics:** `METRICS_ENABLED` (false), `METRICS_ENDPOINT` (/metrics)

README.md

@@ -180,7 +180,6 @@ Key settings:
 | `ENABLE_PASSTHROUGH_ROUTES` | `true` | Enable provider-native passthrough routes under `/p/{provider}/...` |
 | `ALLOW_PASSTHROUGH_V1_ALIAS` | `true` | Allow `/p/{provider}/v1/...` aliases while keeping `/p/{provider}/...` canonical |
 | `ENABLED_PASSTHROUGH_PROVIDERS` | `openai,anthropic` | Comma-separated list of enabled passthrough providers |
-| `CACHE_TYPE` | `local` | Cache backend (`local` or `redis`) |
 | `STORAGE_TYPE` | `sqlite` | Storage backend (`sqlite`, `postgresql`, `mongodb`) |
 | `METRICS_ENABLED` | `false` | Enable Prometheus metrics |
 | `LOGGING_ENABLED` | `false` | Enable audit logging |

config/config.example.yaml

@@ -12,6 +12,9 @@ server:
   allow_passthrough_v1_alias: true # allow /p/{provider}/v1/... while keeping /p/{provider}/... canonical
   enabled_passthrough_providers: ["openai", "anthropic"] # providers enabled on /p/{provider}/...
 
+models:
+  enabled_by_default: true # env: MODELS_ENABLED_BY_DEFAULT; when false, concrete models stay unavailable until explicitly enabled by a model override
+
 cache:
   model:
     refresh_interval: 3600 # how often to refresh the model registry (seconds, default: 3600)

config/config.go

@@ -31,6 +31,7 @@ var bodySizeLimitRegex = regexp.MustCompile(`(?i)^(\d+)([KMG])?B?$`)
 // Config holds the application configuration.
 type Config struct {
 	Server         ServerConfig         `yaml:"server"`
+	Models         ModelsConfig         `yaml:"models"`
 	Cache          CacheConfig          `yaml:"cache"`
 	Storage        StorageConfig        `yaml:"storage"`
 	Logging        LogConfig            `yaml:"logging"`
@@ -128,6 +129,13 @@ type FallbackModelOverride struct {
 	Mode FallbackMode `yaml:"mode" json:"mode"`
 }
 
+// ModelsConfig holds global model access defaults.
+type ModelsConfig struct {
+	// EnabledByDefault controls whether concrete provider models are available
+	// when no persisted override exists. Default: true.
+	EnabledByDefault bool `yaml:"enabled_by_default" env:"MODELS_ENABLED_BY_DEFAULT"`
+}
+
 // FallbackConfig holds translated-route model fallback policy.
 type FallbackConfig struct {
 	// DefaultMode controls the fallback behavior when no per-model override exists.
@@ -863,6 +871,9 @@ func buildDefaultConfig() *Config {
 				"anthropic",
 			},
 		},
+		Models: ModelsConfig{
+			EnabledByDefault: true,
+		},
 		Cache: CacheConfig{
 			Model: ModelCacheConfig{
 				RefreshInterval: 3600,

docker-compose.yaml

@@ -14,7 +14,6 @@ services:
       - .env
     environment:
       # Cache configuration
-      - CACHE_TYPE=redis
       - REDIS_URL=redis://redis:6379
       # Metrics
       - METRICS_ENABLED=true

docs/2026-03-23_benchmark_scripts/gateway-comparison/run-benchmark.sh

@@ -231,7 +231,6 @@ LOGGING_ENABLED=false \
 USAGE_ENABLED=false \
 STORAGE_TYPE=sqlite \
 SQLITE_PATH="/tmp/gomodel-bench.db" \
-CACHE_TYPE=local \
 GOMODEL_CACHE_DIR="/tmp/gomodel-bench-cache" \
 ADMIN_ENDPOINTS_ENABLED=false \
 ADMIN_UI_ENABLED=false \

docs/advanced/configuration.mdx

@@ -47,7 +47,6 @@ The most common way to configure GOModel. Set any of the variables below to over
 
 | Variable            | Description                       | Default          |
 | ------------------- | --------------------------------- | ---------------- |
-| `CACHE_TYPE`        | Cache backend: `local` or `redis` | `local`          |
 | `GOMODEL_CACHE_DIR` | Directory for local cache files   | `.cache`         |
 | `REDIS_URL`         | Redis connection URL              | _(empty)_        |
 | `REDIS_KEY_MODELS`     | Redis key for model cache           | `gomodel:models`    |
@@ -192,9 +191,9 @@ server:
   master_key: "my-secret-key"
 
 cache:
-  type: redis
-  redis:
-    url: "redis://my-redis:6379"
+  model:
+    redis:
+      url: "redis://my-redis:6379"
 
 providers:
   openai:

helm/templates/_helpers.tpl

@@ -84,17 +84,6 @@ Determine the Redis URL - either from values or auto-generated for subchart
 {{- end }}
 {{- end }}
 
-{{/*
-Determine the cache type - auto-set to redis if subchart is enabled
-*/}}
-{{- define "gomodel.cacheType" -}}
-{{- if .Values.redis.enabled }}
-{{- "redis" }}
-{{- else }}
-{{- .Values.cache.type }}
-{{- end }}
-{{- end }}
-
 {{/*
 Create the image reference
 */}}

helm/templates/configmap.yaml

@@ -7,8 +7,7 @@ metadata:
 data:
   PORT: {{ .Values.server.port | quote }}
   BODY_SIZE_LIMIT: {{ .Values.server.bodySizeLimit | quote }}
-  CACHE_TYPE: {{ include "gomodel.cacheType" . | quote }}
-  {{- if or .Values.redis.enabled (eq .Values.cache.type "redis") }}
+  {{- if or .Values.redis.enabled .Values.cache.redis.url }}
   REDIS_KEY_MODELS: {{ .Values.cache.redis.keyModels | default "gomodel:models" | quote }}
   REDIS_KEY_RESPONSES: {{ .Values.cache.redis.keyResponses | default "gomodel:response:" | quote }}
   REDIS_TTL_MODELS: {{ .Values.cache.redis.ttlModels | default 86400 | quote }}

helm/templates/deployment.yaml

@@ -54,12 +54,7 @@ spec:
                   name: {{ include "gomodel.fullname" . }}
                   key: BODY_SIZE_LIMIT
             # Cache configuration
-            - name: CACHE_TYPE
-              valueFrom:
-                configMapKeyRef:
-                  name: {{ include "gomodel.fullname" . }}
-                  key: CACHE_TYPE
-            {{- if or .Values.redis.enabled (eq .Values.cache.type "redis") }}
+            {{- if or .Values.redis.enabled .Values.cache.redis.url }}
             - name: REDIS_URL
               valueFrom:
                 secretKeyRef:

helm/templates/secret.yaml

@@ -8,7 +8,7 @@ metadata:
 type: Opaque
 stringData:
 {{- include "gomodel.providerSecretData" . | nindent 2 }}
-  {{- if or .Values.redis.enabled (eq .Values.cache.type "redis") }}
+  {{- if or .Values.redis.enabled .Values.cache.redis.url }}
   REDIS_URL: {{ include "gomodel.redisUrl" . | quote }}
   {{- end }}
 {{- end }}

helm/values.schema.json

@@ -27,33 +27,6 @@
         }
       }
     },
-    {
-      "if": {
-        "properties": {
-          "cache": {
-            "properties": { "type": { "const": "redis" } }
-          },
-          "redis": {
-            "properties": { "enabled": { "const": false } }
-          }
-        }
-      },
-      "then": {
-        "properties": {
-          "cache": {
-            "properties": {
-              "redis": {
-                "properties": {
-                  "url": { "minLength": 1 }
-                },
-                "required": ["url"]
-              }
-            },
-            "required": ["redis"]
-          }
-        }
-      }
-    },
     {
       "if": {
         "properties": {
@@ -262,10 +235,6 @@
     "cache": {
       "type": "object",
       "properties": {
-        "type": {
-          "type": "string",
-          "enum": ["local", "redis"]
-        },
         "redis": {
           "type": "object",
           "properties": {

helm/values.yaml

@@ -91,12 +91,10 @@ providers:
 
 # Cache configuration
 cache:
-  # -- Cache type: "local" or "redis"
-  type: "redis"
-
   redis:
     # -- Redis connection URL (e.g., "redis://redis:6379")
-    # If redis.enabled is true, this is auto-configured to use the subchart
+    # If redis.enabled is true, this is auto-configured to use the subchart.
+    # Set this explicitly to use an external Redis instance instead.
     url: ""
     # -- Redis key prefix for storing the model cache
     keyModels: "gomodel:models"