Skip to content

feat(embedding): BGE-M3 HTTP provider (1024D, zero-vector guard) + full registration - #91

Open
RobertSigmundsson wants to merge 4 commits into
acidkill:mainfrom
RobertSigmundsson:upstream-pr/bge-m3-embedding-provider
Open

feat(embedding): BGE-M3 HTTP provider (1024D, zero-vector guard) + full registration#91
RobertSigmundsson wants to merge 4 commits into
acidkill:mainfrom
RobertSigmundsson:upstream-pr/bge-m3-embedding-provider

Conversation

@RobertSigmundsson

Copy link
Copy Markdown
Contributor

Problem

main already assumes a self-hosted bge-m3 endpoint in several places
(unified_config.py:124, unified_config.py:2521, engine/encoder.py:461,
engine/reasoning_distiller.py:8 and :410) but there is no bge_m3 provider — you can only reach such
an endpoint through the OpenAI-compatible path, which does not carry BGE-M3's dimension or its
normalisation contract.

Change

Four commits, one logical addition:

  1. BGEM3Embedding — posts to a /embed HTTP service, returns 1024-D L2-normalised vectors, and
    raises on empty/failed input instead of fabricating a zero vector. A fabricated zero vector is
    silently catastrophic for a cosine KNN index: it poisons the neighbourhood without any error.
  2. Registration in unified_config._VALID_PROVIDERS — without it the effective-config validator
    rejected bge_m3 even though the factory could build it.
  3. Generic wording in the provider docstring (no deployment-specific references).
  4. Registration in the embedding capability probe — otherwise recall is reported as degraded
    even when the provider is working.

Configuration is env-driven (SURREAL_MEMORY_EMBEDDING_BASE_URL, BGE_M3_API_KEY,
SURREAL_MEMORY_EMBEDDING_DIMENSION), consistent with the other providers.

Why upstream benefits

Self-hosted BGE-M3 is a common way to run this project without a paid embedding API, and the codebase
already talks about it. This makes it a first-class provider, including the two registration points that
are easy to miss (items 2 and 4 were each found only after the provider silently misbehaved).

Evidence

Check Result
cherry-pick onto origin/main clean (4 commits)
import surreal_memory OK
ruff check All checks passed!
ruff format --check 702 files already formatted
mypy src/ --ignore-missing-imports Success: no issues found in 370 source files (369 + the new module)
pytest -m "not stress" -n auto 6535 passed, 84 skipped, 1 xfailed — identical to baseline

Risks / notes for the reviewer

  • No new tests. The provider is pure HTTP I/O and this branch adds no unit test for it; the suite is
    unchanged at 6535. If upstream wants a mocked-transport test before merging, say so and it will be added.
  • Additive only: no existing provider path is modified, so an installation that never sets
    provider = "bge_m3" sees no behaviour change.
  • Does not touch the storage layer or any KNN contract — it plugs into the existing
    semantic_discovery._create_provider factory.
  • Dimension mismatch caveat: switching an existing brain from a 768/3072-D provider to this one requires
    a re-embed, same as any provider change. Not handled here (and not handled for the other providers either).

Robert Sigmundsson added 4 commits July 26, 2026 01:39
…ry registration

F2 writer A of the Gemini-3072D -> BGE-M3-1024D migration. New BGEM3Embedding posts
to a self-hosted /embed service (vast.ai via tunnel), returns 1024D L2-normalized
vectors, and RAISES on empty/failed input instead of fabricating a poison zero-vector.
Registered in the _create_provider factory + _VALID_PROVIDERS. Shadow only — no prod re-embed.

(cherry picked from commit 4607c9a)
(cherry picked from commit 4fbe4ad)
(cherry picked from commit 9837606)
…2 gap → effective-config rejected it)

The BGE-M3 provider was added to engine/embedding/config.py + the factory in F2, but
unified_config.py has its OWN provider allow-list that gates the effective embedding
config — it still rejected 'bge_m3' ('falling back to disabled'), blocking reindex.
Surfaced during F4 pre-cutover verification.

(cherry picked from commit 560c424)
(cherry picked from commit 75f8e50)
(cherry picked from commit 50df9b2)
…cstring

(cherry picked from commit ad88a53)
(cherry picked from commit 156786a)
(cherry picked from commit 0d0b23e)
…lagged degraded

The BGE-M3 HTTP provider was added to the embedding factory (b59be72) and to
unified_config._VALID_PROVIDERS (5d2cef7) but NOT to capability._PROVIDER_IMPORT.
As a result every smem-mcp/CLI startup logged a spurious "Embedding provider
unavailable — running in degraded keyword mode. unknown embedding provider
'bge_m3'", and smem_health / stats_handler reported embeddings as unavailable —
even though recall/remember embed correctly via the factory (authed BGE-M3
/embed returns 200). bge_m3 only needs httpx, shipped in the `server` extra.

(cherry picked from commit 135a6ec)
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