Unified gene search for client, CLI & MCP (sub-project C)

[timtreis]

Unified gene search for the client, CLI & MCP (sub-project C)

Brings the sddb SDK, CLI, and sddb-mcp server to the same gene-search semantics as the web (sub-project B) and engine (A): multi-gene AND, search by symbol OR Ensembl id, and bronze included by default (flagged) — fixing today's single-symbol, exact-match, validation="pass" behavior.

Sub-project C of the unified gene-search design (docs/superpowers/specs/2026-10-08-gene-search-design.md, §5). No new server-side artifact — the client builds the symbol↔feature_id resolution from the existing gene_index.parquet it already downloads.

What changed

• GeneIndex (genes.py) — new resolve(tokens); where_expressed(genes: str | list[str], *, mode="all"|"any", min_fraction=None, validation=None) resolves each token by symbol OR Ensembl feature_id (casefolded), AND-intersects (or unions) across genes; ranked now also matches Ensembl ids. Default flipped to validation=None → bronze included, with a validation= opt-out; rows carry validation_status/tier. Casefolded columns cached once (the index is ~11M rows).
• Catalog.query — expressing accepts one gene or a list + mode; single-string stays back-compat; validates mode up front; no double validation filtering.
• MCP genes tool — genes(symbols, organism, tissue, disease, assay, mode="all", include_bronze=True); facets + genes compose through query.
• CLI — query --gene repeatable (AND; --expressing kept as alias); genes accepts multiple genes (one → ranked detection table, several → AND membership) with a --validation opt-out; bronze flagged in output.
• Back-compat — datasets_with alias, single-symbol calls, and catalog.query(expressing="SYM") all unchanged in behavior (minus the deliberate bronze-default flip).

Safety

feature_id is nullable "string" (pd.NA for legacy symbol-only genes) — all resolution is vectorised with .fillna(False), never a scalar NA truth-test (the crash class that bit sub-project A, caught there by the final review).

Tests

pytest — 270 passing, including a cross-surface consistency guard (test_cross_surface_canonical_membership) pinning the client's gene→dataset membership to the spec §3 canonical rules A's engine tests encode, so the two repos can't silently diverge; plus real-pd.NA fixtures, AND/ANY, bronze default, and symbol↔Ensembl parity across SDK/CLI/MCP.

Built subagent-driven (per-task + opus whole-branch review); the per-task review caught a CLI single-gene Ensembl gap, now fixed at the source (ranked) with a parity test.

Follow-up (non-blocking)

Spec §5 asks the MCP/CLI-multi results to carry per-gene detection (fraction_obs_detected) per dataset; v1 returns catalog rows + membership only (detection is ambiguous under multi-gene AND — which gene's number?). The single-gene CLI genes table already shows detection via ranked. A per-gene detection sub-record is a clean fast-follow if wanted.

[codecov]

Codecov Report

❌ Patch coverage is 97.67442% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 92.00%. Comparing base (de9cb31) to head (421c137).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
src/sddb/genes.py	95.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #14      +/-   ##
==========================================
+ Coverage   91.67%   92.00%   +0.33%     
==========================================
  Files          19       19              
  Lines        1429     1476      +47     
==========================================
+ Hits         1310     1358      +48     
+ Misses        119      118       -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.