feat(cli): expose local and BYO provider routes

codenib/web/config.py

@@ -27,6 +27,7 @@
     validate_model_options,
 )
 from ..paths import QA_DATA_DIRNAME, REPO_INDEX_DIRNAME
+from ..provider_routes import normalize_provider
 
 DEFAULT_CONFIG_PATH = "qa_config.yaml"
 CACHE_DIR_NAME = REPO_INDEX_DIRNAME
@@ -310,9 +311,9 @@ def load_config(path: Optional[str] = None) -> QAConfig:
     if os.environ.get("CODENIB_EMBEDDING_API_KEY"):
         cfg.embedding_api_key = os.environ["CODENIB_EMBEDDING_API_KEY"]
 
-    cfg.embedding_provider = cfg.embedding_provider.strip().lower()
+    cfg.embedding_provider = normalize_provider(cfg.embedding_provider)
     if cfg.embedding_provider not in {"huggingface", "openai"}:
-        raise ValueError("embedding_provider must be either 'huggingface' or 'openai'")
+        raise ValueError("embedding_provider must be huggingface or openai")
 
     return cfg
 

codenib/web/local.py

@@ -112,6 +112,7 @@ def prepare_local_wiki(
     model: str | None = None,
     api_base: str | None = None,
     api_key_env: str | None = None,
+    embedding_api_key_env: str | None = None,
     model_options: Mapping[str, Any] | None = None,
 ) -> LocalWiki:
     """Write the registry and config consumed by the existing Wiki service."""
@@ -182,6 +183,14 @@ def prepare_local_wiki(
                 f"API key environment variable is unset or empty: {api_key_env}"
             )
         runtime_env["CODENIB_DEMO_API_KEY"] = api_key
+    if embedding_api_key_env:
+        embedding_api_key = os.environ.get(embedding_api_key_env)
+        if not embedding_api_key:
+            raise ValueError(
+                "Embedding API key environment variable is unset or empty: "
+                f"{embedding_api_key_env}"
+            )
+        runtime_env["CODENIB_EMBEDDING_API_KEY"] = embedding_api_key
 
     return LocalWiki(
         repo_path=repo_path,

docs/quickstart.md

@@ -125,6 +125,32 @@ codenib wiki /path/to/repository --preset semantic
 The semantic preset downloads CodeRankEmbed on first use. CodeNib pins the
 built-in model to an immutable revision and enables remote model code only for
 that revision; caller-supplied models or revisions are not trusted implicitly.
+To keep embeddings out of the local process, use a BYO OpenAI-compatible
+embedding service:
+
+```bash
+pip install "codenib[semantic-remote]"
+export EMBEDDING_API_KEY=...
+codenib doctor --require semantic \
+  --embedding-provider openai \
+  --embedding-endpoint https://inference.example.com/v1 \
+  --embedding-api-key-env EMBEDDING_API_KEY \
+  --probe-embedding
+codenib wiki . --preset semantic \
+  --embedding-provider openai \
+  --embedding-endpoint https://inference.example.com/v1 \
+  --embedding-api-key-env EMBEDDING_API_KEY
+```
+
+The remote default is `text-embedding-3-small` with dimension 1536. Select
+another model with `--embedding-model` and declare its vector width with
+`--embedding-dimension`; omit `--embedding-api-key-env` only when the endpoint
+is intentionally unauthenticated.
+Provider, model, endpoint, dimension, and vector-shaping options become part of
+the vector artifact identity. Credentials, retries, timeouts, and batching stay
+process-local, and CodeNib refuses to reopen an artifact through a different
+provider or endpoint.
+
 The `graph` extra supplies the Python graph and protobuf runtimes, while each
 repository language still needs its own SCIP/LSP executable. Check the exact
 repository instead of testing for an unrelated tool:
@@ -176,6 +202,10 @@ codenib wiki . --generate \
   --api-key-env LOCAL_LLM_KEY
 ```
 
+CodeNib passes BYO credentials only to the running client. They are never
+written to `repo_manifest.json`, vector configuration, Wiki caches, or a static
+Pages export.
+
 Provider-native LiteLLM routes use their normal model prefix and credentials:
 
 ```bash

docs/web_demo.md

@@ -115,11 +115,18 @@ environment variables beat the YAML (`load_config()` in
 | `wiki_model_options` | `CODENIB_DEMO_WIKI_MODEL_OPTIONS` | Nested overrides applied only to Wiki, narration, and edge-label calls |
 | `data_dir` | `CODENIB_DEMO_DATA_DIR` | Where checked-out repos, indexes, and the registry live (default `.codenib_qa/`) |
 | `prebuilt_dir` | `CODENIB_DEMO_PREBUILT_DIR` | Read-only tree of pre-built per-instance artifacts (see above) |
-| `embedding_provider` | `CODENIB_EMBEDDING_PROVIDER` | `huggingface` (in-process, default) or `openai` (OpenAI-compatible endpoint) |
+| `embedding_provider` | `CODENIB_EMBEDDING_PROVIDER` | `huggingface` (in-process) or `openai` (BYO endpoint) |
 | `embedding_model` / `embedding_base_url` / `embedding_api_key` | `CODENIB_EMBEDDING_MODEL` / `CODENIB_EMBEDDING_BASE_URL` / `CODENIB_EMBEDDING_API_KEY` | Embedding model plus the endpoint and credential for the remote provider |
 | `edge_labels` | `CODENIB_EDGE_LABELS` | Opt-in LLM-written edge phrases in the graph view (off by default; each first-seen edge costs one small LLM call, then cached) |
 | `edge_label_model` | `CODENIB_EDGE_MODEL` | Optional cheaper model for the short edge-label calls |
 
+The manifest's embedding route is authoritative when the service reopens a
+vector view. Runtime configuration may provide its credential, but cannot swap
+the artifact to another provider, model, dimension, or endpoint. A BYO
+credential can be copied into `CODENIB_EMBEDDING_API_KEY` through the
+`codenib wiki --embedding-api-key-env` option. No credential is persisted in
+the manifest or vector-store configuration.
+
 When `wiki_model` and `model` use the same LiteLLM provider prefix, Wiki may
 reuse `model_api_base` and `model_api_key`. A different provider never inherits
 the Ask endpoint or credential: configure `wiki_api_base` / `wiki_api_key`, or

pyproject.toml

@@ -90,6 +90,11 @@ semantic = [
     "openai>=1.0.0",
     "sentence-transformers>=2.2.0",
 ]
+semantic-remote = [
+    "faiss-cpu>=1.7.0",
+    "numpy>=1.24.0",
+    "openai>=1.0.0",
+]
 # Vertex AI backends (``vertex_ai/...`` model strings, via gcloud ADC).
 # Keep the provider SDK coupled to LiteLLM's own compatibility constraint
 # instead of maintaining a second, looser google-cloud-aiplatform pin here.