fix(rag): make OCI embedding dimension + input_type deterministic (closes #292)#293
Merged
Merged
Conversation
…290) Bumps locus-sdk to 0.2.0b25. Fixes a Pydantic v2 regression where an explicit wallet_password="" (the python-oracledb auto-login / cwallet.sso idiom) was silently dropped by a truthy SecretStr guard, forcing the encrypted ewallet.pem path and failing at connect with DPY-6005 / OSError: [Errno 22]. The guard is now `is not None` across all seven Oracle pool builders (closes #289). Signed-off-by: Federico Kamelhar <federico.kamelhar@oracle.com>
…oses #292) OCIEmbeddings.embed_query() hardcoded input_type="SEARCH_QUERY" (ignoring config) and embed_documents() hardcoded "SEARCH_DOCUMENT"; embed_query also carried a dead `original_type` local and a misleading "frozen config" comment. More importantly, the real dimension-mismatch trigger behind the report is Cohere v4's Matryoshka output_dimensions, which Locus never set. cohere.embed- v4.0 returns exactly the requested size (256/512/1024/1536) and OCI's server-side default (1536 today) applies otherwise — so a table indexed at one output_dimensions and queried at another raises ORA-51803. input_type does NOT change the output dimension (verified live: v4 returns 1536 for both SEARCH_QUERY and SEARCH_DOCUMENT; v3 returns 1024 for both). Changes: - Add OCIEmbeddingConfig.output_dimensions (default None). Forwarded to EmbedTextDetails on every embed path via a shared _build_embed_details helper, and only when set, so non-Matryoshka models never see the field. - config.dimension now prefers output_dimensions, so the vector column is sized to match the pinned embedding dimension. - Add OCIEmbeddingConfig.query_input_type (default SEARCH_QUERY) and read input_type from config in embed_documents; removes the hardcodes and the dead/misleading code in embed_query. Tests: query_input_type / input_type configurability, output_dimensions omitted-by-default + forwarded on all three paths, and config.dimension reflecting output_dimensions. Signed-off-by: Federico Kamelhar <federico.kamelhar@oracle.com>
fede-kamel
added a commit
that referenced
this pull request
May 30, 2026
…ype fix (#293) (#294) Bumps locus-sdk to 0.2.0b26. Makes the OCI embedding dimension deterministic via a new output_dimensions config knob (Cohere v4 Matryoshka), so a vector column and its query vectors can no longer diverge into ORA-51803; also honors configured input_type / query_input_type instead of hardcoding it (closes #292). Signed-off-by: Federico Kamelhar <federico.kamelhar@oracle.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #292.
The report
RAG queries against a
cohere.embed-v4.0-indexed Oracle table failed with:The original hypothesis was that
OCIEmbeddings.embed_query()hardcodinginput_type="SEARCH_QUERY"caused v4 to return 1024-dim query vectors against a1536-dim (
SEARCH_DOCUMENT-indexed) table.What the investigation actually found
I reproduced against live OCI Generative AI (us-chicago-1) on two separate tenancies.
input_typedoes not change the output dimension — that hypothesis is wrong:SEARCH_DOCUMENTSEARCH_QUERYcohere.embed-v4.0cohere.embed-english-v3.0cohere.embed-multilingual-v3.0cohere.embed-english-light-v3.0The real lever is Cohere v4's Matryoshka
output_dimensions, which Locus neverset. v4 returns exactly the requested size, and OCI's server-side default applies when
it's omitted:
So the
ORA-51803happens when one path (an ingestion pipeline, an older server-sidedefault, or a foreign
OracleVSwriter) lands at oneoutput_dimensionsand anotherpath lands at a different one. Because Locus left the dimension to an implicit OCI
default, the stored column and query vectors could silently diverge.
input_typewas ared herring — but the code did genuinely hardcode it, so that's fixed too.
Fix
Primary — deterministic dimension (
output_dimensions):OCIEmbeddingConfig.output_dimensions(defaultNone). It's forwarded toEmbedTextDetailson every embed path through a shared_build_embed_detailshelper,and only when set, so non-Matryoshka models (v3, fixed dims) never receive the
field.
config.dimensionnow prefersoutput_dimensions, so the vector store sizes itscolumn to exactly the embedding dimension being produced.
Secondary — honor
input_type(the original hardcode + cleanup):embed_query()no longer hardcodesSEARCH_QUERY; it reads a newOCIEmbeddingConfig.query_input_type(defaultSEARCH_QUERY).embed_documents()readsinput_typefrom config instead of hardcodingSEARCH_DOCUMENT.original_typelocal and the incorrect "Can't modify frozen config"comment in
embed_query(the config is a plainBaseModel, never frozen).Tests
Unit —
tests/unit/test_rag_embeddings_oci.py:output_dimensionsomitted by default (never attached for non-Matryoshka models)output_dimensionsforwarded on all three paths (embed/embed_query/embed_documents)config.dimensionreflectsoutput_dimensions(wins over the model hint)query_input_type/input_typeare honored, not hardcodedFull unit suite: 5023 passed, 0 failed.
Integration —
tests/integration/rag/test_oci_embeddings.py: 9 passed against liveOCI GenAI.
Live verification of the fix (real
cohere.embed-v4.0, us-chicago-1):embed_documentsembed_queryconfig.dimensionoutput_dimensions=1024Both paths and the column dimension stay in lockstep — the
ORA-51803divergence can nolonger arise from an implicit server default.