4 Commits

Include renames

Author	SHA1	Message	Date
3 people	e60b60244f	v0.36.6.0 feat: cross-modal search wave (text↔image + unified column + LLM intent) (#1165) ... * feat(cross-modal/0): batched multimodal + query helpers + SSRF helper Commit 0 of the cross-modal search wave. Foundation for Phase 1-3: - embedMultimodal accepts MultimodalInput text variant + EmbedMultimodalOpts with inputType: 'document' | 'query' (D22-2). Default unchanged so importImageFile keeps document-side embedding. - embedQueryMultimodal(text) + embedQueryMultimodalImage(input) wrappers for hybridSearch + searchByImage query paths. - embedMultimodalSafe binary-search retry on transient batch failure + failed_indices surfacing. Phase 3 reindex uses this so a single bad chunk doesn't discard the 31 in-flight embeddings around it. - Voyage path: text + image inputs in one batch via content arrays. - openai-compat path: text + image inputs in one request per input. - src/core/ssrf-validate.ts (D19): DNS-resolve-and-fetch-by-IP defense for redirect chains. Closes the DNS-rebinding gap that url-safety.ts' static check leaves open. Uses node:dns/promises with {all: true, family: 0} to inspect every A and AAAA record before connecting. fetchWithSSRFGuard helper validates per-redirect-hop and limits chain depth (default 3). - Re-exports from src/core/embedding.ts public seam. Tests: - test/embed-multimodal-batching.test.ts (13 cases): text variant, query inputType discipline, mixed text+image batches, embedQueryMultimodal, embedQueryMultimodalImage, embedMultimodalSafe happy/empty/all-fail/ mid-batch-recovery/permanent-misconfig. - test/ssrf-validate.test.ts (20 cases): static rejections via isInternalUrl, scheme + credentials rejection, DNS rebinding defense (single-record + multi-record), public happy path, IPv6 literals, malformed URLs. No regression in existing voyage-multimodal.test.ts or openai-compat-multimodal.test.ts (33 cases all pass). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(cross-modal/1): Phase 1 text→image routing + knobsHash + RRF + backfill Phase 1 of the cross-modal search wave. Wires the existing 1024d Voyage multimodal embedding space (already populated for image chunks via importImageFile) into the user-facing query path. Text queries that match cross-modal intent regex route through Voyage multimodal-3 instead of the text embedding model, then search content_chunks.embedding_image. - query-intent.ts: new `suggestedModality: 'text' | 'image' | 'both'` axis on `QuerySuggestions`. Module-scope CROSS_MODAL_PATTERNS regex array (D15 — compiled once at module load). Conservative on purpose; LLM intent escalation (Commit 4) catches genuinely ambiguous phrasings. - query-intent.ts: new `isAmbiguousModalityQuery(query)` pure heuristic for Commit 4's escalation gate. Returns true ONLY when regex misses AND a visual noun + reference marker both fire. - types.ts: `SearchOpts.crossModal: 'text' | 'image' | 'both' | 'auto'` + `SearchResult.modality: 'text' | 'image'` for downstream renderers. - mode.ts: 7 new knobs in ModeBundle (D2): cross_modal_both_text_weight, cross_modal_both_image_weight, image_query_text_refinement_weight, image_query_image_refinement_weight, unified_multimodal, unified_multimodal_only, cross_modal_llm_intent. All three mode bundles default to the same values (cross-modal is opt-in). - mode.ts: D2 cache-key fix — KNOBS_HASH_VERSION bumped 2→3, all 7 new knobs participate in knobsHash so a text-mode cache hit can't be served to an image-mode caller. - mode.ts: D3 registry — all 7 keys land in SEARCH_MODE_CONFIG_KEYS so `gbrain search modes` / `stats` / `tune` see them. - hybrid.ts: routing branch at the embed step. Resolves effective modality from (per-call opts → suggestions → 'text'). Image route: embedQueryMultimodal + searchVector(embedding_image), skip expansion + keyword (D9 mode-bundle override). Both route: parallel text + image vector searches merged via weighted RRF (D6) with cross_modal_both_* weights. Fail-open: multimodal misconfigured → structured warn + text fallback. 'auto' literal normalized to undefined (D22-1). - operations.ts: thread `cross_modal` param through `query` op. - backfill-registry.ts: new `modality` backfill kind. SQL filter requires `chunk_source='image_asset'` (D22-7 defensive guard). Idempotent. - doctor.ts: `cross_modal_modality_backfill` check surfaces unflagged image-asset chunks with paste-ready `gbrain backfill modality` hint. Tests: - cross-modal-phase1.test.ts (45 cases): regex classification (positive + negative + plural-safe), isAmbiguousModalityQuery, D3 registry, D2 knobsHash diffs across all 7 new knobs, MODE_BUNDLES defaults, resolveSearchMode precedence chain. - cross-modal-hybrid-integration.test.ts (7 cases): PGLite + stubbed gateway. Verifies image-modality calls Voyage and not OpenAI, text calls OpenAI and not Voyage, 'auto' literal normalizes, 'both' mode hits both endpoints, fail-open routes to text on multimodal misconfig. - search-mode.test.ts: updated MODE_BUNDLES + KNOBS_HASH_VERSION assertions (148 cross-suite tests still pass; no regression). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(cross-modal/2): Phase 2 image-as-query + D18 path ban + D23-#6 spend cap Phase 2 of the cross-modal search wave. Adds the `search_by_image` MCP op, the SSRF-defended image loader, and the daily per-OAuth-client spend cap on paid Voyage multimodal calls. D17 honest framing applied: Phase 2 ships image→similar-images + image-OCR-text retrieval. True image→full-text- knowledge requires Phase 3's unified column. - src/core/search/image-loader.ts: loadImageInput accepts local path, data: URI, or http(s):// URL. Magic-byte sniff for PNG/JPEG/WebP (no other formats). Hard size cap (10MB local default, 2MB remote default). http(s) path uses fetchWithSSRFGuard from Commit 0: every redirect hop re-resolved via DNS lookup + every record checked against the internal IP deny list. Max 3 redirect hops. 5s total fetch timeout. Pre-flight Content-Length check + post-fetch size guard for lying servers. - src/core/search/by-image.ts: searchByImage runs the image branch always; D13 hybrid intersect runs a parallel text branch when `query` is provided, merged via weighted RRF. Phase 3 will widen the column routing to embedding_multimodal once that lands. - src/core/operations.ts: new search_by_image op (scope: read, NOT localOnly). D18 P0 — when ctx.remote === true AND image_path is set, rejects with permission_denied at handler entry (validateParams would catch it again at dispatch). D5 source-id thread via sourceScopeOpts. D12 per-param length cap enforced via remote-vs-local maxBytes config read at handler entry. D23-#6 pre-flight checkBudget + post-call recordSpend (best-effort; failures don't block response). - src/core/spend-log.ts: BudgetExceededError + checkBudget + recordSpend + getTodaySpendCents. UTC day-aligned aggregation so the cap rolls over deterministically. Local CLI callers (no clientId) bypass the gate entirely. Pre-v0.36 brains without the mcp_spend_log table fail open to spend=0; the migration brings the table in on first start. - src/core/migrate.ts: new migration v67 mcp_spend_log table + indexes for the (client_id, day) and (token_name, day) hot reads. PGLite parity via sqlFor.pglite. - src/core/search/hybrid.ts: RRF_K constant exported so by-image.ts can share the same effective-K math as the main hybrid path. Tests: - cross-modal-phase2.test.ts (15 cases): magic-byte sniffing (PNG + JPEG + WebP positive, GIF rejection), oversized rejection (default + custom cap), data: URI happy path + malformed + decoded-non-image + oversized, invalid input shapes (empty + ftp), SSRF defense via DNS rebinding stub. - search-by-image-op.test.ts (7 cases): D18 remote image_path rejection + local CLI accepts; input validation (missing all three / multiple together); D23-#6 budget block-at-cap + allow-under-cap + local-CLI-bypass; migration v67 mcp_spend_log table applied cleanly. All 166 tests across the cross-modal suite pass; no regression in existing voyage-multimodal / openai-compat-multimodal / search-mode suites. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(cross-modal/3): Phase 3 unified column + reindex + D8 fail-open + D23-#2 Phase 3 of the cross-modal search wave. Adds the unified multimodal column on content_chunks + the `gbrain reindex --multimodal` sweep + the `search.unified_multimodal` routing flag with D8 source-aware coverage guard + fail-open behavior. D17 honest framing: this is the phase that unlocks true image→full-text-knowledge — Phase 2's searchByImage transparently upgrades to the richer retrieval once the unified column has coverage. D10 reindex-core extraction filed as a follow-up TODO. The existing markdown reindex walks pages and re-imports via importFromFile; this walks content_chunks and re-embeds via the gateway. Patterns rhyme but cores diverge enough that extraction balloons the diff. Both commands stand alone with their own checkpoint + cost-prompt logic. - migrate.ts v68 (embedding_multimodal_column): column-only ALTER on content_chunks. HNSW partial index deferred to post-reindex build (D20: pgvector docs recommend post-load build for HNSW). Both engines. - types.ts SearchOpts.embeddingColumn type widened to include 'embedding_multimodal'. - postgres-engine.ts + pglite-engine.ts searchVector: route to embedding_multimodal column when opts.embeddingColumn set. NO modality filter (unified column carries both text + image content). - hybrid.ts unified routing branch: when search.unified_multimodal=true, bypasses dual-column branching and runs embedQueryMultimodal + searchVector(embedding_multimodal). D8 fail-open: zero rows + not strict-mode → falls through to dual-column text path with structured warning. search.unified_multimodal_only=true bypasses the fallback. - src/commands/reindex-multimodal.ts: `gbrain reindex --multimodal`. D7 lock via tryAcquireDbLock('gbrain-reindex-multimodal'); 6h TTL. Cost prompt + 10s Ctrl-C grace window in TTY; auto-proceeds non-TTY. GBRAIN_NO_REEMBED=1 bypass. Checkpoint at ~/.gbrain/reindex-multimodal-checkpoint.json for resume. D23-#2 auto-flip prompt at coverage=100% completion. - cli.ts: `gbrain reindex --multimodal` dispatch with --limit, --dry-run, --cost-estimate, --no-embed, --yes, --json flags. - doctor.ts: unified_multimodal_coverage check (D21 source-aware) + reports per-source % when search.unified_multimodal is on. Warns at <95% lowest source; fails when unified_multimodal_only=true AND lowest source <99%. Falls open to OK when column not yet present. Tests: - unified-multimodal.test.ts (8 cases): schema migration v68 applies, reindex --dry-run + --cost-estimate + GBRAIN_NO_REEMBED bypass + zero-pending fast-path, hybridSearch unified routing forces voyage endpoint, D8 fail-open routes to text on empty unified, D8 strict blocks text fallback. All 211 tests across the cross-modal + related suite pass; no regression in voyage-multimodal / openai-compat-multimodal / search-mode / intent / search base suites. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(cross-modal/4): LLM intent escalation for ambiguous modality Commit 4 of the cross-modal search wave (opt-in default off). When `search.cross_modal.llm_intent` is true AND the regex classifier returned 'text' AND `isAmbiguousModalityQuery(query)` fires, hybridSearch awaits a Haiku tie-break via gateway.chat() before routing. The ambiguous-modality gate (introduced in Commit 1) ensures the LLM call only fires on the narrow band where regex misses but a visual noun + reference marker both fire — roughly <1% of queries with the flag on. - src/core/search/llm-intent.ts: new module. `classifyModalityWithLLM` routes through gateway.chat() with a fixed system prompt ("Output exactly one word: text, image, or both"). 1s timeout via AbortController. `parseModality` is a pure exported helper that tolerates trailing punctuation + casing. Fail-open on every error path (gateway unavailable, timeout, parse failure, unrecognized output). - src/core/search/hybrid.ts: escalation branch slots BEFORE the unified routing branch. Gated by: no explicit per-call crossModal opt, regex result == 'text', config flag on, ambiguity heuristic fires. Fail-open to regex result on any error from the LLM tie-break. Tests: - llm-intent-escalation.test.ts (14 cases): parseModality tolerance matrix (text / image / both / trailing punct / whitespace / unrecognized / empty), classifyModalityWithLLM happy paths for all 3 outputs, fail-open on throw / unrecognized output / gateway-not- configured, explicit-fallback-honored. - llm-intent-hybrid-integration.test.ts (6 cases): hybridSearch escalation gate fires ONLY when flag-on + ambiguous; off when flag-off, unambiguous, regex-confident, or explicit per-call opt set; fail-open on LLM throw. All 231 tests across the cross-modal + related suite pass; no regression in voyage-multimodal / openai-compat-multimodal / search-mode / intent / search base suites. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(cross-modal/3): verify-gate fixes for full test suite Three small fixes to pass the full unit + E2E sweep after the cross-modal wave commits land. - migrate.ts v67: drop date_trunc('day', created_at) from mcp_spend_log indexes. TIMESTAMPTZ truncation depends on session timezone and isn't IMMUTABLE, so Postgres rejects the function in the index expression with SQLSTATE 42P17. BTREE on (client_id, created_at) covers the per-day rollup query via range scan on created_at — same performance, no IMMUTABLE constraint. - pglite-schema.ts + src/schema.sql: shorten the embedding_multimodal column comment. The longer version contained a comma inside a SQL line comment ("...search.unified_multimodal=true, all queries..."), which broke parseBaseTableColumns in test/schema-bootstrap-coverage (the parser splits on commas at depth-0 before stripping comments, so the comma inside the comment shortened the column-definition part and an "all" token from "all queries" got picked up as the next column name — silently hiding embedding_multimodal from coverage). - schema-embedded.ts: regenerated via `bun run build:schema`. - test/e2e/v030_1-integration-pglite.test.ts: listBackfills assertion extended to include the new `modality` entry registered in src/core/backfill-registry.ts as part of Commit 1. - test/search/knobs-hash-reranker.test.ts: KNOBS_HASH_VERSION assertion updated from 2→3 to match the cross-modal-wave hash-key extension (D2 cache contamination fix). Same shape as the prior v0.32→v0.35 bump. - test/unified-multimodal.test.ts: migrated process.env mutation to withEnv() helper to satisfy the scripts/check-test-isolation R1 rule. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(cross-modal): VERSION + CHANGELOG + CLAUDE.md + spec doc + llms regen Final docs commit for the cross-modal wave (v0.36.0.0). - VERSION + package.json: bump 0.35.5.1 → 0.36.0.0 - CHANGELOG.md: full Garry-voice release entry with five-commit breakdown, the-numbers-that-matter table, what-this-means-for-you, and the required to-take-advantage-of-v0.36.0.0 block - docs/issues/cross-modal-search.md: cherry-picked from PR #1127 head (164 lines, the original spec doc preserved as historical reference for Phase 2 + 3 background) - CLAUDE.md: Key Files entries for src/core/ssrf-validate.ts, src/core/search/image-loader.ts, src/core/search/by-image.ts, src/core/search/llm-intent.ts, src/core/spend-log.ts, src/commands/reindex-multimodal.ts, plus extension annotations on src/core/search/query-intent.ts, src/core/search/mode.ts, src/core/search/hybrid.ts, src/core/backfill-registry.ts, src/core/migrate.ts (v67 + v68) - llms-full.txt + llms.txt: regenerated via `bun run build:llms` `bun run verify` clean (privacy + proposal-pii + test-names + jsonb + source-id-projection + progress + test-isolation + wasm + admin-build + admin-scope-drift + cli-exec + system-of-record + eval-glossary + typecheck). `bun test test/build-llms.test.ts` clean (7/7). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(cross-modal): renumber migrations 67→69 + 68→70 post-master-merge Master shipped its own v67 (`facts_typed_claim_columns`) during the cross-modal wave's review cycle. The merge picked up both side's v67 entries, breaking the migration-distinct-versions test. Renumbering moves cross-modal's table + column ALTER off the collision: - v67 mcp_spend_log → v69 mcp_spend_log - v68 embedding_multimodal_column → v70 embedding_multimodal_column References updated in CHANGELOG, CLAUDE.md, pglite-schema.ts, schema.sql. schema-embedded.ts regenerated. llms-full.txt regenerated. 7006 unit tests pass, 0 fail. No test code touched — just version renumbering plus comment refs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore: bump version 0.36.0.0 → 0.36.4.0 Bumping to v0.36.4.0 to land in the queue slot the user requested. No behavior change; pure version bump across VERSION, package.json, CHANGELOG.md header, llms-full.txt regen. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-19 17:14:53 -07:00
3 people	1d5f69fe7a	v0.36.3.0 feat: dynamic embedding column selection for search (#1164) ... * feat: migration v68 — eval_candidates.embedding_column Schema migration ALTERs eval_candidates to add a nullable embedding_column TEXT column. Per-row capture metadata so `gbrain eval replay` reproduces the same column the capture ran against (D16 / CDX-10). NULL-tolerant: pre-v0.36 rows fall back to current default. Renumbered v67→v68 because master claimed v67 for facts_typed_claim_columns during this branch's lifetime. PGLite parity via sqlFor.pglite — same ALTER IF NOT EXISTS. * feat: dynamic embedding column — core (resolver, types, gateway, engines) The read-path foundation for routing search through any populated embedding column, not just OpenAI 1536. src/core/search/embedding-column.ts (new) is the canonical seam. Single source of truth for column → provider/dim/type lookup. Validates registry keys via regex (/^[a-z_][a-z0-9_]*$/), uses Object.create(null) + Object.hasOwn so 'constructor' and other inherited names can't masquerade as registered columns. Identifier-quoting on SQL interpolation as defense in depth. src/core/types.ts widens SearchOpts.embeddingColumn to accept ResolvedColumn descriptors at the engine boundary; adds EmbeddingColumnConfig + ResolvedColumn exports. src/core/config.ts merges embedding_columns + search_embedding_column from the DB plane via loadConfigWithEngine, mirroring the existing embedding_multimodal_model pattern. Handles the no-file case so env-only Postgres installs see DB-plane overrides (codex /ship #3). src/core/ai/gateway.ts: embedQuery(text, opts) + embed(texts, opts) accept embeddingModel + dimensions overrides. isAvailable(touchpoint, modelOverride?) so hybrid asks 'is the active column's provider reachable?' not 'is the global default reachable?' (CDX-4 / D10). Engines: searchVector accepts ResolvedColumn descriptors via normalizeEngineColumn; engine code is config-free and unit-testable. getEmbeddingsByChunkIds(ids, column?) so cosineReScore hydrates from the active column instead of always 'embedding' (CDX-3 / D9). Identifier-quoting belt at the SQL boundary. src/core/eval-capture.ts threads embedding_column from hybridSearch meta into the persisted capture row. * feat: dynamic embedding column — integration (hybrid, ops, doctor) Wires the resolver into hybridSearch, the query op, doctor, and the config command. src/core/search/hybrid.ts: resolves the column once at the boundary, threads the descriptor into engine calls, routes embedQuery through the resolved column's provider/dims, and calls isCacheSafe (not isDefaultColumn) for cache skip so user overrides of the 'embedding' builtin can't leak across vector spaces (CDX-4). cosineReScore now hydrates from the active column. src/core/search/mode.ts: KNOBS_HASH_VERSION 2→3, append-only new fields col= and prov= alongside floor_ratio. Cache rows from different columns or providers now sit in different keyspaces — cross-column contamination impossible. src/core/operations.ts: query op accepts embedding_column param for per-call A/B benchmarking. search op (keyword-only) deliberately does NOT (CDX-9 / D15) — would be silent UX. src/commands/doctor.ts: new embedding_column_registry check. Batch format_type probe (D13) catches dim drift that information_schema.columns.udt_name can't. Batch pg_indexes probe (D5) warns on missing HNSW. Coverage % on active column, gates at <90% (D14), short-circuits on empty brains (codex /ship #5). src/commands/config.ts: validates embedding_columns JSON shape at set time, runs the coverage gate when setting search_embedding_column, uses Object.hasOwn for the registry lookup. src/commands/eval-replay.ts: replay re-runs queries against the captured embedding_column so post-flip-config replays don't surface as false-positive regressions. * test: dynamic embedding column — unit + e2e coverage 50 unit cases for the resolver (resolution chain, registry merge, validation, prototype pollution, descriptor passthrough, isCacheSafe, normalizeEngineColumn). 8 gateway override cases — embeddingModel + dimensions flow into providerOptions, isAvailable(touchpoint, override) routes to the right recipe, unknown models throw clean. 4 cosineReScore + 6 ops + 5 knobs-hash + 7 mode + 9 PGLite E2E + 7 Postgres E2E + 5 eval-replay column metadata. Postgres E2E (gated on DATABASE_URL) covers halfvec(2560) end-to-end on real pgvector, EXPLAIN-visible HNSW index on the alternate column, format_type-based dim drift catch, and the <90% coverage gate. Pins every codex /ship fix: prototype-pollution rejection ('constructor' as column name), descriptor passthrough validation (rejects SQL-shaped strings in dimensions), isCacheSafe semantics (space-based, not name-based). Total: 141 new + extended cases, all green. * chore: bump version and changelog (v0.36.3.0) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: sync to v0.36.3.0 Add CLAUDE.md key-files entry for src/core/search/embedding-column.ts. Annotate hybrid.ts, gateway.ts, doctor.ts, and migrate.ts entries with v0.36.3.0 wave changes (ResolvedColumn threading, embedQuery model override, embedding_column_registry check, migration v68). Document knobs_hash v=2 → v=3 bump under the Search Mode section. Regenerate llms-full.txt from the updated CLAUDE.md so the auto-checked bundle matches source (build-llms.test.ts CI guard). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(ci): two CI failures from v0.36.3.0 1. test/loadConfig-merge.test.ts: update the 'returns null when base config is null' contract test. Pre-v0.36 the function returned null for null base; the codex /ship #3 fix changed that to synthesize a minimal `{ engine: 'postgres' }` so env-only installs see DB-plane overrides. Test now pins the new contract + adds a round-trip case asserting the merge actually surfaces `embedding_columns` / `search_embedding_column` set via gbrain config set on a null base. 2. test/schema-bootstrap-coverage.test.ts was failing because eval_candidates.embedding_column (added by migration v68) wasn't covered by applyForwardReferenceBootstrap. Fix: add the column to PGLITE_SCHEMA_SQL's eval_candidates CREATE TABLE definition (and src/schema.sql for parity) so fresh installs get it natively. The coverage test's third tier (schemaCreateTableCols) now finds it. Regenerated schema-embedded.ts via bun run build:schema. Schema-blob path is cleaner than COLUMN_EXEMPTIONS — fresh installs skip the migration entirely; upgrade installs still run v68. --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-18 21:26:12 -07:00
4 people	af7e5379c2	v0.35.6.0 feat(search): floor-ratio gate for metadata boost stages (closes #1091) (#1129) ... * v0.35.6.0 feat(search): floor-ratio gate for metadata boost stages Opt-in score-based gate on the three metadata-axis boost stages (backlink, salience, recency) inside `runPostFusionStages`. When `SearchOpts.floorRatio` or `search.floor_ratio` config is set, each stage skips results whose post-cosine-rescore score is below `floorRatio * topScore`. Default undefined preserves prior behavior bit-for-bit. Prevents weak-overlap candidates from accumulating metadata boosts and leapfrogging the legitimate primary hit on dense-embedder corpora. Built on the contributor PR from @jayzalowitz (PR #1091, SkyTwin twin-memory layer). Refactored on top: threshold is computed ONCE at runPostFusionStages entry instead of per-stage (single-baseline semantic, order-independent); knobsHash bumped 2->3 so a no-floor cache write can't be served to a floor-enabled lookup; NaN scores skip the boost instead of bypassing the gate; SearchOpts/config/MODE_BUNDLES integration replaces the PR's PostFusionOpts-only surface; no env var (resolveSearchMode is pure by design). Three correctness issues codex outside-voice review caught and this landed with fixed: - Cache contamination via knobsHash() (same bug class as v0.32.3 CDX-4 hotfix for the other search-lite knobs) - NaN scores would have bypassed the gate (NaN < threshold is false in JS); realistic on Voyage flexible-dim / zembed-1 Matryoshka dim drift - Negative top scores would have broken the "single result trivially eligible" claim; gate now disables on no-positive-signal inputs Scope: gates metadata stages only. Exact-match boost (applyExactMatchBoost) runs independently as a lexical-relevance signal by design. Cross-source floor stays global (per-source deferred to v0.36 if federated-read users hit the suppression). Default-on for any mode bundle deferred until gbrain-side ablation against longmemeval / whoknows / suspected-contradictions / BrainBench-Real (TODOS.md). Plan + 9-decision review trail (D1-D9): ~/.claude/plans/swift-sniffing-nygaard.md. Empirical motivation, failure-mode framing, dense-embedder targeting, and the 0.85 starting value all from @jayzalowitz's labeled-retrieval ablation. Integration shape is gbrain-side. Test surface: 30+ new cases (computeFloorThreshold edge cases including T1a NaN / T1b negative top, three boost-function gate parity tests including T6 IRON-RULE applyRecencyBoost regression, runPostFusionStages single-baseline composition pin, KNOBS_HASH_VERSION bump from 2 to 3, floor-ratio-changes-hash cache-contamination prevention, loadOverridesFromConfig coverage for search.floor_ratio config key). bun run verify clean; full unit suite 6753 pass / 0 fail. Co-Authored-By: Jay Zalowitz <jayzalowitz@gmail.com> Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: rewrite v0.35.6.0 CHANGELOG ELI10-lead-first; codify the rule in CLAUDE.md CHANGELOG entry for v0.35.6.0 was readable only by someone who already understood gbrain's internals (RRF, knobsHash, MODE_BUNDLES, runPostFusionStages, Matryoshka, CDX-4). Rewrote it so the first ~150 words explain what shipped in everyday English, with a concrete worked example, before any file paths or function names appear. Itemized changes section keeps the technical precision for engineers who need it. Then codified the rule in CLAUDE.md so future release entries land the same way. The "Release-summary template" section now has an iron rule: "lead ELI10, get precise after." No file paths or internal constants in the first 150 words; user-visible behavior change first; everyday-language column headers in any tables. Technical precision is required (the entry is still the technical record) but lives BELOW the plain-English lead, never before it. Smell test: if a reader who has never opened gbrain can walk away from the first 150 words knowing what shipped and whether they care, the entry passes. bun run build:llms regenerated to pick up the CLAUDE.md change (CI guard test/build-llms.test.ts pins committed bundles against fresh generator output). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Jay Zalowitz <jayzalowitz@gmail.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-17 15:41:43 -07:00
3 people	baf1a47798	v0.35.0.0 feat: ZeroEntropy zembed-1 + zerank-2 reranker (#1008) ... * feat(ai): add ZeroEntropy recipe + reranker touchpoint type Widens `TouchpointKind` with `'reranker'`, adds `RerankerTouchpoint` interface, extends `Recipe.touchpoints` and `AIGatewayConfig` to carry reranker model state. Registers `zeroentropyai` recipe (zembed-1 embeddings + zerank-{2,1,1-small} rerankers) in the recipe registry. Recipe declares the 7 Matryoshka dims (2560/1280/640/320/160/80/40), Voyage-style dense-payload hedge (chars_per_token=1, safety_factor=0.5), and 5MB rerank payload cap. Pinned by test/ai/zeroentropy-recipe.test.ts including F1 regression (implementation literal is 'openai-compatible') and F2 regression (base_url_default ends with /v1, no doubling). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(ai/dims): thread input_type 4th-arg + ZE flexible-dim allowlist `dimsProviderOptions` gains an optional `inputType?: 'query' | 'document'` 4th param so asymmetric providers (ZE zembed-1, Voyage v3+) can route query-side vs document-side encoding. Per-model filtering inside the openai-compatible branch keeps `input_type` from leaking to symmetric providers (OpenAI text-3, DashScope, Zhipu) that would 400 on it. Adds `ZEROENTROPY_VALID_DIMS` allowlist (2560/1280/640/320/160/80/40), `supportsZeroEntropyDimension(modelId)`, and `isValidZeroEntropyDim(dims)`. Throws `AIConfigError` with paste-ready fix hint when zembed-1 is configured with an invalid dim (most common: defaulting to 1536 from DEFAULT_EMBEDDING_DIMENSIONS). The 4th-arg is optional; existing call sites (1 production + N tests across Voyage/OpenAI/DashScope/Zhipu/MiniMax) compile unchanged. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(ai/gateway): zeroEntropyCompatFetch + embedQuery + gateway.rerank() Two seams land together because they share the same recipe + auth path. zeroEntropyCompatFetch handles ZE's non-OpenAI-compatible wire shape: - URL rewrite: SDK's `${base_url}/embeddings` -> `${base_url}/models/embed` - Body inject: `input_type` (default 'document'; 'query' when threaded via providerOptions) + explicit `encoding_format: 'float'` - Response rewrite: `{results: [{embedding}]}` -> `{data: [{embedding, index}]}` so the AI SDK's openai-compat schema validates - `usage.prompt_tokens` injected from `total_tokens` (Voyage hit the same SDK schema requirement at :655) - Layer 1 (Content-Length) + Layer 2 (per-embedding size) OOM caps via tagged `ZeroEntropyResponseTooLargeError` (kept separate from `VoyageResponseTooLargeError` because the Voyage cap tests do structural source-text greps pinning the Voyage name) - Wired in `instantiateEmbedding()` via the existing `recipe.id === 'voyage' ? voyageCompatFetch : ...` ternary pattern embedQuery(text) routes `inputType: 'query'` through dimsProviderOptions for the search hot path. Companion to embed(texts) which now takes an optional 2nd-arg inputType (defaults to undefined -> 'document' for asymmetric providers). gateway.rerank() is the new native HTTP path (no AI-SDK reranking abstraction). Resolves the configured reranker model via `getRerankerModel()` (new accessor), parses + asserts the model is in the recipe's touchpoint.reranker.models allowlist (CDX2-F11: assertTouchpoint does not enforce allowlists for openai-compatible recipes — rerank() does it directly). Posts to `${recipe.base_url}/models/rerank` with bearer auth. Returns `RerankResult[]` sorted by `relevanceScore`. Errors classify into `RerankError.reason: 'auth' | 'rate_limit' | 'network' | 'timeout' | 'payload_too_large' | 'unknown'`. 5s default timeout. Pre-flight payload guard rejects bodies over `recipe.max_payload_bytes` BEFORE any HTTP call so applyReranker can fail-open without burning a round-trip. `_rerankTransport` + `__setRerankTransportForTests` mirror the embed test seam. `AIGatewayConfig.reranker_model` + isAvailable('reranker') branch + configureGateway / reconfigureGatewayWithEngine extensions thread the reranker model through the same state path as embedding/expansion/chat. `applyResolveAuth` + `defaultResolveAuth` widen the touchpoint param to include `'reranker'`. `KnownTouchpointKey` + `getTouchpoint()` in model-resolver widen to cover `'reranker'`. Pinned by: - test/ai/embedQuery.test.ts (8): returns single Float32Array, threads input_type='query' for ZE, drops field for OpenAI text-3, back-compat: legacy embed() callers without 4th arg keep their previous Voyage no-input_type shape - test/ai/rerank.test.ts (21): URL (F2 regression — no /v1/v1/), body shape, bearer header, response parsing, error classification across 6 HTTP shapes, payload pre-flight (no transport call), allowlist enforcement - test/ai/zeroentropy-compat-fetch.test.ts (14): structural source assertions for the shim that mirror test/voyage-response-cap.test.ts — URL rewrite path, body injection, response rewrite, usage.prompt_tokens injection, OOM caps Layer 1 + Layer 2 + instanceof rethrow, instantiateEmbedding wiring branch Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(search): applyReranker + rerank-failure audit + hybrid wire-in src/core/search/rerank.ts — the call-site abstraction. Slices the top `opts.topNIn` deduped candidates, sends to gateway.rerank(), reorders by relevanceScore desc, appends the un-reranked tail in its original RRF order (recall protection). Fail-open on every RerankError.reason: logs via `logRerankFailure` and returns the input array unchanged. Stamps `rerank_score` onto reordered items. `topNOut: null` is the explicit "don't truncate" signal — distinct from `undefined` (fall through to mode bundle); pin in test (CDX2-F16). src/core/rerank-audit.ts — failure-only JSONL audit at `~/.gbrain/audit/rerank-failures-YYYY-Www.jsonl` (ISO-week rotation; mirrors `src/core/audit-slug-fallback.ts`). Exports `logRerankFailure` + `readRecentRerankFailures(days)`. **No `logRerankSuccess`** — CDX2-F22 deliberately drops success-event logging: writing once per tokenmax search is hot-path I/O churn AND success events leak query volume + timing into a local audit. The doctor check reads `search.reranker.enabled` first so "no events in window" gets interpreted correctly (disabled -> healthy by definition; enabled -> healthy because nothing failed). Query text is SHA-256-prefix-hashed (8 hex chars) for privacy. Honors `GBRAIN_AUDIT_DIR`. src/core/search/hybrid.ts — slots `applyReranker` between `dedupResults()` and `enforceTokenBudget()` in the main RRF path. Resolution: per-call `opts.reranker` overrides; otherwise pulled from the resolved mode bundle (tokenmax -> enabled, others -> disabled in commit 5). Cache rows store final reranked results; the bumped knobsHash (commit 5) ensures rows can't leak across reranker configs. src/core/types.ts — adds `SearchOpts.reranker` as a structural type so callers can pass per-call overrides; runtime type lives in src/core/search/rerank.ts (avoids circular import). Tests: - test/search/rerank.test.ts (14): reorder, tail preserve, fail-open on every error class, topNOut null vs number, score stamping, empty + enabled=false pass-through - test/rerank-audit.test.ts (10): JSONL round-trip, error_summary truncated to 200, corrupt rows skipped, missing dir -> [], ISO-week rotation walks current + previous week, no logRerankSuccess export (CDX2-F22 contract) - test/search/hybrid-reranker-integration.test.ts (6): reranker fires when enabled, doesn't when disabled, reorders correctly, preserves tail, stamps rerank_score, fail-opens on rerankerFn throw — uses PGLite + stubbed embed transport, no API keys Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(search/mode): reranker mode-bundle fields + KNOBS_HASH_VERSION v=2 Extends `ModeBundle` with five reranker fields: `reranker_enabled`, `reranker_model`, `reranker_top_n_in`, `reranker_top_n_out`, `reranker_timeout_ms`. Per-mode defaults: - conservative -> enabled=false (cost-sensitive) - balanced -> enabled=false (opt-in via search.reranker.enabled) - tokenmax -> enabled=true (the high-cost-tolerant tier; ~$0.0003/query) Defaults model to `zeroentropyai:zerank-2`, topNIn=30, topNOut=null (no truncate by default; preserves tokenmax's searchLimit=50 end-to-end per CDX2-F16), timeout_ms=5000. `SearchKeyOverrides` + `SearchPerCallOpts` + `resolveSearchMode.pick` all extend to thread the new fields through the resolution chain (per-call -> per-key config -> mode bundle -> default). `loadOverridesFromConfig` adds parsers for the five new `search.reranker.*` config keys. `top_n_out` parsing distinguishes three input shapes (CDX2-F15): key absent -> undefined (fall through to mode bundle) 'null'|'none'|empty -> explicit null (no truncate) positive integer -> that number `SEARCH_MODE_CONFIG_KEYS` extends so `gbrain search modes --reset` clears the reranker overrides too. **KNOBS_HASH_VERSION bumps 1 -> 2** (CDX1-F14). Five new entries appended to `parts[]` (append-only convention CDX2-F13; reordering existing fields would silently rebuild every existing cache row). Includes `reranker_timeout_ms` so a 5s -> 100ms change invalidates stale rows (CDX2-F14: more fail-opens = different search behavior). Mid-rolling-deploy note (CDX2-F12): v=1 and v=2 processes produce distinct cacheRowIds for the same (source_id, query_text). Expect a temporary hit-rate dip + cache-row doubling for hot queries. Clears naturally within `cache.ttl_seconds` (default 3600s). src/commands/search.ts extends `KNOB_DESCRIPTIONS` with five new entries so `gbrain search modes` renders them. test/search-mode.test.ts extends the three bundle fixtures and bumps the KNOBS_HASH_VERSION expectation to 2. Pinned by test/search/knobs-hash-reranker.test.ts (13): each of the 5 reranker fields independently flips the hash, top_n_out=null renders stable, append-only convention enforced via source-position assertion. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(doctor): probeRerankerConfig + reranker_health check `gbrain models doctor` gains two new probes: - `probeRerankerConfig` (zero-network) validates that the configured reranker model resolves through the recipe registry, that the recipe declares a `reranker` touchpoint, and that the model is in `touchpoint.models[]`. Direct allowlist check here — assertTouchpoint does not enforce allowlists for openai-compatible recipes (CDX2-F11). Surfaces paste-ready `gbrain config set search.reranker.model <zerank-2|zerank-1|zerank-1-small>` fix hint. - `probeRerankerReachability` (1-token-equivalent) sends a minimal `{query: "probe", documents: ["probe"]}` rerank to verify auth + URL. Failures classify via `classifyError` into auth/rate_limit/network/ unknown. Skipped silently when reranker is unconfigured. Also extends `probeEmbeddingConfig` with a `providerId === 'zeroentropyai'` branch that catches the silent-1536-default bug class for zembed-1 configurations (same posture as the existing Voyage branch). `ProbeResult.touchpoint` widens to include `'reranker_config'`. `gbrain doctor` adds `checkRerankerHealth` to both the abbreviated (doctorReportRemote) and full (runDoctor) check sets. Logic: 1) Read `search.reranker.enabled` first. Disabled + no failures => 'reranker disabled'. Enabled + no failures => healthy. 2) Walk last 7 days of ~/.gbrain/audit/rerank-failures-*.jsonl. 3) ANY auth failure warns (config-time problem the probe should have caught — surface it). 4) ANY payload_too_large failure warns (workload mismatch). 5) Transient (network/timeout/rate_limit) warns at >=5 in window. Below that they're noise; reranker fails open anyway. CDX2-F21 blind-spot fix: reading enabled state first means "no events" gets interpreted correctly — never confuses "never-used" with "success logging broken" (the latter is impossible because there is no success logging by design, CDX2-F22). Engine-agnostic; file-based + one config-key read. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(e2e): ZeroEntropy live API round-trip + wire into Tier 2 CI test/e2e/zeroentropy-live.test.ts exercises the full stack against the real api.zeroentropy.dev: embed (default 2560-dim + flexible 1280), embedQuery (asymmetric query side), batch embed (3 distinct vectors), rerank (3 docs sorted by relevance score, photosynthesis-relevant docs beat the irrelevant cat doc), rerank with topN truncation. Gated on `ZEROENTROPY_API_KEY`: every test prints `[skip]` and returns early without assertions when the env var is unset, so fork PRs and contributor machines without a ZE account stay green. CI wire-up: `.github/workflows/e2e.yml` Tier 2 step adds `test/e2e/zeroentropy-live.test.ts` to its `bun test` invocation and exposes `ZEROENTROPY_API_KEY: ${{ secrets.ZEROENTROPY_API_KEY }}` to the runner. The secret is set on garrytan/gbrain at the repo scope (separately from this commit — set via `gh secret set` so the value never lands in source). Tier 1 stays mechanical (no API keys); Tier 2 is the natural home for provider-live tests because it's already the API-keyed lane. Cost: each full run fires ~6 small HTTP calls totaling well under a cent at the published $0.025/1M-token rate. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.33.3.0 feat: ZeroEntropy zembed-1 + zerank-2 reranker Release notes for the ZeroEntropy support wave: zembed-1 embeddings (flexible-dim 2560/1280/640/320/160/80/40, asymmetric input_type) and zerank-2 cross-encoder reranking land as a new openai-compatible recipe alongside OpenAI/Voyage. Reranker defaults ON for tokenmax mode, OFF for conservative/balanced (~$0.0003/query at tokenmax topNIn=30; rounding error vs the tier's $700/mo Opus pairing per the CLAUDE.md cost matrix). Search now ends with `RRF -> dedup -> reranker -> token-budget` when reranker is enabled; fails open to RRF order on any error class (audit-logged at ~/.gbrain/audit/rerank-failures-*.jsonl). `KNOBS_HASH_VERSION` bumps 1 -> 2 to fold reranker config into the query_cache row key. Rolling-deploy operators should expect a temporary cache hit-rate dip + cache-row doubling for hot queries (clears naturally within `cache.ttl_seconds`, default 3600s). Files in this commit are pure docs / version bump: - VERSION + package.json bump to 0.33.3.0 - CHANGELOG.md release-summary entry with "How to take advantage" block - CLAUDE.md Key Files annotations for the new recipe + rerank.ts + rerank-audit.ts + gateway extensions - docs/ai-providers/zeroentropy.md one-pager (setup, knob reference, failure observability, troubleshooting table) - skills/migrations/v0.33.3.md (purely informational: no required user action; reranker is opt-in everywhere, ZE embedding is opt-in) - llms-full.txt regenerated to match CLAUDE.md Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-15 06:48:36 -07:00