refactor(providers): unify name separator and refresh docs

[SantiagoDePolonia]

Summary

• Replace go run ./cmd/gomodel and bare ./bin/gomodel snippets with a three-tab <CodeGroup> (Docker .env, Docker -e, binary via make build) on the Oracle, Azure, Bedrock provider pages and the Prometheus metrics guide.
• Condense every page in docs/providers/*.mdx (1227 → 822 lines, ~-33%) onto a single value-first shape: one-line intro → Configure → Run GoModel → Verify → advanced bits → Troubleshooting → References. No factual content removed.
• Drop the undocumented Discovery.NameSeparator: "_" override from Vertex and Bedrock so VERTEX_<SUFFIX>_* / BEDROCK_<SUFFIX>_* register vertex-<suffix> / bedrock-<suffix>, matching every other provider and Google/AWS's own RFC-1034 conventions.
• Update README + advanced config docs to drop the Vertex special-case framing; the general suffix-to-name rule now covers every provider uniformly.

BREAKING CHANGE

Operators with VERTEX_<SUFFIX>_* or BEDROCK_<SUFFIX>_* env vars (or config keyed on vertex_us / bedrock_us) need to switch the provider-name references to vertex-<suffix> / bedrock-<suffix>. Env-var names themselves are unchanged.

Why

The _ override was introduced in PR #302 (Vertex) and copy-pasted into PR #316 (Bedrock) one day later. Neither PR justifies the choice in body or inline comments, no code comment explains it, and the AWS/GCP naming conventions both prefer hyphens. Removing the override removes a special case from the codebase, aligns the documentation with reality (the general "underscores become hyphens" rule), and matches what every other provider already does.

Test plan

• make test-race, make lint, go mod tidy, mint validate — all green via pre-commit hooks on each commit.
• Live smoke test on the unification:
  • Boot log shows provider registered name=bedrock-us type=bedrock and name=vertex-us type=vertex (post-fix; pre-fix was bedrock_us / vertex_us).
  • Admin /providers/status lists both with registered: true, separate fetch timestamps.
  • /v1/models returns bedrock/us.amazon.nova-lite-v1:0 and bedrock-us/us.amazon.nova-lite-v1:0.
  • Real chat calls to both Bedrock provider names returned valid Nova Lite responses through AWS.
  • Vertex chat call blocked by a separate, pre-existing bug (see below) — registration layer verified at every step.

Follow-up worth a separate issue/PR

internal/providers/googleauth/googleauth.go uses google.DefaultTokenSource, which doesn't read quota_project_id from application_default_credentials.json. As a result, any ADC-based Vertex deployment hits authentication_error: ... API requires a quota project on aiplatform.googleapis.com. The fix is to switch to google.FindDefaultCredentials and propagate the project as the X-Goog-User-Project header on outbound Vertex requests. Unrelated to this PR; surfaced during smoke testing.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • Rewrote and reorganized provider setup guides (Azure, Bedrock, DeepSeek, Gemini, Ollama, Oracle, Vertex, vLLM) with clearer Configure/Run/Verify examples, multi-instance guidance, and streamlined tips. Prometheus guide simplified with consolidated quick-start and troubleshooting. Clarified environment-variable usage and pairing rules across docs.

• Bug Fixes

  • Suffixed environment variables now map to hyphenated provider names (e.g., VERTEX_US_* → vertex-us).

• Clarification

  • Vertex auth/defaults and env-var pairing behavior documented (VERTEX_AUTH_TYPE defaults to gcp_adc).

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

Standardizes provider discovery by removing custom underscore NameSeparator for Vertex and Bedrock so suffixed env vars normalize to hyphenated provider names (e.g., VERTEX_US → vertex-us), updates discovery tests, and restructures many provider and guide docs into consistent Configure / Run GoModel / Verify flows.

Changes

Provider Configuration and Documentation Updates

Layer / File(s)	Summary
Provider name normalization internal/providers/vertex/vertex.go, internal/providers/bedrock/bedrock.go, internal/providers/config_test.go	Removes custom NameSeparator: "_" from Vertex and Bedrock registrations, enabling standard suffix-to-name normalization (e.g., VERTEX_US → vertex-us) and updates tests to assert hyphenated discovered provider keys.
Vertex provider docs and examples README.md, docs/advanced/config-yaml.mdx, docs/advanced/configuration.mdx, docs/providers/vertex.mdx	Aligns Vertex docs with suffix-to-provider-name normalization, requires matching-suffix project/location pairs for an instance, documents VERTEX_AUTH_TYPE default (gcp_adc), VERTEX_API_MODE, service-account auth options, multi-region suffixed env vars, and replaces image behavior prose with a mode table.
Provider overview and launch guidance docs/providers/overview.mdx	Clarifies when dedicated provider pages are needed, shortens provider rationale bullets, and adds a Tip showing three launch methods (Docker --env-file, Docker inline -e, prebuilt/binary).
Gemini provider reorganization docs/providers/gemini.mdx	Documents default native routing, adds per-provider GEMINI_API_MODE, documents legacy global toggle behavior, separates native vs OpenAI-compatible base URLs, and replaces image-URL prose with a mode handling table.
Multiple Ollama instances docs/providers/multiple-ollama.mdx	Adds suffixed env-var registration examples (OLLAMA_A_BASE_URL, OLLAMA_B_BASE_URL), consolidates Configure/Run/Route sections with Docker CodeGroup and binary examples, and clarifies provider-qualified model ID routing and YAML fallback use cases.
Azure OpenAI provider rewrite docs/providers/azure.mdx	Condenses Azure setup to Configure with required env vars, adds Run GoModel CodeGroup (Docker env-file, inline -e, binary), updates Verify semantics and multiple-deployments via suffixed env vars, and rewrites troubleshooting.
Bedrock provider rewrite docs/providers/bedrock.mdx	Replaces step-by-step flow with a concise Converse/ConverseStream intro, documents AWS credential-chain resolution, adds Configure/Run/Verify sections, updates BEDROCK_MODELS guidance, and consolidates troubleshooting.
DeepSeek provider update docs/providers/deepseek.mdx	Documents /v1/responses → /chat/completions translation, requires type: deepseek, rewrites DeepSeek V4 reasoning_effort mapping, and marks embeddings unsupported.
Oracle GenAI provider rewrite docs/providers/oracle.mdx	Rewrites Oracle docs to document OCI IAM generativeaiapikey, ORACLE_BASE_URL region scoping, ORACLE_MODELS and CONFIGURED_PROVIDER_MODELS_MODE semantics, precedence rules, Run GoModel CodeGroup, Verify curl example, multiple providers via suffixed env vars, and troubleshooting.
vLLM provider rewrite docs/providers/vllm.mdx	Restructures vLLM docs: Start vLLM first, Configure (VLLM_BASE_URL/API_KEY), Run GoModel CodeGroup, Verify with provider-qualified model IDs, documents provider-prefixed GET /v1/models, and condenses multi-instance/passthrough guidance.
Prometheus metrics guide docs/guides/prometheus-metrics.mdx	Consolidates Disabled-by-Default quick-start into a multi-launch CodeGroup, updates Custom Metrics Endpoint example (METRICS_ENABLED=true, METRICS_ENDPOINT=/internal/prometheus), and replaces 404 troubleshooting with METRICS_ENABLED check + restart directive.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• ENTERPILOT/GoModel#259: Related work on suffix-to-hyphenated-name normalization that aligns with this PR's removal of underscore NameSeparator behavior.
• ENTERPILOT/GoModel#302: Touches Vertex provider discovery/registration and NameSeparator handling; closely related to the changes here.
• ENTERPILOT/GoModel#211: Documentation edits for Ollama multi-instance configuration that overlap with the suffixed env-var patterns standardized in this PR.

Poem

🐰 A rabbit hums, the hyphens sing,

Env vars pair and providers spring,
Vertex, Bedrock, docs aligned,
Configure, Run, and Verify signed,
A small hop marks the tidy change.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the primary change: unifying the name separator convention across providers (removing underscore-based separators from Vertex and Bedrock) and refreshing documentation throughout provider pages.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/provider-run-instructions

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[greptile-apps]

Greptile Summary

This PR removes the NameSeparator: "_" override from the Vertex and Bedrock provider registrations so that VERTEX_<SUFFIX>_* / BEDROCK_<SUFFIX>_* env vars produce hyphenated provider names (vertex-us, bedrock-us) matching every other provider, then refreshes the documentation to drop the old special-case framing and introduce three-tab CodeGroups on provider pages.

• Code change: Single-line removal in vertex/vertex.go and bedrock/bedrock.go; the corresponding test in config_test.go is updated and renamed for vertex, and the testDiscoveryConfigs entry is cleaned up.
• Docs refactor: All docs/providers/*.mdx pages are condensed to a uniform shape (Configure → Run GoModel → Verify → Troubleshooting → References), and README.md / advanced config docs drop the Vertex special-case paragraph.
• Breaking change: Operators using VERTEX_<SUFFIX>_* or BEDROCK_<SUFFIX>_* env vars need to update any references to provider names from underscore form (vertex_us, bedrock_us) to hyphen form (vertex-us, bedrock-us).

Confidence Score: 4/5

Safe to merge; the Go changes are minimal two-line removals whose correctness is confirmed by an updated test on the vertex side and by the live smoke test described in the PR.

The bedrock naming change is symmetric with vertex but has no dedicated test — the behavior of BEDROCK_US_* producing bedrock-us is unverified in the test suite. Adding a parallel test before merge would close that gap. The docs condensation is thorough, but bedrock.mdx does not include a multi-instance example showing the new hyphenated names, which is present for every other provider that underwent the same treatment.

internal/providers/config_test.go (missing bedrock suffix test) and docs/providers/bedrock.mdx (no multi-instance naming example)

Important Files Changed

Filename	Overview
internal/providers/vertex/vertex.go	Removes the Discovery block entirely, dropping the NameSeparator: "_" override so suffixed Vertex providers (VERTEX_US_*) now register as vertex-us instead of vertex_us.
internal/providers/bedrock/bedrock.go	Removes NameSeparator: "_" from Discovery, leaving AllowAPIKeyless: true intact. Suffixed Bedrock providers (BEDROCK_US_*) now register as bedrock-us instead of bedrock_us.
internal/providers/config_test.go	Updates testDiscoveryConfigs to drop the vertex NameSeparator, renames the vertex suffix test, and updates assertions from vertex_us to vertex-us. No equivalent bedrock suffix test is added despite the symmetric behavior change.
docs/providers/bedrock.mdx	Condensed page now lacks a "Multiple Bedrock providers" section showing the BEDROCK_US_* → bedrock-us naming, unlike vertex.mdx which documents the equivalent pattern explicitly.
docs/providers/vertex.mdx	Updated to show vertex-us / vertex-eu naming and condenses the multi-region section; correctly documents the new suffix-to-name rule.
docs/providers/azure.mdx	Refactored to the new Configure → Run GoModel (CodeGroup) → Verify shape; no behavioral changes, content is accurate.
docs/guides/prometheus-metrics.mdx	Replaced bare ./bin/gomodel snippet with a three-tab CodeGroup and added a Note directing readers to apply variables via their chosen launch form.
README.md	Drops the old special-case Vertex paragraph, replacing it with the unified suffix-to-name description. Bedrock's equivalent change is not mentioned here, but it was not mentioned before this PR either.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["Env var VERTEX_US_PROJECT\nBEDROCK_US_BASE_URL"] --> B{"DiscoveryConfig\nNameSeparator"}
    B -- "Before PR\nNameSeparator = '_'" --> C["Provider name:\nvertex_us / bedrock_us"]
    B -- "After PR\nNameSeparator = '' (default)" --> D["Provider name:\nvertex-us / bedrock-us"]
    D --> E["Matches all other providers\ne.g. openai-east, ollama-a, vllm-test"]
    C --> F["Was inconsistent\nwith general suffix rule"]

Loading

Comments Outside Diff (2)

1. internal/providers/config_test.go, line 551-569 (link)

   Missing test for Bedrock suffix naming change

   The vertex suffix behavior is verified here (VERTEX_US_* → vertex-us), but there is no parallel test confirming that BEDROCK_US_* now registers as bedrock-us. Both providers had NameSeparator: "_" removed in this PR, yet only vertex has test coverage. Adding TestApplyProviderEnvVars_DiscoversSuffixedBedrockProvider (mirroring this test with BEDROCK_US_BASE_URL and an assertion on key bedrock-us) would close that gap and guard against a future regression that silently re-introduces the old bedrock_us name.

2. docs/providers/bedrock.mdx, line 1-10 (link)

   No "Multiple Bedrock providers" section documenting the new hyphenated names

   vertex.mdx was updated to show VERTEX_US_* → vertex-us and VERTEX_EU_* → vertex-eu. The symmetric breaking change for Bedrock (BEDROCK_US_* → bedrock-us) is not shown anywhere in the condensed bedrock.mdx. An operator reading only the Bedrock page has no example of the new naming after the breaking change. A short section mirroring the vertex "Multiple regions or accounts" block would make the page self-contained and consistent with the rest of the docs.

_{Reviews (1): Last reviewed commit: "fix(providers): unified suffix-to-name r..." | Re-trigger Greptile}

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[coderabbitai]

Actionable comments posted: 8

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/providers/azure.mdx (1)

57-63: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Verification request is incomplete when master-key auth is enabled.

Because setup uses GOMODEL_MASTER_KEY, the verify curl needs a bearer token header.

Suggested fix

 curl -s http://localhost:8080/v1/chat/completions \
+  -H "Authorization: Bearer change-me" \
   -H "Content-Type: application/json" \
   -d '{

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/providers/azure.mdx` around lines 57 - 63, The verification curl example
in docs/providers/azure.mdx is missing the Authorization header required when
master-key auth is enabled; update the curl command used for the verify flow to
include a Bearer token header using the GOMODEL_MASTER_KEY (e.g., add -H
"Authorization: Bearer $GOMODEL_MASTER_KEY") so the request authenticates
against the server when GOMODEL_MASTER_KEY is set.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/advanced/config-yaml.mdx`:
- Around line 28-30: The wording about Vertex's required environment variables
is ambiguous; update the text to tie required vars to the same suffix rather
than globals — clarify that for a suffixed provider like VERTEX_US_PROJECT
(which registers as vertex-us) you must also provide the matching suffixed
LOCATION var (e.g., VERTEX_US_LOCATION) and any other suffixed settings, rather
than the generic VERTEX_PROJECT or VERTEX_LOCATION; keep the note that
VERTEX_AUTH_TYPE defaults to gcp_adc. Use the existing example names
VERTEX_US_PROJECT and add VERTEX_US_LOCATION to show the intended pattern.

In `@docs/guides/prometheus-metrics.mdx`:
- Around line 80-82: Add the missing flag so the snippet is runnable: update the
quick snippet that currently only sets METRICS_ENDPOINT to also set
METRICS_ENABLED=true (or add an explicit prerequisite line) so the example
enables metrics before specifying METRICS_ENDPOINT; look for the snippet
containing METRICS_ENDPOINT=/internal/prometheus and prepend or include
METRICS_ENABLED=true next to it.

In `@docs/providers/bedrock.mdx`:
- Around line 56-63: The curl example in the Bedrock docs omits the required
Authorization header even though the page configures GOMODEL_MASTER_KEY; update
the example curl (the snippet that posts to /v1/chat/completions) to include the
Authorization header using the GOMODEL_MASTER_KEY (e.g., add an Authorization:
Bearer $GOMODEL_MASTER_KEY header) so the verification request succeeds with the
documented setup.

In `@docs/providers/deepseek.mdx`:
- Around line 44-46: The sentence "To skip reasoning entirely, omit the
`reasoning` field; don't pass `low`." is misleading because the mapping converts
`"reasoning": {"effort":"low"}` into DeepSeek's top-level `reasoning_effort` and
`low` maps to `high` (which enables reasoning). Update the text around the
GoModel/`reasoning` mapping to explicitly state that omitting `reasoning`
disables reasoning, whereas providing `reasoning.effort` — including `low` —
will be mapped and will enable reasoning (note that `low` maps to `high`);
replace "don't pass `low`" with a clear instruction like "omit the `reasoning`
field to disable reasoning; any provided `reasoning.effort` (including `low`)
will be mapped and enable reasoning."
- Around line 36-42: The docs mapping for the reasoning_effort parameter is
incorrect: DeepSeek V4 only accepts "high" and "max", so "anything else → passed
through" is misleading and will cause API errors; update the docs table to
either (A) state that unknown client values will be rejected by DeepSeek (and
recommend mapping/normalizing them to "high" or "max"), or (B) show that the
client must validate/normalize the input (e.g., via a normalizeReasoningEffort
or mapReasoningEffort routine) and reject invalid values before calling the API;
ensure the table and any descriptive text mention that only "high" and "max" are
permitted and that other values will fail.

In `@docs/providers/oracle.mdx`:
- Around line 77-83: The example curl request in the docs omits the required
Authorization header despite the environment key being set; update the curl
example that posts to /v1/chat/completions to include the Authorization header
(e.g., add -H "Authorization: Bearer change-me") so the request uses the
GOMODEL_MASTER_KEY; ensure the header appears alongside the existing
Content-Type header in the sample.

In `@internal/providers/config_test.go`:
- Around line 551-562: Add a parallel assertion in
TestApplyProviderEnvVars_DiscoversSuffixedVertexProvider to also verify Bedrock
suffixed discovery: set the analogous BEDROCK_US_* env vars (e.g.,
BEDROCK_US_PROJECT, BEDROCK_US_LOCATION, BEDROCK_US_AUTH_TYPE,
BEDROCK_US_SERVICE_ACCOUNT_FILE) before calling applyProviderEnvVars and then
assert that got["bedrock-us"] exists (mirroring the existing vertex-us check) so
the test covers the Bedrock separatator/name path as well.

In `@README.md`:
- Around line 128-131: Reword the README sentence about Vertex AI to clarify
that project and location env vars must match the instance prefix: for a
suffixed instance like VERTEX_US_PROJECT you must also set the corresponding
VERTEX_US_LOCATION (and similarly for any other suffix), rather than implying
the unsuffixed VERTEX_PROJECT/VERTEX_LOCATION are always required; retain
mention that VERTEX_US_PROJECT registers provider `vertex-us` and that
VERTEX_AUTH_TYPE defaults to `gcp_adc`.

---

Outside diff comments:
In `@docs/providers/azure.mdx`:
- Around line 57-63: The verification curl example in docs/providers/azure.mdx
is missing the Authorization header required when master-key auth is enabled;
update the curl command used for the verify flow to include a Bearer token
header using the GOMODEL_MASTER_KEY (e.g., add -H "Authorization: Bearer
$GOMODEL_MASTER_KEY") so the request authenticates against the server when
GOMODEL_MASTER_KEY is set.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: b232491c-14c8-4868-aa88-bcadcc70144a

📥 Commits

Reviewing files that changed from the base of the PR and between 6854023 and 0e1f0eb.

📒 Files selected for processing (16)

• README.md
• docs/advanced/config-yaml.mdx
• docs/advanced/configuration.mdx
• docs/guides/prometheus-metrics.mdx
• docs/providers/azure.mdx
• docs/providers/bedrock.mdx
• docs/providers/deepseek.mdx
• docs/providers/gemini.mdx
• docs/providers/multiple-ollama.mdx
• docs/providers/oracle.mdx
• docs/providers/overview.mdx
• docs/providers/vertex.mdx
• docs/providers/vllm.mdx
• internal/providers/bedrock/bedrock.go
• internal/providers/config_test.go
• internal/providers/vertex/vertex.go

💤 Files with no reviewable changes (2)

• internal/providers/vertex/vertex.go
• internal/providers/bedrock/bedrock.go