Repository navigation
Atlas step 3: CLI mode — one-shot commands at Python surface parity #5353
Description
Step 3 of the Atlas binary+service epic (#5350). Design of record: doc/2026-11-04T08-07-13Z_design_atlas_binary_service/ (§1, §4 atlas-search bin).
Scope
- The
atlas-searchbinary's one-shot mode at full Python surface parity:searchandget-chunksubcommands, the Python's flags (--model/--vec-table/--embedder-equivalents where they still make sense,--trunc,--max-sensitivity, filters,--pool,--vector-backend,--backend turso|local,--text), JSON envelope output identical in shape to the Python's, and the human-readable--textrendering. - Standalone operation is the default and must be complete: embed the query in-process (step 1), talk to Turso or a local publish file directly (step 2). No daemon required, ever.
- Token resolution for Turso identical to the Python's order: env, Bitwarden by name (
turso.atlas-ro-token/turso.atlas-read-only-token/atlas-ro),tursoCLI read-only mint with the 20 h cache. --via-service/ATLAS_SEARCH_VIA=service: route through a running service (step 4) usingatlas-proto; contract is prefer service, fall back to standalone loudly (a note in the envelope'snotes), never a silent hang or failure. Until step 4 lands, via-service against no service exercises exactly that fallback path.- Degradation parity: with no model present, FTS-only search and
get-chunkwork; vector/hybrid fail loudly (design §4).
Dependencies: step 1 (embedder), step 2 (core).
Verification gate (exit criteria)
- A flag-for-flag comparison run: a fixed battery of representative queries (filtered, ceiling-raised, FTS-only, get-chunk with neighbors, local-backend against a publish copy) produces envelopes matching the Python's (same results, same order, same
rank_sources; scores within float formatting). - Cold one-shot latency measured and recorded on this issue vs the Python's ~35 s baseline (the embedder load is the expected win; report the real number either way).
Out of scope: serve mode (step 4), packaging/deploy (step 5), any default flip (step 6).
Activity
Merge pull request #5377 from developing-today/atlas-step3-cli
dezren39 commentedon Nov 4, 2026
Step 3 DONE — PR #5377 merged
9128ee816f281a48c3fc4504e3a67dd303dccc6f(API-verified).Built: the
atlas-searchbinary crate (pkgs/atlas-search/crates/atlas-search) —search+get-chunksubcommands over atlas-core/atlas-embed at Python surface parity (flags, defaults, envelope,--text, exit codes: die-fatals exit 2, get-chunk not-found exit 1, backend/transport failures exit 1 with the message instead of a traceback). Standalone by default (Turso via the read-only token chain, or--backend local); the embedder loads lazily so FTS/get-chunk work with no model present and vector/hybrid fail loudly without one.--via-serviceimplements prefer-with-loud-fallback now; the job-protocol client swaps in behindservice::attemptin step 4. Declared divergences (in the PR body):--embedder fastembed/ non-Snowflake--modelfail loudly for vector/hybrid (atlas-embed is the Snowflake ST path only); clap help formatting; a test-onlyATLAS_SEARCH_QVEC_FILEhook mirroring the fixture generator's monkeypatch.Gate results (laptop, rustup 1.99.0, sccache wrapper disabled via
--configafter it served a stale 1.98.1 rmeta — the step-1 trap, E0514):json.dumps(indent=1, ensure_ascii=False)rendering (14/14).--textgoldens generated by the Python'srender_textitself, byte-equal. (This needed a CPython-compatible JSON writer: serde_json prints0.000087where CPython prints8.7e-05, and 2-space pretty indent vs Python's 1.)--via-service→ stderr warning (service at http://127.0.0.1:18760 unreachable (io: Connection refused (os error 111)); falling back to standalone) + the same note in the envelope; results identical to standalone.cargo test --workspace(29 tests), clippy, fmt — clean.Notes for step 4/5 are in the PR body (transport seam; model/ORT resolution chain + the closure must carry libstdc++.so.6 + libz.so.1 — verified live with the venv ORT plus the store gcc-lib/zlib pair). Chaining to step 4 (#5354) per the run-to-completion instruction.