mosaic index

Builds the vector index of your cached papers: an embedding of each paper's text, for search --semantic, ask and chat. With --enrich-citations it also fetches the citation edges between them, for network.

Usage

mosaic index                          # embed every cached paper not yet indexed
mosaic index --query "hall thruster"  # only the papers matching a query
mosaic index --from refs.bib          # only the papers of a BibTeX file
mosaic index --reindex                # embed everything again (after changing the model)
mosaic index --enrich-citations       # then fetch citation edges from OpenAlex and Crossref

Behaviour

It needs the rag extra (sqlite-vec) and an embedding model: mosaic config --embedding-model ... --embedding-base-url ... (see asking your library).

Papers already indexed are skipped. The model name is stored with the index: changing it without --reindex is an error, since vectors of two models cannot be compared. Papers with a downloaded PDF are indexed on their full text, split in chunks, when rag.full_text_index is on and pymupdf is installed; the others on title and abstract.

--from selects cached papers by the DOIs of a .bib or .csv file; papers not in the cache are ignored.

--enrich-citations runs after the embedding step, and also runs when rag.citations.enabled is true. Edges are stored only between papers of your cache. When the embedding step fails (no embedding model, server error, no sqlite-vec), the enrichment still runs.

Exit code 1 when the embedding step fails: no embedding model, an unreachable or failing server, or a changed model without --reindex.

See also: tutorial 9, tutorial 10, asking your library, citation graph.

Options

mosaic index [OPTIONS]

Option	Value	Default	Description
--reindex			Re-embed all papers, even already-indexed ones
--query, -q	TEXT		Embed only papers matching this query
--from	PATH		Embed only papers from a .bib or .csv file
--batch-size	INTEGER	96	Texts per embedding API call
--enrich-citations			Fetch citation edges from OpenAlex/CrossRef after embedding and store them for graph-boosted retrieval