LearnNewsExamplesServices
Frontmatter
id10804
titleConsolidate neoEmbeddingProvider and chromaEmbeddingProvider configurations
stateClosed
labels
enhancementairefactoringarchitecture
assigneesneo-gpt
createdAtMay 6, 2026, 10:33 AM
updatedAtMay 15, 2026, 2:46 PM
githubUrlhttps://github.com/neomjs/neo/issues/10804
authorneo-gemini-3-1-pro
commentsCount4
parentIssuenull
subIssues[]
subIssuesCompleted0
subIssuesTotal0
blockedBy[]
blocking[]
closedAtMay 6, 2026, 11:33 AM

Consolidate neoEmbeddingProvider and chromaEmbeddingProvider configurations

Closedenhancementairefactoringarchitecture
neo-gemini-3-1-pro
neo-gemini-3-1-pro commented on May 6, 2026, 10:33 AM

Context

The configuration surface currently exposes both chromaEmbeddingProvider and neoEmbeddingProvider. This duality creates operator confusion during deployment regarding which provider to configure and where.

The Architectural Reality

neoEmbeddingProvider is used in exactly one callsite (ai/daemons/services/GoldenPathSynthesizer.mjs:81), while chromaEmbeddingProvider is used by both KB and MC. The two-provider model was surfaced in #10773.

The Fix

Refactor the configuration and instantiation logic to consolidate down to a single, unified embeddingProvider.

Acceptance Criteria

  • Config templates simplified to a single embeddingProvider.
  • GoldenPathSynthesizer.mjs updated to use the unified provider.
  • Backward compatibility or clear deprecation notice provided.

Out of Scope

Adding new embedding provider types (e.g., local ONNX models).

T3 Contract Ledger

Per canonical specification in learn/agentos/contract-ledger.md:

Target Surface Source of Authority Proposed Behavior Fallback / Edge Case Docs Evidence
aiConfig.embeddingProvider (unified config field replacing chromaEmbeddingProvider + neoEmbeddingProvider) #10804, parent #9999, surfacing PR #10806 cookbook gap-audit, PR #10799 Option B substrate this simplifies Single config field ('gemini' | 'openAiCompatible' | 'ollama') drives all downstream embedding consumers. Same input → same vector across all engines (KB QueryService, KB VectorService, MC ChromaManager, MC SummaryService.gateGemini, GoldenPathSynthesizer, MC TextEmbeddingService.gateGemini). Single env var (NEO_EMBEDDING_PROVIDER recommended; final name decided during implementation per #10808 ergonomics direction). Backwards-compat layer: legacy NEO_CHROMA_EMBEDDING_PROVIDER and NEO_EMBEDDING_PROVIDER env vars still readable with deprecation warning; if both legacy vars set with different values, log warning + prefer the unified value (or fall back to first-non-empty per documented precedence). Deprecation window: at least one minor release before hard removal. Update MemoryCore.md §Healthcheck (simplify providers.embedding shape per Row 2), SharedDeployment.md env-var inventory, learn/agentos/DeploymentCookbook.md Section 6 (already references via #10808 footnote — coordinate during implementation). L2 unit-test: test/playwright/unit/ai/mcp/server/memory-core/services/TextEmbeddingService.spec.mjs (verify gateGemini logic with single provider); deprecation-fallback test with both env vars set + conflicting values; HealthService.spec.mjs updated for new providers.embedding shape. Targeted run: npx playwright test test/playwright/unit/ai/mcp/server/memory-core/.
Healthcheck providers.embedding block shape PR #10799 just-shipped Option B {aligned, chroma, neo} shape gets simplified back to single-block per #10804 consolidation; aligned field obsolete Single-block shape {active, host, model, dimensions, error?} — same shape as pre-#10773 + same shape as sibling providers.summary (visual symmetry restored). aligned field removed. Error field surfaced if provider key unrecognized (preserved from prior shape per "surface, don't obscure" PR #10227 principle). Update MemoryCore.md providers.embedding field-table (revert from chroma/neo split to single-provider shape); SharedDeployment.md JSON sample; DeploymentCookbook.md Section 7. L2 unit-test: test/playwright/unit/ai/mcp/server/memory-core/services/HealthService.spec.mjs describe block renamed #10723/#10773/#10804; existing 7 tests collapsed to ~5 (single-block shape; remove aligned assertions; preserve unrecognized provider + defensive nested config absence cases). Empirical 2026-05-06: 23 tests current, expect ~21 post-consolidation.
Code-consumer migration This ticket #10804 + chromaEmbeddingProvider/neoEmbeddingProvider callsites enumerated below All callsites read unified aiConfig.embeddingProvider (not the legacy two): GoldenPathSynthesizer.mjs:81, KB QueryService.mjs:113, KB VectorService.mjs:223,241, MC ChromaManager.mjs:203, MC TextEmbeddingService.mjs:43 (gateGemini becomes single-provider check vs OR), MC HealthService.mjs:135 (buildEmbeddingProviderBlock simplified per Row 2). If backwards-compat layer is provided, callsites continue working with legacy aiConfig.chromaEmbeddingProvider / aiConfig.neoEmbeddingProvider reads via getter shim during deprecation window (or rename happens in callsites + legacy env-var-only fallback in config layer). Code-internal change; no external doc surface beyond Row 1. JSDoc on changed methods may benefit from @since notation calling out the consolidation. L2 — full unit suite passes after consolidation; npm run test-unit (~90s). Specifically HealthService.spec.mjs, TextEmbeddingService.spec.mjs, plus any KB-side tests touching embedding callsites.

Origin Session ID: 88a6ed3a-b1b9-461a-aaf3-7c9984bd12e7 Retrieval Hint: Deployment Cookbook gap surfacing

tobiu closed this issue on May 6, 2026, 11:33 AM
tobiu referenced in commit 7d72cc3 - "feat(ai): consolidate embedding provider config (#10804) (#10810) on May 6, 2026, 11:33 AM