feat(providers): add secret-safe local and BYO routes

[fishmingyu]

Parent: #415

Summary

Add one secret-safe inference route contract for CodeNib chat generation and vector construction. The zero-secret product path remains deterministic static Wiki plus BM25. Local Hugging Face and BYO OpenAI-compatible endpoints provide optional semantic and generated-content capabilities through the same public configuration model.

GitHub Models was fully retired by GitHub on 2026-07-30. CodeNib must reject its former aliases rather than infer GITHUB_TOKEN or target the retired endpoint.

Current Gap

The existing product surfaces are individually functional, but their assumptions do not line up:

• chat uses model strings plus optional LiteLLM endpoint/key fields;
• vector construction defaults to local Hugging Face and the CLI cannot select a remote provider;
• semantic dependency checks always require Sentence Transformers;
• default compiler registration hard-codes the Hugging Face provider;
• VectorIndexBuilder embedding kwargs are persisted as artifact identity, so they are unsafe for runtime credentials;
• Wiki runtime configuration can substitute a remote embedding client without a complete persisted compatibility fingerprint;
• doctor validates chat backends but not the embedding route needed to build or query a vector artifact.

Design

Route resolution

Introduce dependency-light, side-effect-free route resolvers for chat and embeddings. A resolved route has:

• canonical provider id;
• model id;
• operation;
• normalized endpoint identity;
• credential source name and availability, never the credential value;
• public provider/model options that affect behavior;
• a stable compatibility fingerprint over public fields.

Local Hugging Face is the built-in embedding route. OpenAI-compatible endpoints are the portable remote embedding route. Chat retains native LiteLLM provider prefixes and an OpenAI-compatible escape hatch.

Artifact versus runtime configuration

Split embedding configuration into:

• artifact identity: provider, model, dimension, endpoint identity, revision/prompt/normalization/truncation settings, and fingerprint;
• runtime client parameters: API key and other process-local authentication data.

Batching, retry, timeout, and credentials do not determine vector compatibility and stay out of the artifact. Any setting that can change produced vectors must be included in the compatibility identity.

Product surfaces

• Add explicit provider/model/dimension/endpoint/key-env options to semantic indexing.
• Make dependency checks provider-aware: local Hugging Face needs Sentence Transformers; remote providers need the OpenAI SDK and credentials when required.
• Reopen vector artifacts only with a compatible route; report a clear mismatch instead of silently substituting a model or endpoint.
• Let Wiki generation use provider-native LiteLLM routes or a BYO OpenAI-compatible service.
• Extend codenib doctor with redacted static diagnostics and optional minimal chat/embedding probes.
• Keep the default static Wiki and BM25 workflow model-free and credential-free.

Security

• Never serialize credential values or request headers.
• Never print token fragments in errors.
• Do not infer a provider from the mere presence of a credential.
• Do not use model-enabled credentials on untrusted fork code or pull_request_target.
• Persist endpoint identity only after rejecting URL userinfo, query strings, and fragments.
• Reject the retired github_models and github-models provider names with an actionable message.

Acceptance Criteria

• Pure resolver tests cover Hugging Face and OpenAI-compatible chat/embedding routes.
• Credential precedence and missing-credential diagnostics are deterministic and redacted.
• No credential can enter manifest/vector artifact configuration under the supported CLI path.
• Vector compatibility fingerprints change for provider, model, dimension, endpoint, revision, prompt, normalization, or truncation changes, but not for token, timeout, retry, or batch-size changes.
• Semantic indexing can build against a mocked OpenAI-compatible embeddings endpoint without Sentence Transformers installed.
• A persisted remote vector artifact can be reopened only by a compatible query route.
• Wiki generation and doctor accept the same BYO route fields.
• Unit, compiler, CLI, Wiki configuration, and secret-regression tests pass.
• Documentation states that static Pages never receives a credential.
• Retired GitHub Models aliases fail closed.

Delivery

1. feat(providers): add secret-safe embedding routes #420: route/identity resolver plus secret-safe vector artifact boundary.
2. feat(cli): expose local and BYO provider routes #421: CLI, compiler, Wiki, doctor, and documentation integration.

Effort

effort/large

[fishmingyu]

Core route/artifact boundary is ready in #420 (commit 4f9df76).

Validated:

• canonical GitHub Models, OpenAI-compatible, and Hugging Face embedding routes;
• credential-free schema-v3 artifact identity and compatibility fingerprints;
• strict reopening through compiler skills, MCP, and Wiki;
• schema-v2 read compatibility;
• 2,568 unit tests and full pre-commit.

The next stacked change will add CLI flags, provider-aware dependency checks, Wiki chat aliasing, doctor probes, and docs. #420 intentionally does not close this issue.

[fishmingyu]

The CLI/Wiki integration is ready as stacked draft #421 (base: feat/provider-routes).

It adds provider-aware indexing and Wiki reopening, GitHub Models chat aliasing, redacted embedding probes, the semantic-remote extra, strict route/artifact mismatch errors, and an actual OpenAI-compatible HTTP build test that verifies credentials never persist.

Local gates:

• 2,582 unit tests passed, 10 skipped
• strict MkDocs build passed
• full pre-commit passed

#421 remains draft until #420 lands and the stack is rebased onto main.

[fishmingyu]

Triage: type/feature, scope/llm + scope/indexing + scope/compiler (route resolution spans litellm chat/embedding routes, CodeVectorStore in index/embedding/, and compiler-side VectorIndexBuilder/default registration), priority/P2 (effort/large, actively landing via stacked #420/#421, existing model-string config remains a workaround). Note: this issue also carries kind/feature and scope/indexer, which aren't in the .github/labels.yml taxonomy — left as-is rather than removed, flagging for cleanup. @fishmingyu (primary), @siriuxyu (scope/indexing).

---

Generated by Claude Code