feat(oracle): support configured models via env (#246)

* feat(oracle): support configured models via env

* docs(roadmap): restore oracle env item

Author: SantiagoDePolonia

.env.template

@@ -273,6 +273,9 @@
 # Oracle
 # ORACLE_API_KEY=...
 # ORACLE_BASE_URL=https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/v1
+# Optional fallback model inventory when Oracle's /models endpoint is unavailable
+# Comma-separated; whitespace around entries is ignored
+# ORACLE_MODELS=openai.gpt-oss-120b,xai.grok-3
 
 # Ollama (local LLM server)
 # Note: Ollama doesn't require an API key, but one can be sent for secured deployments

CLAUDE.md

@@ -115,4 +115,4 @@ Full reference: `.env.template` and `config/config.yaml`
 - **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)
 - **Guardrails:** Configured via `config/config.yaml` only (except `GUARDRAILS_ENABLED` env var)
-- **Providers:** `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `XAI_API_KEY`, `GROQ_API_KEY`, `OPENROUTER_API_KEY`, `ZAI_API_KEY`, `ZAI_BASE_URL` (optional Z.ai endpoint override), `AZURE_API_KEY`, `AZURE_BASE_URL` (Azure OpenAI deployment base URL), `AZURE_API_VERSION` (optional Azure API version), `ORACLE_API_KEY` (Oracle API key), `ORACLE_BASE_URL` (Oracle OpenAI-compatible base URL), `OLLAMA_BASE_URL`
+- **Providers:** `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `XAI_API_KEY`, `GROQ_API_KEY`, `OPENROUTER_API_KEY`, `ZAI_API_KEY`, `ZAI_BASE_URL` (optional Z.ai endpoint override), `AZURE_API_KEY`, `AZURE_BASE_URL` (Azure OpenAI deployment base URL), `AZURE_API_VERSION` (optional Azure API version), `ORACLE_API_KEY` (Oracle API key), `ORACLE_BASE_URL` (Oracle OpenAI-compatible base URL), `ORACLE_MODELS` (comma-separated Oracle fallback model inventory), `OLLAMA_BASE_URL`

GETTING_STARTED.md

@@ -199,6 +199,7 @@ Provider credentials:
 | `AZURE_API_VERSION`   | Azure OpenAI API version override (default: `2024-10-21`)                      |
 | `ORACLE_API_KEY`      | Oracle                                                                         |
 | `ORACLE_BASE_URL`     | Oracle OpenAI-compatible base URL                                              |
+| `ORACLE_MODELS`       | Oracle fallback model inventory (comma-separated, used when `/models` is unavailable) |
 | `OLLAMA_BASE_URL`     | Ollama (default: `http://localhost:11434/v1`)                                  |
 
 See `.env.template` for the full list of all configurable environment variables.
@@ -224,7 +225,7 @@ Ollama requires no API key. Even with no YAML and no `OLLAMA_BASE_URL` set, an O
 
 **Oracle requires both key and base URL.**
 `ORACLE_API_KEY` alone is not enough for auto-discovery. Set `ORACLE_BASE_URL` to the Oracle OpenAI-compatible endpoint, otherwise the provider is ignored.
-If your Oracle endpoint does not return a usable model list, configure `providers.<name>.models` in YAML to seed the router with explicit model IDs.
+If your Oracle endpoint does not return a usable model list, set `ORACLE_MODELS` or configure `providers.<name>.models` in YAML to seed the router with explicit model IDs.
 
 **Azure ships with a pinned API version by default.**
 If you do not set `AZURE_API_VERSION`, the gateway sends `api-version=2024-10-21`. Override it only when you need a different Azure API version.

README.md

@@ -42,6 +42,7 @@ docker run --rm -p 8080:8080 \
   -e AZURE_API_VERSION="2024-10-21" \
   -e ORACLE_API_KEY="your-oracle-key" \
   -e ORACLE_BASE_URL="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/v1" \
+  -e ORACLE_MODELS="openai.gpt-oss-120b,xai.grok-3" \
   -e OLLAMA_BASE_URL="http://host.docker.internal:11434/v1" \
   enterpilot/gomodel
 ```
@@ -81,6 +82,8 @@ Example model identifiers are illustrative and subject to change; consult provid
 ✅ Supported ❌ Unsupported
 
 For Z.ai's GLM Coding Plan, set `ZAI_BASE_URL=https://api.z.ai/api/coding/paas/v4`.
+For Oracle, set `ORACLE_MODELS=openai.gpt-oss-120b,xai.grok-3` when the
+upstream `/models` endpoint is unavailable.
 
 ---
 

config/config.example.yaml

@@ -231,6 +231,7 @@ providers:
   #   type: "oracle"
   #   base_url: "${ORACLE_BASE_URL}"
   #   api_key: "${ORACLE_API_KEY}"
+  #   # Optional when ORACLE_MODELS is set as a comma-separated env var instead.
   #   models:
   #     - openai.gpt-oss-120b
   #     - xai.grok-3

docs/advanced/config-yaml.mdx

@@ -15,6 +15,10 @@ especially:
 - custom provider instance names such as `ollama-a`, `ollama-b`, or `my-openai`
 - larger nested config that is easier to review in one file
 
+For Oracle specifically, a single fallback model list can now stay in env via
+`ORACLE_MODELS`. Use YAML when you need custom Oracle provider names or more
+than one Oracle provider instance.
+
 ## Priority Order
 
 Effective precedence is:

docs/advanced/configuration.mdx

@@ -143,7 +143,7 @@ Set these to automatically register providers. No YAML configuration required.
 | `OLLAMA_BASE_URL`    | Ollama (no API key needed)                        |
 
 Most providers can use a custom base URL via `<PROVIDER>_BASE_URL` (for example `OPENAI_BASE_URL`). OpenRouter defaults to `https://openrouter.ai/api/v1` and can be overridden with `OPENROUTER_BASE_URL`. Z.ai defaults to `https://api.z.ai/api/paas/v4`; set `ZAI_BASE_URL=https://api.z.ai/api/coding/paas/v4` for the GLM Coding Plan endpoint. Azure uses `AZURE_BASE_URL` for its deployment base URL and accepts an optional `AZURE_API_VERSION` override; otherwise it defaults to `2024-10-21`. Oracle requires `ORACLE_BASE_URL` because its OpenAI-compatible endpoint is region-specific.
-When using Oracle, `models:` also acts as a fallback inventory if the upstream endpoint does not expose a usable `/models` response.
+When using Oracle, set `ORACLE_MODELS` to a comma-separated list such as `openai.gpt-oss-120b,xai.grok-3` if the upstream endpoint does not expose a usable `/models` response. YAML `models:` remains available for custom provider names and multi-provider Oracle setups.
 
 For OpenRouter, GoModel also sends default attribution headers unless the request already sets them. Override those defaults with `OPENROUTER_SITE_URL` and `OPENROUTER_APP_NAME`.
 
@@ -250,6 +250,7 @@ export AZURE_API_KEY="..."           # Registers "azure" provider when paired wi
 export AZURE_BASE_URL="https://your-resource.openai.azure.com/openai/deployments/your-deployment"
 export ORACLE_API_KEY="..."          # Registers "oracle" provider when paired with ORACLE_BASE_URL
 export ORACLE_BASE_URL="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/v1"
+export ORACLE_MODELS="openai.gpt-oss-120b,xai.grok-3" # Optional fallback inventory for Oracle
 export OLLAMA_BASE_URL="http://localhost:11434/v1" # Registers "ollama" provider
 ```
 
@@ -294,14 +295,14 @@ providers:
 ```
 
 <Note>
-  For Oracle, prefer YAML configuration over env-only auto-discovery. Oracle
-  inference can work even when the upstream `/models` endpoint is unavailable,
-  so setting `models:` gives GoModel a reliable fallback inventory. See the
-  [Oracle guide](/guides/oracle) for the required OCI policy and a tested
-  configuration. Automatic model discovery is not yet a reliable, validated
-  path for this provider: GoModel can try Oracle's OpenAI-compatible `/models`
-  endpoint, but Oracle may not return a usable inventory there. OCI-native
-  Oracle model discovery is not integrated yet.
+  For Oracle, give GoModel a fallback inventory with `ORACLE_MODELS` or
+  `models:`. `ORACLE_MODELS` is enough for the default single-provider setup;
+  use YAML when you need custom provider names or multiple Oracle providers.
+  See the [Oracle guide](/guides/oracle) for the required OCI policy and a
+  tested configuration. Automatic model discovery is not yet a reliable,
+  validated path for this provider: GoModel can try Oracle's OpenAI-compatible
+  `/models` endpoint, but Oracle may not return a usable inventory there.
+  OCI-native Oracle model discovery is not integrated yet.
 </Note>
 
 ### Ollama (Local Models)

docs/guides/oracle.mdx

@@ -16,7 +16,7 @@ Flow:
 - Create an Oracle Generative AI API key.
 - Add an OCI IAM policy for `generativeaiapikey`.
 - Choose a supported Oracle region and model.
-- Prefer YAML configuration for Oracle so you can set `models:`.
+- Decide whether you want env-only `ORACLE_MODELS` or YAML `models:`.
 
 ## 1. Add the OCI policy
 
@@ -42,7 +42,18 @@ export ORACLE_API_KEY="..."
 
 ## 3. Configure Oracle in GoModel
 
-Use a YAML provider block and set `models:` explicitly:
+For the default single `oracle` provider, env-only configuration is enough:
+
+```bash
+export ORACLE_MODELS="openai.gpt-oss-120b,xai.grok-3"
+```
+
+`ORACLE_MODELS` is a comma-separated list. GoModel trims whitespace around each
+entry and uses the list as the fallback inventory when Oracle's `/models`
+endpoint is unavailable.
+
+Use a YAML provider block when you want a custom provider name, multiple Oracle
+providers, or prefer to keep the model list in `config.yaml`:
 
 ```yaml
 providers:
@@ -61,15 +72,15 @@ Why `models:` matters:
 - GoModel can fall back to the configured model list when `/models` is
   unavailable
 
-For Oracle, YAML is the recommended path. Environment-only auto-discovery is
-not enough if you need the configured-model fallback.
+If both are set, `ORACLE_MODELS` overrides YAML `models:` for the default
+`oracle` provider.
 
 ## Current status
 
 What is integrated today:
 
 - Oracle's OpenAI-compatible inference endpoints
-- manual model configuration through `models:`
+- manual model configuration through `ORACLE_MODELS` or `models:`
 - GoModel `/v1/models` from the configured-model fallback
 
 What is not yet validated as reliable:
@@ -79,11 +90,12 @@ What is not yet validated as reliable:
 What is not integrated yet:
 
 - native Oracle model auto-discovery through OCI APIs
-- automatic population of the Oracle model inventory without `models:`
+- automatic population of the Oracle model inventory without `ORACLE_MODELS` or
+  `models:`
 
 If Oracle later exposes a reliable `/models` endpoint for this API-key flow, or
-GoModel adds a separate OCI-native discovery path, this manual `models:`
-requirement can be relaxed.
+GoModel adds a separate OCI-native discovery path, this manual fallback
+configuration requirement can be relaxed.
 
 ## 4. Start GoModel
 
@@ -100,7 +112,7 @@ curl -s http://localhost:8080/v1/models
 Expected result:
 
 - a `200 OK`
-- an Oracle-owned model such as `oracle/openai.gpt-oss-120b`
+- a model such as `openai.gpt-oss-120b` with `owned_by: "oracle"`
 
 ## 6. Verify Responses
 
@@ -140,7 +152,8 @@ text.
   Usually means the Generative AI API key policy is missing, the region is
   wrong, or the model is not available to the account.
 - `model registry has no models`
-  Add `models:` to the Oracle provider config so GoModel can use the fallback.
+  Set `ORACLE_MODELS` or add `models:` to the Oracle provider config so GoModel
+  can use the fallback.
 - OCI CLI works but Oracle bearer requests fail
   These are different auth flows. OCI CLI uses API signing keys; Oracle
   Generative AI inference uses the Generative AI bearer API key.

internal/providers/config.go

@@ -44,6 +44,7 @@ func applyProviderEnvVars(raw map[string]config.RawProviderConfig, discovery map
 
 		apiKey := os.Getenv(envNames.APIKey)
 		explicitBaseURL := normalizeResolvedBaseURL(os.Getenv(envNames.BaseURL))
+		models := parseCSVEnvList(os.Getenv(envNames.Models))
 		apiVersion := ""
 		if spec.SupportsAPIVersion {
 			apiVersion = os.Getenv(envNames.APIVersion)
@@ -53,7 +54,7 @@ func applyProviderEnvVars(raw map[string]config.RawProviderConfig, discovery map
 			baseURL = spec.DefaultBaseURL
 		}
 
-		if apiKey == "" && baseURL == "" && apiVersion == "" {
+		if apiKey == "" && baseURL == "" && apiVersion == "" && len(models) == 0 {
 			continue
 		}
 
@@ -71,6 +72,9 @@ func applyProviderEnvVars(raw map[string]config.RawProviderConfig, discovery map
 			if apiVersion != "" {
 				existing.APIVersion = apiVersion
 			}
+			if len(models) > 0 {
+				existing.Models = models
+			}
 			result[targetKey] = existing
 		} else if ambiguous {
 			continue
@@ -83,6 +87,7 @@ func applyProviderEnvVars(raw map[string]config.RawProviderConfig, discovery map
 				APIKey:     apiKey,
 				BaseURL:    baseURL,
 				APIVersion: apiVersion,
+				Models:     models,
 			}
 		}
 	}
@@ -122,6 +127,7 @@ type providerEnvNames struct {
 	APIKey     string
 	BaseURL    string
 	APIVersion string
+	Models     string
 }
 
 func derivedEnvNames(providerType string) providerEnvNames {
@@ -130,6 +136,7 @@ func derivedEnvNames(providerType string) providerEnvNames {
 		APIKey:     prefix + "_API_KEY",
 		BaseURL:    prefix + "_BASE_URL",
 		APIVersion: prefix + "_API_VERSION",
+		Models:     prefix + "_MODELS",
 	}
 }
 
@@ -167,6 +174,26 @@ func normalizeResolvedBaseURL(value string) string {
 	return trimmed
 }
 
+func parseCSVEnvList(value string) []string {
+	if strings.TrimSpace(value) == "" {
+		return nil
+	}
+
+	items := strings.Split(value, ",")
+	values := make([]string, 0, len(items))
+	for _, item := range items {
+		trimmed := strings.TrimSpace(item)
+		if trimmed == "" {
+			continue
+		}
+		values = append(values, trimmed)
+	}
+	if len(values) == 0 {
+		return nil
+	}
+	return values
+}
+
 func isUnresolvedEnvPlaceholder(value string) bool {
 	if !strings.HasPrefix(value, "${") || !strings.HasSuffix(value, "}") || len(value) <= 3 {
 		return false

internal/providers/config_test.go

@@ -471,6 +471,7 @@ func TestApplyProviderEnvVars_DoesNotDiscoverAzureWithoutBaseURL(t *testing.T) {
 func TestApplyProviderEnvVars_DiscoversOracleFromExplicitEnvVars(t *testing.T) {
 	t.Setenv("ORACLE_API_KEY", "oracle-key")
 	t.Setenv("ORACLE_BASE_URL", "https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/v1")
+	t.Setenv("ORACLE_MODELS", " openai.gpt-oss-120b, xai.grok-3 ,, ")
 
 	got := applyProviderEnvVars(map[string]config.RawProviderConfig{}, testDiscoveryConfigs)
 
@@ -487,6 +488,9 @@ func TestApplyProviderEnvVars_DiscoversOracleFromExplicitEnvVars(t *testing.T) {
 	if p.BaseURL != "https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/v1" {
 		t.Errorf("BaseURL = %q, want Oracle base URL", p.BaseURL)
 	}
+	if len(p.Models) != 2 || p.Models[0] != "openai.gpt-oss-120b" || p.Models[1] != "xai.grok-3" {
+		t.Errorf("Models = %v, want [openai.gpt-oss-120b xai.grok-3]", p.Models)
+	}
 }
 
 func TestApplyProviderEnvVars_DoesNotDiscoverOracleWithoutBaseURL(t *testing.T) {
@@ -499,6 +503,31 @@ func TestApplyProviderEnvVars_DoesNotDiscoverOracleWithoutBaseURL(t *testing.T)
 	}
 }
 
+func TestApplyProviderEnvVars_OracleModelsEnvWinsOverYAMLWithoutOtherOracleEnvVars(t *testing.T) {
+	raw := map[string]config.RawProviderConfig{
+		"oracle": {
+			Type:    "oracle",
+			APIKey:  "oracle-key",
+			BaseURL: "https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/v1",
+			Models:  []string{"yaml-model"},
+		},
+	}
+	t.Setenv("ORACLE_MODELS", "openai.gpt-oss-120b, xai.grok-3")
+
+	got := applyProviderEnvVars(raw, testDiscoveryConfigs)
+
+	p := got["oracle"]
+	if p.APIKey != "oracle-key" {
+		t.Fatalf("APIKey = %q, want oracle-key", p.APIKey)
+	}
+	if p.BaseURL != "https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/v1" {
+		t.Fatalf("BaseURL = %q, want Oracle base URL", p.BaseURL)
+	}
+	if len(p.Models) != 2 || p.Models[0] != "openai.gpt-oss-120b" || p.Models[1] != "xai.grok-3" {
+		t.Fatalf("Models = %v, want [openai.gpt-oss-120b xai.grok-3]", p.Models)
+	}
+}
+
 func TestApplyProviderEnvVars_EnvWinsOverYAML(t *testing.T) {
 	t.Setenv("OPENAI_API_KEY", "sk-env-key")
 
@@ -636,6 +665,7 @@ func TestApplyProviderEnvVars_SkipsWhenNoEnvVars(t *testing.T) {
 		envNames := derivedEnvNames(providerType)
 		t.Setenv(envNames.APIKey, "")
 		t.Setenv(envNames.BaseURL, "")
+		t.Setenv(envNames.Models, "")
 		if spec.SupportsAPIVersion {
 			t.Setenv(envNames.APIVersion, "")
 		}