Ship offline LanceDB search for agent docs

[stale2000]

Summary

comfy-cli[docs-search] installs a version-matched companion package with a 59.3 MiB compressed offline search pack: 337 documentation chunks, precomputed 384-dimensional BGE vectors, the pinned local ONNX query encoder and tokenizer, and a LanceDB BM25 index. The base CLI remains lightweight and keeps its existing local BM25 search.

comfy docs status reports available retrieval modes. docs search --mode auto selects hybrid retrieval when the matching pack is installed; bm25, semantic, and hybrid can also be selected explicitly. Search output includes the backend, retrieval mode, source section, corpus and model identity, confidence evidence, and fallback reason. docs show reads the cited section. Searches use packaged assets and do not download a model; absent or incompatible optional assets leave auto mode on core BM25, while explicit semantic/hybrid requests return a structured error.

The bundled comfy skill teaches shell-capable agents to search, read relevant sections, and reformulate a missed query once before answering from retrieved sources. This exposes the workflow through the CLI; it does not add native tools to the separate local Comfy-agent runtime.

The release workflow builds and validates the data package alongside comfy-cli, then smoke-installs the optional extra from PyPI. PyPI trusted publishing needs to be configured for both package names before release.

Example output

The following is the exact stdout from the hybrid search command against wheels built from the source distributions, run outside the checkout:

$ comfy --json docs search 'A job is still pending and seems frozen, what should I check?' --mode hybrid --limit 1
{"schema": "envelope/1", "type": "envelope", "ok": true, "command": "docs search", "version": "0.0.0", "where": null, "data": {"query": "A job is still pending and seems frozen, what should I check?", "results": [{"id": "comfy-debug:job-stuck-triage", "title": "comfy-debug agent guide", "headings": ["Job-stuck triage"], "source": "comfy_cli/skills/comfy-debug/SKILL.md", "source_line": 128, "excerpt": "If a prompt seems to hang:\n\n```\n# 1. Is it still tracked?\ncomfy --json jobs ls\n\n# 2. What does the server think?\ncomfy --json jobs status <prompt_id>\n\n# 3. Watch live events (NDJSON, one per line)\ncomfy --json-stream jobs watch <prompt_id>\n```\n\nThree possible answers:\n\n| Symptom | Likely cause | Fix |\n|---|---|---|\n| `status: pending`, `queue_position > 0` | Earlier jobs ahead of you | Wait or cancel them |\n| `status: running` but no progress events | A long sampler step, or a hung custom node | Wait one sampler-step's worth; if still stuck, interrupt |\n| `status: error` with no `error_message` | Server crashed mid-execution | Check the Comfy Cloud dashboard or server logs (cloud), or the stdout of `comfy launch` (local) |", "score": 0.032786883413791656, "score_type": "rrf"}], "zero_hit": false, "has_more": true, "search_backend": "lancedb-hybrid-rrf", "retrieval_mode": "hybrid", "corpus_hash": "1d62f56018524ac95c81a250666f0f4405c545328e6670b7b338ecb3a17af519", "pack_version": "0.0.0", "model": "BAAI/bge-small-en-v1.5", "fallback_reason": null, "highest_vector_similarity": 0.7049703896045685, "fts_term_coverage": 0.75, "query_mode": "hybrid"}, "error": null}

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{Comment @coderabbitai help to get the list of available commands.}

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	onnxruntime@​1.23.2
	onnxruntime@​1.24.3
	pyarrow@​24.0.0
	lancedb@​0.25.0
	tokenizers@​0.23.2

View full report