Embedding config: HTTP fallback defaults never succeed; expected_dim dead; eager-load is a no-op

[codenamekt]

Summary

Several embedding-config options don't behave as documented.

Findings

HTTP fallback can never succeed with its own defaults (medium)

hexus/embed.py:105-127 — default model="nomic-embed-text" returns 768-dim vectors while default expected_dim=384 (embed.py:32), so both Path A (OpenAI-compat) and Path B (Ollama) raise EmbeddingError("expected 384 dims, got 768"). This contradicts the module docstring's claim (lines 13–15) that a stale v0.3.x HTTP config "keeps working" — an upgrading operator gets hard failures.

expected_dim plugin config is dead (medium)

hexus/__init__.py:414-421 documents expected_dim as operator-overridable, but no call site passes it — prefetch:790, _maybe_embed:1835, _make_embed_fn:1292, and tool handlers all omit it, so embed.py's hardcoded EXPECTED_DIM = 384 always wins. An operator on a 768-dim endpoint who sets expected_dim: 768 still gets 384-dim errors.

HEXUS_EMBED_EAGER_LOAD does nothing (medium)

docker/compose.yml:88 sets it and comments "saves ~1-2s on first tool call," but nothing calls ensure_loaded(). The only reader is mcp_server/tools.py:88, which merely reports it in stats. Behavior described doesn't exist.

Stale config schema / docstrings (low)

hexus/__init__.py:1743-1751 — get_config_schema marks embed_url as required: True (though None/local is the default) and says embed_model "must return 768-dim vectors" (stale since the 384-dim MiniLM swap). bulk_upsert_md docstring also promises a 768-dim embed_fn.

Suggested direction

Thread expected_dim through the embed() call sites (or drop the config); fix the HTTP-fallback default model/dim mismatch (or update the docstring to stop promising v0.3.x compatibility); actually eager-load when HEXUS_EMBED_EAGER_LOAD=1 (call ensure_loaded() at server/plugin startup) or remove the option; refresh the schema/docstrings to 384-dim.

Filed from the 2026-07 codebase review.