feat(providers): add Hyperbolic preset

[olddonkey]

Relates to #572.

This is one review-sized provider addition under the umbrella issue. It intentionally does not close #572.

What changed

• add hyperbolic as a collision-safe API-key preset for CLI init, dashboard setup, key login, and provider workspaces
• use Hyperbolic's fixed OpenAI-compatible /v1 transport with registry-owned, bounded /models discovery
• preserve provider-native slash model ids in both selector forms
• protect an older same-named custom provider from destination or adapter retargeting
• add fixture-only endpoint, routing, derivation, discovery, and collision regression coverage
• update the provider catalog and preset totals in all five documentation locales

Chutes was removed from this PR because its aggregator authorization is not yet established by a citable public source. It was not added to free-directory.ts: Chutes' official pricing currently says it has no free tier, so placing it in the free-provider directory would be inaccurate. Chutes remains usable through the custom OpenAI-compatible provider flow and can return as a separate canonical-preset PR once the authorization evidence is public.

Canonical-preset evidence

Requirement	Primary source	Verification
OpenAI-compatible chat endpoint, base URL, and Bearer API-key use	Hyperbolic text-generation API documentation	Checked 2026-07-30
Authenticated GET /v1/models contract	Official Hyperbolic TypeScript SDK OpenAPI	Checked 2026-07-30
/v1/models host and client authentication binding	Official SDK client configuration	Checked 2026-07-30
Terms of service and operating legal entity	Hyperbolic Terms of Service, which names Hyperbolic Labs, Inc. as owner and operator of the services and API	Checked 2026-07-30
Resale or routing authorization	Not applicable: the documented endpoint is Hyperbolic-operated serverless inference on its GPU infrastructure, not a third-party API reseller route	Checked against the inference documentation on 2026-07-30

Maintenance owner: @olddonkey. Breakage should be reported through an opencodex GitHub issue tagging @olddonkey. I will update the preset when its base URL, authentication, or catalog contract changes, or demote it from the canonical registry if its evidence no longer supports the credential destination.

Contributor affiliation: none; this contribution is not submitted on behalf of Hyperbolic.

Safety and scope

• discovery is capped at 256 KiB and 256 raw rows before caching
• discovery and collision policy remain registry-only and are not copied into config.json or the key-login map
• the preset covers serverless text and vision-language chat only; Hyperbolic's separate image, audio, and GPU endpoints are out of scope
• tests never call live provider endpoints

Validation

• bun test tests/hyperbolic-provider.test.ts tests/provider-registry-parity.test.ts tests/provider-model-discovery-contract.test.ts tests/codex-catalog.test.ts tests/slug-codec.test.ts tests/provider-payload.test.ts — 200 pass, 0 fail
• bun run typecheck
• bun run privacy:scan
• cd docs-site && bun install --frozen-lockfile && bun run build — 146 pages built
• registry count check — 61 total: 50 key, 7 OAuth, 3 local, 1 forward

Local full-suite note: bun run test emitted no failure before the Bun 1.3.14 isolated runner stopped producing output while remaining CPU-active; it was terminated after ten minutes. The focused suite above covers the changed provider, derivation, discovery contract, catalog, slug, and payload surfaces. GitHub's rebased cross-platform CI remains authoritative for the complete suite.

Summary by CodeRabbit

• New Features
  • Added Hyperbolic as a supported API-key provider.
  • Enabled Hyperbolic live model discovery, preserving model IDs that include slashes and restricting discovery scope and size.
  • Ensured Hyperbolic chat completions are routed to the correct inference endpoint with proper authorization.
• Documentation
  • Updated Quickstart and provider guides to reflect the current count of built-in provider registry presets (61).
  • Documented Hyperbolic’s provider details, discovery behavior, supported use cases, and limitations.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: f72f4efb-2068-4da2-864c-108968b40e5d

📥 Commits

Reviewing files that changed from the base of the PR and between d5dd390 and dbf4bd1.

📒 Files selected for processing (3)

• docs-site/src/content/docs/ja/guides/providers.md
• docs-site/src/content/docs/ko/guides/providers.md
• docs-site/src/content/docs/zh-cn/guides/providers.md

---

📝 Walkthrough

Walkthrough

Changes

Hyperbolic provider integration

Layer / File(s)	Summary
Registry entry and provider parity src/providers/registry.ts, tests/provider-registry-parity.test.ts	Registers Hyperbolic with key authentication, OpenAI-compatible chat routing, bounded live model discovery, and custom-destination preservation.
Discovery, routing, and migration validation tests/hyperbolic-provider.test.ts, tests/fixtures/hyperbolic-models.json	Tests provider derivation, bearer-authenticated discovery, slash-preserving model IDs, chat-completions routing, and custom-provider destination behavior.
Multilingual provider documentation docs-site/src/content/docs/...	Updates preset counts and documents Hyperbolic URLs, discovery behavior, limits, and supported endpoint types across locales.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant OcxConfig
  participant buildModelsRequest
  participant HyperbolicAPI
  participant gatherRoutedModels
  participant routeModel
  OcxConfig->>buildModelsRequest: Build /models request
  buildModelsRequest->>HyperbolicAPI: GET /v1/models with Bearer key
  HyperbolicAPI-->>gatherRoutedModels: Return model list
  gatherRoutedModels-->>routeModel: Preserve native model IDs
  routeModel-->>OcxConfig: Build /chat/completions request

Loading

Possibly related PRs

• lidge-jun/opencodex#652: Introduces the bounded model-discovery contract used by the Hyperbolic registry entry.
• lidge-jun/opencodex#434: Introduces provider-registry and model-discovery machinery used by this integration.
• lidge-jun/opencodex#653: Adds another first-class provider with bounded live model discovery and related documentation/tests.

Suggested reviewers: ingwannu, lidge-jun, wibias

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR implements Hyperbolic-specific preset, discovery, routing, tests, and docs, but not the linked issue's broader 12-provider batch.	Either expand the PR to include the full verified provider batch and related presets, or relink it to a narrower Hyperbolic-only issue.
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 (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and accurately highlights the main change: adding the Hyperbolic provider preset.
Out of Scope Changes check	✅ Passed	The changes stay within provider registry, discovery, tests, fixtures, and documentation; no unrelated scope is evident.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[lidge-jun]

NEEDS-CHANGES — the code is ready, the evidence package is not.

The implementation shape is right and the tests are the kind I like to see on a preset. tests/chutes-hyperbolic-provider.test.ts covers derivation into init/dashboard/key-login, Bearer-authenticated discovery against a fixture, slash-ID preservation in both selector forms, the actual adapter request URL and authorization header, and preservation of a same-name custom base URL. Both entries set preserveCustomDestination, which is exactly the protection a new key-provider ID needs.

The blocker is MAINTAINERS.md:33-42. A preset is a credential-destination change, and before merge it needs documented OpenAI-compatible endpoints (including authenticated GET /v1/models where the entry declares liveModels), terms of service and operating legal entity, resale or routing authorization for aggregators, a named maintenance owner, and a citable verification date.

Going through it:

Chutes (https://llm.chutes.ai/v1, liveModels: true)

• endpoint and authenticated /v1/models: supplied
• ToS and operating legal entity: missing
• routing authorization: missing and applicable — Chutes serves Z.AI, DeepSeek, Moonshot, MiniMax and Google models through one endpoint, which is the aggregator case the clause names
• maintenance owner: missing
• verification date: partial; 2026-07-30 is attached to endpoint probes but not paired with each primary source

Hyperbolic (https://api.hyperbolic.xyz/v1, liveModels: true)

• chat endpoint documentation: supplied
• authenticated GET /v1/models documentation: missing, and the entry declares liveModels, so this one is required
• ToS and operating legal entity: missing
• routing authorization: not applicable — their documentation describes Hyperbolic-operated serverless serving on their own GPU infrastructure, so I read them as first-party
• maintenance owner: missing
• verification date: partial; unauthorized-token probes are not a dated verification package

One thing worth knowing before you invest more: Hyperbolic is already in src/providers/free-directory.ts:127, with verification: "official". Directory rows are inert — they never become canonical login or routing presets (tests/provider-registry-parity.test.ts:805 pins that) — but they exist precisely for the case where the endpoint is known and the paperwork is not. The same clause says to prefer a directory row when evidence is incomplete. So if the ToS and ownership evidence is hard to pin down for one of these, the fallback is not "drop it", it is "leave it where it already is".

What happens next: complete the evidence for whichever provider you want canonical — the endpoint and /v1/models documentation with dates, the ToS and operating entity, Chutes' routing authorization, and a named maintenance owner willing to be pinged when it breaks. Then request explicit security review. The PR is a draft and merges cleanly against current dev, and dev CI is fully green now, so your checks will be about your change.

[lidge-jun]

Formalizing the disposition so it shows on your dashboard.

Blocking on the canonical-preset evidence gate in MAINTAINERS.md:33-42, not on the code — the implementation and tests are in good shape. Missing for both providers: terms of service and operating legal entity, a named maintenance owner, and a citable verification date. Chutes additionally needs routing authorization as an aggregator, and Hyperbolic needs authenticated GET /v1/models documentation since the entry declares liveModels.

Note that Hyperbolic already has an inert row at src/providers/free-directory.ts:127, which is the preferred landing spot when the evidence is incomplete.

Full per-item walkthrough in my earlier comment.

[olddonkey]

Addressed the canonical-preset evidence gate in d5dd3905 and rebased the branch onto current dev (be177ea5).

• narrowed the PR to Hyperbolic only; Chutes code, fixtures, tests, and docs were removed
• did not put Chutes into free-directory.ts, because Chutes' current official pricing explicitly says there is no free tier; it can return in a separate PR once public routing authorization is available
• added a dated, primary-source evidence table covering the chat endpoint, authenticated GET /v1/models, SDK host/auth binding, Terms, and the operating entity Hyperbolic Labs, Inc.
• named @olddonkey as maintenance owner, documented the breakage-report path, and disclosed contributor affiliation
• retained collision-safe destination preservation and fixture-only live-discovery coverage for Hyperbolic

Validation: focused provider/contract/catalog suite 200 pass / 0 fail, typecheck passed, privacy scan passed, and the docs build produced 146 pages. The PR description records the local Bun full-suite non-exit separately; the rebased cross-platform CI is authoritative for the complete suite.

Please re-review the requested changes and perform the explicit security review required for this credential-destination addition.

[coderabbitai]

Actionable comments posted: 2

🤖 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-site/src/content/docs/ja/guides/providers.md`:
- Around line 119-121: Update the earlier Japanese OAuth preset count in the
OAuth section to match the catalog’s 7 presets, ensuring both references
consistently reflect the registry count.
- Line 136: Correct GitHub Copilot’s provider classification by removing it from
the API-key tables or moving it to the OAuth catalogs, preserving the existing
OAuth description. Apply the same correction in
docs-site/src/content/docs/ja/guides/providers.md:136-136,
docs-site/src/content/docs/ko/guides/providers.md:136-136, and
docs-site/src/content/docs/zh-cn/guides/providers.md:128-128.

🪄 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: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: f68186fe-2ebe-40dc-b9d9-9e90f75cf288

📥 Commits

Reviewing files that changed from the base of the PR and between be177ea and d5dd390.

📒 Files selected for processing (14)

• docs-site/src/content/docs/getting-started/quickstart.md
• docs-site/src/content/docs/guides/providers.md
• docs-site/src/content/docs/ja/getting-started/quickstart.md
• docs-site/src/content/docs/ja/guides/providers.md
• docs-site/src/content/docs/ko/getting-started/quickstart.md
• docs-site/src/content/docs/ko/guides/providers.md
• docs-site/src/content/docs/ru/getting-started/quickstart.md
• docs-site/src/content/docs/ru/guides/providers.md
• docs-site/src/content/docs/zh-cn/getting-started/quickstart.md
• docs-site/src/content/docs/zh-cn/guides/providers.md
• src/providers/registry.ts
• tests/fixtures/hyperbolic-models.json
• tests/hyperbolic-provider.test.ts
• tests/provider-registry-parity.test.ts