Skip to content

fix(catalog): semantic search works again, and says why when it cannot - #54

Merged
jrosskopf merged 1 commit into
mainfrom
fix/catalog-embeddings
Aug 31, 2026
Merged

fix(catalog): semantic search works again, and says why when it cannot#54
jrosskopf merged 1 commit into
mainfrom
fix/catalog-embeddings

Conversation

@jrosskopf

@jrosskopf jrosskopf commented Aug 31, 2026

Copy link
Copy Markdown
Contributor

The audit's last group: the catalog commands. Two findings, one of them a live outage.

catalog search --mode vss|hybrid was broken by something outside this repo

Both failed with a bare HTTP 404 from the embedding provider — with a valid API key. The cause: Google retired text-embedding-004, so the endpoint we call no longer exists. catalog build --embed was broken the same way.

$ erpl-adt catalog search catalog.duckdb "procurement value" --mode hybrid
Error: GeminiEmbeddingProvider::EmbedText (HTTP 404)      # before
  [ABAP] DTEL/DE AD_PROCUREMENT_DOC  (score 0.0163934)    # after

gemini-embedding-001 replaces it, with two details that matter:

  • It returns 3072 dimensions by default where the catalog schema stores FLOAT[768], so the request asks for 768 explicitly — every existing catalog stays readable.
  • Its truncated vectors are not unit length, unlike the ones text-embedding-004 returned, so they are normalised before storage. Without that, cosine similarity would be inconsistent between rows written before and after this change.

The model name now comes from ERPL_ADT_GEMINI_EMBED_MODEL when set, so the next retirement is a configuration change rather than a release, and a 404 from the provider names the unavailable model instead of surfacing a bare status.

A quieter one in the same command

A catalog built without --embed holds no vectors, and a semantic search over none returned an empty list — indistinguishable from "nothing matched", the same trap as the ADT commands in #52. It now says the catalog holds no embeddings and points at --mode fts or a rebuild.

Verified

Against a 100 MB catalog on this machine: hybrid search returns ranked hits, and --mode vss against that (unembedded) catalog explains itself. 1349 unit tests pass.

A correction worth recording

While fixing this I first "explained" the build failure as a GCC -O3 quirk and silenced it with inline. That was wrong: the compiler was right — a member ModelName() in the header shadowed the free function I had added, so my new model name was never used and the old one was still being sent. The member is now defined in the .cpp with the configurable logic, and the bogus comment is gone.


View with [code]smith Autofix with [code]smith
Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.

Sweeping the catalog commands found `catalog search --mode vss` and
`--mode hybrid` failing with an unexplained HTTP 404 from the embedding
provider — with a valid API key. The cause is outside the repo: Google
retired text-embedding-004, so the endpoint we call no longer exists.
`catalog build --embed` was broken the same way.

The replacement is gemini-embedding-001, which returns 3072 dimensions by
default where the catalog schema stores FLOAT[768], so the request asks for
768 explicitly and every existing catalog stays readable. Truncated vectors
from that model are not unit length, unlike the ones text-embedding-004
returned, so they are normalised before storage — otherwise cosine similarity
would be inconsistent between old and new rows.

The model name is now read from ERPL_ADT_GEMINI_EMBED_MODEL when set, so the
next retirement is a configuration change rather than a release, and a 404
from the provider now says which model was unavailable instead of surfacing a
bare status.

A second, quieter problem in the same command: a catalog built without --embed
holds no vectors, and a semantic search over none returned an empty list —
indistinguishable from "nothing matched". It now reports that the catalog has
no embeddings and points at --mode fts or a rebuild.

Verified against a 100 MB catalog: hybrid search returns ranked hits, and vss
against an unembedded catalog explains itself rather than returning silence.
@jrosskopf
jrosskopf merged commit f8a7816 into main Aug 31, 2026
5 checks passed
@jrosskopf
jrosskopf deleted the fix/catalog-embeddings branch August 31, 2026 16:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant