Skip to content

gaia search

Search external retrieval providers for Gaia authoring. LKM (Large Knowledge Model) turns papers into source-grounded reasoning graphs: questions, claims, reasoning chains, and evidence become addressable units, aligned across papers. In Gaia CLI, the LKM backend is a read-only source of papers, paper knowledge items, reasoning chains, workflows, bibliographic references, and extracted per-paper graphs.

gaia search lkm knowledge <query>           Find claims/questions/abstracts by topic
gaia search lkm reasoning <query>           Find similar arguments or experiments
gaia search lkm reasoning --claim-id <id>   Fetch reasoning for a supported conclusion
gaia search lkm nodes <ids...>              Fetch LKM node records by id
gaia search lkm package --paper-id <id>     Fetch one LKM paper package candidate
gaia search lkm package --package-id paper:<id>
gaia search lkm package --doi <doi>
gaia search lkm package --title <title>
gaia search lkm references --paper-id <id>  Look up references / cited-by lists
gaia search lkm references --doi <doi>
gaia search lkm feedback --type bug <text>  Submit LKM service/data feedback
gaia search lkm docs                        Print API documentation links
gaia search lkm auth ...                    Manage the LKM access key

These verbs search those reasoning graphs. Search and lookup calls cost 0.05 CNY each, covered first by LKM's personal monthly 1,000-call quota. A local PDF that may not be in LKM is gaia extract (1.00 CNY per successful paper, or 0.10 CNY on a cache hit), not this group.

The current implementation is an LKM provider adapter. Search-oriented LKM verbs write raw LKM JSON to stdout, or to --out PATH. Gaia follow-up suggestions are printed on stderr by default so stdout stays machine-readable JSON. Use --no-hint to suppress those suggestions.

Conceptually, LKM searches over scientific papers' conclusion claims, weak-point / highlight claims, addressed problems, open questions, reasoning chains, and workflows. LKM is not Gaia's local IR, not a Gaia knowledge package, and not a generic graph API. Treat its results as corpus-backed evidence with paper provenance that can be inspected directly or materialized into Gaia packages with explicit follow-up commands.

LKM has two complementary search surfaces:

  • knowledge <query> performs a fused search over selected scopes: claims, research questions, abstracts, and optionally complete reasoning chains by topic or wording.
  • reasoning <query> searches for a similar whole argument, derivation, calculation, experimental process, or workflow.

Optional follow-ups:

gaia search lkm knowledge "solid state battery dendrite suppression" --scopes conclusion
gaia search lkm knowledge "unresolved battery failure mechanisms" --scopes open_question
gaia search lkm reasoning "solid state battery dendrite suppression"
gaia search lkm reasoning --claim-id <gcn_id>
gaia search lkm package --paper-id <paper_id>
gaia search lkm references --paper-id <paper_id>
gaia pkg add --lkm-index bohrium --lkm-paper <paper_id>

Any global gcn_... / node id can be inspected with nodes. Use --claim-id only for a conclusion claim reported with has_reasoning=true when you want its supporting reasoning graph. Premise and question ids cannot be used with --claim-id. Use package to fetch a paper graph, references for bibliographic forward-reference / cited-by cards, and gaia pkg add when that paper should become an editable dependency of the current Gaia package.

Omit --scopes to use LKM's default: conclusion claims plus abstracts. Use knowledge --scopes conclusion when the goal is only conclusion claims, or --scopes premise for premises. Response kind values such as highlight / weak_point are claim display labels, not search filters. For best recall, use default hybrid mode with --keywords. Use --retrieval-mode semantic when speed matters more than recall quality. Use --retrieval-mode lexical only for exact keyword matching. knowledge tracks the latest POST /search API shape: --sort-by maps to sort_by (relevance, recent, journal, or comprehensive), while repeatable --paper-id / --paper-ids and --doi / --dois map to filters.paper_ids and filters.dois. --title maps to filters.title. --publication-date-start, --publication-date-end, and --limit-publication-date/--no-limit-publication-date map to the LKM publication-date filters. Dates must be YYYY-MM-DD. --paper-id(s) and --doi(s) each accept up to 50 values; paper ids must be bare numeric ids without a paper: prefix. --offset is capped at 2000; each --keywords value is at most 100 bytes. The default Gaia CLI ordering is comprehensive; the server applies its own default date window unless --no-limit-publication-date is passed. --scopes abstract asks for paper-level abstract hits; use them as paper background context rather than Gaia claims. Same-paper related entries are folded context for the representative paper hit, not cross-paper recommendations or complete paper graphs.

knowledge returns 10 hits by default; pass --limit to request 1–100.

The full scope hierarchy is:

abstract
claim
├── premise
└── conclusion
question
├── problem
├── open_question
└── subproblem
reasoning_chain

Parent scopes include their child roles. Use --scopes question to search all research questions, or select problem, open_question, or subproblem when only one question role is relevant. The response keeps these hits as type: "question" and reports the selected role in role. LKM normalizes its internal open_question_sub role to the public open_question value.

--scopes reasoning_chain instead asks this endpoint to include complete chain hits in the fused result. It can be combined with any claim, question, or abstract scope; use gaia search lkm reasoning <query> for the dedicated reasoning-chain search surface.

reasoning --claim-id asks LKM for the graph-shaped reasoning response by default (format=graph). In practice this means Gaia receives a supporting reasoning graph for one target claim.

reasoning <query> searches whole reasoning chains and workflows (POST /reasoning/search), not individual paper knowledge hits. Query mode accepts --retrieval-mode, --keywords, --sort-by, --paper-id / --paper-ids, --doi / --dois, --title, publication-date filters, --offset, and --limit, and the raw response carries reasoning_chains and total; it may also include papers when the backend provides paper metadata. Query-mode --sort-by maps to sort_by and accepts relevance, recent, journal, and comprehensive; --paper-id(s), --doi(s), and --title map to LKM filters and are intersected upstream. Query mode returns 10 chains by default; pass --limit to request 1–100. --claim-id mode instead calls GET /claims/{id}/reasoning and accepts --max-chains plus --sort-by comprehensive|recent.

nodes fetches LKM node records by id. The server returns hits in request order and may report partial misses in not_found; partial misses do not make the response a business error. This endpoint does not apply a visibility filter.

package requires exactly one identifier flag: --package-id, --paper-id, --doi, or --title. --title may return several candidate papers and accepts --title-resolve-limit; the other identifier modes address one paper directly. The CLI keeps /papers/graph on the default raw paper-graph shape.

references looks up bibliographic paper cards (POST /papers/reference) for papers already identified by --paper-id and/or --doi (repeatable; at least one side required). Combined seeds are capped at 20 before dedupe. A paper: prefix on --paper-id is stripped. The three include switches are always sent and match the HTTP defaults: --with-abstract (on), --with-reference (off), --with-cited-by (on). The response uses data.papers. An empty paper id means LKM has not covered that record; references / cited_by are null when that list was not queried and [] when it was queried and empty. A successful hit with a numeric LKM id may hint gaia search lkm package --paper-id <id> on stderr.

feedback is a write endpoint (POST /feedback) for reporting LKM service or data issues. It accepts a required --type bug|feature|question and content text, plus at most one optional target: --gcn-id for a node or --paper-metadata-id for a paper metadata record. It returns the raw feedback envelope and does not emit Gaia follow-up hints.

docs prints the online LKM API documentation links. The Apifox docs are the source of truth for endpoint parameter and response details:

gaia search lkm docs

Before changing gaia search lkm behavior, options, or help text, verify the relevant endpoint in Apifox instead of relying on copied local summaries.

Use --index <id> on LKM verbs to select a configured LKM index. This follows the same split as pip / uv: the dependency or source ref stays stable, while the index name resolves to the real URL and credential configuration. This build ships bohrium as the default configured index; --server remains a compatibility alias. Additional indexes can be added by setting GAIA_LKM_INDEX_<NAME>_URL.

Design Contract

The search group is provider-shaped by design:

  • lkm searches a configured LKM API index, defaulting to bohrium.
  • Future pkg search should search installed Gaia Python packages.
  • Future cross-provider search should wait until both providers share a stable Gaia-native result envelope.

Search commands should not mutate the current project. They may suggest follow-up actions on stderr, but package materialization, installation, and dependency changes belong to gaia pkg add.

LKM source identities include the LKM index id so multiple backends can coexist without id collisions. Gaia accepts canonical refs such as lkm:bohrium:paper:<paper_id> and lkm:bohrium:claim:<claim_id> in gaia pkg add; human-facing hints prefer explicit flags, for example gaia pkg add --lkm-index bohrium --lkm-paper <paper_id>.

LKM paper results are name-first and id-backed in the upstream payload. Paper titles remain display metadata; paper ids remain the stable identity used by gaia pkg add, registry lookup, and local package metadata.

gaia pkg add --lkm-index <id> --lkm-paper <paper-id> consumes the paper action ref by fetching /papers/graph, generating a project-local Gaia package under .gaia/lkm_packages/, compiling that package, and adding it as an editable uv dependency. The generated package remains a standard Python Gaia package, so downstream code imports it with normal Python imports. Generated LKM reasoning links use depends_on(...) by default: think of this as the scaffold form of derive(...), preserving the dependency relation without yet making it a formal Gaia reasoning edge in IR/BP.

LKM retrieval score / rerank_score values are ranking signals only. They must not be copied into Gaia priors, beliefs, or warrant strengths.

reasoning returns raw reasoning-chain search results. In graph-shaped responses, Gaia reads each reasoning step's conclusion claim as the claim being produced by that step. Incoming claim edges such as previous_conclusion_of, weakpoint_of, and highlight_of are dependencies of the reasoning step. A reasoning step with no usable incoming dependencies is incomplete context, not a valid derive(..., given=[]).

package returns the raw paper graph under data.papers[]. Paper-level addressed_problems / open_questions stay next to the graph; conclusion dependencies are read from graph.edges such as previous_conclusion_of, weakpoint_of, highlight_of, subproblem_of, and concludes.

references returns bibliographic paper cards under data.papers[]. Neighbor lists are paper metadata, not graph nodes or edges.

The search / pkg add boundary is tracked in docs/specs/2026-05-20-gaia-search-design.md.

Implementation

gaia.cli.commands.search

gaia search — retrieval backends for knowledge-package authoring.

Today this group hosts a single backend, lkm (Bohrium's Large Knowledge Model: source-grounded paper reasoning graphs). The search parent is deliberately a thin shell so future non-LKM retrieval backends can slot in alongside it without reshaping the verb tree.

gaia.cli.commands.search.lkm

gaia search lkm — Bohrium LKM retrieval for Gaia authoring.

Gaia-facing verbs wrap the public LKM HTTP endpoints. Search verbs write raw JSON to stdout or, with --out PATH, atomically to a file; optional follow-up suggestions are emitted on stderr.