Skip to content

fix: pass embedding dimension to provider and surface sqlite-vec probe failures - #1386

Merged
Teingi merged 3 commits into
oceanbase:masterfrom
happy-v587:fix/embedding-dimension
Aug 28, 2026
Merged

fix: pass embedding dimension to provider and surface sqlite-vec probe failures#1386
Teingi merged 3 commits into
oceanbase:masterfrom
happy-v587:fix/embedding-dimension

Conversation

@happy-v587

@happy-v587 happy-v587 commented Aug 28, 2026

Copy link
Copy Markdown
Contributor

Which issue or RFC does this PR close?

Closes #1385.

Rationale for this change

The configured EMBEDDING_DIMENSION was never sent to the embedding provider, so any configured dimension different from the provider default failed validation. The failure was invisible to users: the readiness probe swallowed the underlying error and only reported degraded / inference.embedding: unavailable, and if the failure happened during vector index initialization it was uniformly wrapped as CapabilityNotSupportedError: vector (sqlite-vec probe failed), which misleadingly suggests a missing sqlite-vec extension. Additionally, an interrupted startup could leave a vector_id=-1 probe row behind, which poisoned every subsequent startup with the same masked error until the database file was deleted manually.

What changes are included in this PR?

  • composition.py: pass the configured embedding profile dimension to the Embedder via EmbeddingSettings(dimensions=...), so providers actually receive the requested dimension instead of returning their default.
  • sqlite/memory_index.py: clear a leftover vector_id=-1 probe row before the vector index probe, making startup idempotent after an interrupted run.
  • sqlite/memory_index.py: include the underlying error in the CapabilityNotSupportedError detail, with a dedicated hint when the existing vec table dimension does not match the configured profile (message contains both dimension values).
  • composition.py: log embedding readiness probe failures via logger.exception before marking inference.embedding unavailable.

Are there any user-facing changes?

  • Behavior: an explicitly configured embedding dimension is now honored by providers that support the dimensions parameter; providers that reject the parameter will now surface a visible error instead of silently mismatching dimensions.
  • Error messages: vector index probe failures now carry the underlying cause text instead of a bare sqlite-vec probe failed; a stale vec table with a different dimension produces an actionable message naming both dimensions.
  • No API, schema, or migration changes.

How was this change tested?

  • 5 new unit tests (tests/builtin/persistence/test_sqlite_memory_vector_index.py, tests/builtin/runtime/test_composition_embedding.py): leftover-row self-heal, dimension-mismatch message contains both dimensions plus chained cause, generic cause surfacing, dimensions settings reaching the Embedder, and no-embedding-config passthrough.
  • make test: no new failures vs the base commit (16 vs 17 pre-existing environment-dependent failures); make check clean.
  • Manual end-to-end validation against a real OpenAI-compatible endpoint: fresh DB with dimension 1536 now reaches ready with vector/hybrid search enabled; a stale 1024-dim table now fails with a message containing both dimensions; an injected vector_id=-1 row is cleaned up on the next start.

AI usage statement

Built with opencode (GLM, Z.ai) under human direction and review; all code, tests, and validation steps were reviewed and confirmed by the author.

…e failures

- send the configured embedding profile dimension via Embedder settings instead
  of letting providers return their default dimension
- clear a leftover probe row before the sqlite-vec vector index probe so an
  interrupted run cannot poison subsequent startups
- include the underlying error, with a dimension-mismatch hint, in the
  CapabilityNotSupportedError raised by the probe
- log embedding readiness probe failures before marking the capability unavailable

Fixes oceanbase#1385
The server test suite intentionally asserts that provider error messages
never reach the logs (see the redaction tests in tests/test_server.py),
so the readiness probe stays silent; root causes are surfaced through the
hard-failure CapabilityNotSupportedError detail instead. Also annotate the
spy state as ClassVar and apply ruff formatting.
@happy-v587
happy-v587 force-pushed the fix/embedding-dimension branch from 1bc63e8 to 5b5c5d7 Compare August 28, 2026 06:14
Comment thread src/powercontext/builtin/runtime/composition.py
Comment thread src/powercontext/builtin/persistence/sqlite/memory_index.py Outdated
Address review feedback on PR oceanbase#1386:

- dependency_readiness_probe now exposes the stable code/detail carried by
  InferenceConfigurationError (e.g. 'misconfigured: provider-rejected
  (HTTP 400)') so the Server and doctor explain what was rejected, while
  plain configuration errors stay redacted as 'misconfigured'.
- _map_error attaches the structured HTTP status to provider-rejected
  failures; the raw provider response body is never included.
- _probe_failure_detail only emits the existing-table migration hint after
  confirming a pre-existing vec0 table with a different dimension; a fresh
  oversized dimension now preserves the actual probe error (e.g. the
  sqlite-vec 8192 maximum).
@happy-v587

Copy link
Copy Markdown
Contributor Author

Both review points are addressed in 6229cb9:

  1. Rejected dimensions now surfaces a stable redacted reason. _map_error attaches the structured HTTP status to provider-rejected failures, and dependency_readiness_probe() now exposes the stable code/detail carried by InferenceConfigurationError instead of collapsing everything to misconfigured: the Server and doctor now report inference.embedding: misconfigured: provider-rejected (HTTP 400). The raw provider response body is never included (the reason is built only from our stable code plus the status code), and plain configuration errors without a code stay redacted as bare misconfigured. Covered by new unit tests plus an end-to-end server test with a mock OpenAI-compatible endpoint returning 404, asserting the reason is stable across cached refreshes and the response body never leaks.

  2. The dimension-mismatch hint is only emitted for a confirmed pre-existing table. _probe_failure_detail now reads the dimension of a pre-existing pc_memory_entry_vec table from sqlite_master and emits the migration hint only when that table exists with a different dimension; otherwise the actual probe error is preserved. A fresh database with dimension 65536 now reports the real sqlite-vec error (its 8192 maximum) instead of telling the user to migrate a nonexistent table. Covered by a new oversized-fresh-dimension regression test.

Validation: make test (950 passed, 9 skipped), make check clean.

@happy-v587 happy-v587 closed this Aug 28, 2026
@happy-v587 happy-v587 reopened this Aug 28, 2026

@Teingi Teingi left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@Teingi
Teingi merged commit 09ee055 into oceanbase:master Aug 28, 2026
25 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

2 participants