What is Acquisitions?

Acquisitions is where you search digital libraries (Open Library, Project Gutenberg, Crossref) and bring files into your linked folders so they flow into the Main Library. Save just the bibliographic record for later, or import the full text and let the pipeline process it end-to-end. It has two tabs — Digital Libraries and Local Library.

Connectors

Open Library

Catalog records (metadata only — saved as a reference).

Project Gutenberg

Public-domain ebooks; the full text can be downloaded and imported.

Crossref

Scholarly works by DOI (metadata only — saved as a reference).

Local Library

Use + Add Folder to link a folder, or drop a file into the import zone (PDFs are fully supported). Any compatible file placed in a linked folder is automatically integrated into the Main Library, up to your data allowance. Removing a linked folder leaves files already indexed in the library.

Save Reference vs Import

Save Reference

Shown for metadata-only sources (Open Library, Crossref). Adds just the citation metadata to your library — no file is downloaded. These results are marked Reference only.

Import

Shown for sources that can supply the file (e.g. Project Gutenberg). Downloads the full text, uploads it, and runs it through the processing pipeline ready for retrieval.

What is Resource Management?

Resource Management is where the files you have acquired are checked and prepared for search. It has two tabs — Inventory and Metadata — and a settings gear in the header. A badge on the Metadata tab tells you how many files are waiting for your review.

Inventory tab

A complete list of every file Mira knows about, with per-file actions. From here you can inspect a file, open it in the reader, re-run a processing step, or remove it. Select one or more files and the Index button runs the full pipeline on them. Each row shows a strip of processing pills that fill in left-to-right as the file moves through the pipeline (see below); a file is only searchable once its pills reach Ready.

Processing stages (the pills)

Each pill on a file’s row is one stage of the intake pipeline. They light up in order as the file is processed:

Upload

The file has been received and stored.

Parse · PyMuPDF

Pull the embedded text layer out of the PDF.

OCR

Optical character recognition for scanned or image-only pages (when no usable text layer is found).

GROBID Header · GROBID Fulltext · GROBID Tier

Extract document structure and the title/author block using GROBID.

Cover Page · Body Text · Embedded PDF · Byline · Filename

Successive fallbacks that infer the title and author from the cover page, body text, the PDF’s own metadata, the byline, or finally the filename.

CrossRef DOI · CrossRef Title · OpenAlex · Semantic Scholar · CORE

Look the work up in scholarly catalogues to confirm and complete the citation.

Reconcile

Merge the candidate values (and any metadata you edited by hand) into one citation.

Classify

Decide the document type — article, book, chapter, and so on.

Chunk

Split the text into short (~128-token) passages.

Embed · Vector Store

Turn each passage into a vector and store it in the vector database (ChromaDB).

Index

Finalize and register the file so it can be searched.

Ready

Fully processed — the file is searchable and available to the Atelier.

Metadata tab

A review queue of files whose extracted citation details were not confident enough to accept automatically. Files Mira is sure about are processed for you; the rest land here.

Review & correct

Each item shows the proposed title, author, and other citation fields next to a preview of the original file. Tab between fields to correct them.

Approve & Skip

Approve & Next accepts your corrections and moves on (Enter also works). Skip sets the item aside without saving changes.

Page viewer

The original file is shown beside the form so you can verify details against the source. Use the ← / → buttons to move between review items, the − / + and percentage controls to zoom (click the percentage to reset), and the fullscreen button (or F11) for a larger view. A rotate button appears for files whose preview supports it and turns the page 90° clockwise. When no form field is focused, the keyboard ←/→ arrows also move between review items.

Settings

The gear icon in the header opens the unified settings, on the Models & Keys section.

What is the Library?

The Library is where all of your source material lives. Each collection of documents you upload — for example, the complete works of a single author or a set of journal articles — is stored as an archive. You can have as many archives as you like, organized under one or more libraries. When you search from the Workbench, the search runs against the archives you have selected.

Archives

Creating an archive

Click Add Content in the library header, then either browse a public-domain collection (Internet Archive, Standard Ebooks, Perseus) or upload your own files directly. Uploaded documents are added to the currently visible archive.

Supported formats

Mira ingests PDFs, plain text and Markdown (.txt, .md), DJVU, and scanned pages and images via OCR (JPEG, PNG, TIFF, BMP). There are no other compatible file formats.

Selecting archives for search

Archives with a green Indexed badge are ready to search. From the Main Library, you can check or uncheck which archives are active. Only active, indexed archives are included when you run a search from the Reading Room. The search bar shows exactly which archives are being searched in a strip beneath the mode tabs.

The Processing Pipeline

Each archive card shows a pipeline of four stages. A passage cannot be searched until all four are complete:

1. OCR

If your documents are scanned images or image-based PDFs, optical character recognition extracts the text. Plain text files skip this step automatically.

2. Splitting

The extracted text is divided into short passages. The passage size determines how long each one is. Smaller passages give more precise search results; larger passages preserve more surrounding context.

3. Attribution

Each passage is tagged with its source: the original author, an editor or publisher, or a translator. This allows you to filter search results by attribution later, so you can distinguish, for instance, an author’s own words from a publisher’s footnotes.

4. Embedding

Each passage is converted into a row of numbers (a vector) that captures its meaning, and stored in a matrix using the configured embedding model. This is the step that makes meaning-based search possible. Once embedding is complete, the archive shows an Indexed badge and is ready to search.

Library Settings

Card density

A slider from 1 (most compact) to 5 (most spacious) controlling how much space each archive card takes up on screen. Lower values show more archives at once; higher values give each card more breathing room.

Attribution method

How passages are auto-attributed before researcher review — a rule-based heuristic, a local LLM, or a low-cost API.

Embedding backend

The embedding backend used to convert passages into vectors. For cloud-backed Mira this defaults to OpenRouter (BGE-M3) when an API key is configured, with Together AI as the cloud fallback and FastEmbed (local) as the offline fallback. This powers semantic search and hybrid retrieval. See the Search help guide for technical details.

How your archives are searched

When you upload documents into a library, the workbench breaks each document into short passages and converts them into a matrix — a large table of numbers where each row represents one passage and each column captures one dimension of that passage’s meaning. Your search query is converted into a row of numbers the same way. The search engine then compares your query’s row against every passage row in the matrix to find the closest matches. The passages that match most closely appear first in your results; passages with weaker matches appear further down or not at all.

Each number in the matrix represents how strongly a passage relates to one abstract dimension of meaning. No single number is human-readable on its own, but taken together as a row, the hundreds of numbers form a unique fingerprint for that passage’s content. When two rows have similar numbers in the same columns, the passages are about similar topics — even if they use completely different words.

Retrieval Methods

Keyword (BM25)

What it does: BM25 searches for the exact words you type. It looks through every passage in your archives and asks two questions: does this passage contain my search terms? and how important are those terms? A word like “dialectical” that only appears in a handful of passages is treated as a much stronger signal than a common word like “the.” If your search term appears many times in a short passage, that passage is judged more relevant and appears earlier in your results — closer to the top of the list. A long passage where the same term appears just once, buried among thousands of other words, is judged less relevant and appears further down.

When to use it: Use BM25 when you are looking for specific words, names, or phrases that you know appear in the text. For example, searching for “Feuerbach” or “rate of profit” — where the exact term matters. It is the most predictable method: if the word is in your archives, BM25 will find it. It does not require the matrix of numerical representations described above; it works directly with the words in your documents.

Why it works: BM25 rewards rarity (uncommon words count more), repetition (a word appearing several times signals relevance), and brevity (a focused passage beats a rambling one). These three principles, combined, make it very good at finding exactly what you asked for — but it will miss passages that discuss the same idea using different vocabulary.

Mathematical notation

Best Match 25 — a probabilistic ranking function that scores documents by term frequency, weighted by inverse document frequency and normalized by document length. score(D, Q)  =  ∑_i=1ⁿ  IDF(q_i) ·   f(q_i, D) · (k₁ + 1) ⁄ [ f(q_i, D) + k₁ · (1 − b + b · |D| / avgdl) ]

• Q = the query, composed of terms q₁ … q_n
• D = a document being scored; |D| = its length in tokens
• f(q_i, D) = raw frequency of term q_i in document D
• IDF(q_i) = inverse document frequency — log[(N − n(q_i) + 0.5) / (n(q_i) + 0.5) + 1], where N = total documents, n(q_i) = documents containing q_i. Rare terms receive higher weight.
• k₁ = term-frequency saturation parameter (typically 1.2–2.0). Controls how quickly repeated occurrences of a term stop increasing the score.
• b = length-normalization parameter (typically 0.75). At b=1, full length normalization; at b=0, no length normalization.
• avgdl = average document length across the collection

Under the hood: Vector Indexing (ChromaDB)

What it does: ChromaDB is the vector database used internally by Smart Search and Semantic modes. When you upload documents, every passage is converted into a row of numbers (a vector) and stored in a collection. ChromaDB indexes those rows so that when you search, it can find the passages whose rows are nearest to your query’s row without re-reading every passage from scratch.

Why it matters: Comparing your query against every passage one row at a time gets slow as an archive grows. A vector database keeps the rows in a structure built for nearest-neighbour lookup — like organizing a library by subject so you can go straight to the right shelf instead of walking every aisle. This keeps semantic search fast even as your archives grow.

Mathematical notation

Nearest-neighbour retrieval over a dense vector space. Text passages are encoded into fixed-dimensional vectors and stored in a vector database (ChromaDB), which returns the indexed vectors closest to the query vector under a chosen distance function. NN(q)  =  argmin_{v ∈ V}  d(q, v)

• q = query vector (the embedding of the search query)
• V = the set of all indexed passage vectors in the matrix
• v = an individual passage vector (one row of the matrix)
• d(q, v) = a distance function between vectors, e.g. cosine distance, inner-product (dot product) d = −∑ q_i · v_i, or L2 (Euclidean) distance d = √∑(q_i − v_i)²
• NN(q) = the nearest neighbor — the passage vector closest to the query

Under the hood: Semantic Embeddings

What it does: The configured embedding model (part of the Sentence-BERT family of transformer encoders) reads your archives and decides what each passage means. When you uploaded your documents, the model read each passage and produced the row of numbers (the vector) that represents its meaning in the matrix. It does the same for your search query. It understands meaning because it was trained on enormous amounts of text and learned that, for instance, “workers’ revolt” and “proletarian uprising” refer to the same idea. The search then compares your query’s row of numbers against each passage’s row: passages whose rows closely match yours appear at the top of your results, because close rows mean close meaning.

When it activates: Semantic embeddings power the Smart Search and Semantic modes. When you search for “economic crisis,” the embedding model also surfaces passages about “financial panic,” “commercial collapse,” or “overproduction” from your archives, even if those exact words weren’t in your query.

Why it works: Traditional keyword search treats “dog” and “hound” as completely unrelated because they share no letters. The embedding model learned from billions of sentences that these words appear in similar contexts and mean similar things, so it places them in nearby rows of the matrix. It compares meaning by measuring how closely two rows point in the same direction in the high-dimensional space of the matrix — if two passages discuss the same topic, their rows will point the same way regardless of the specific words each one uses.

Mathematical notation

A modification of the BERT transformer that produces semantically meaningful sentence embeddings using siamese and triplet network structures. Passages and queries are independently encoded, then compared via cosine similarity. sim(q, p)  =  cos(θ)  =  (q · p) ⁄ (||q|| · ||p||)  =  ∑_i=1^d q_i p_i  ⁄  (√∑ q_i²  ·  √∑ p_i²)

• q = query embedding vector, produced by passing the query through the BERT encoder followed by mean pooling
• p = passage embedding vector, produced identically from the indexed passage
• d = embedding dimensionality (typically 384 or 768 depending on model)
• q_i, p_i = the i-th component of each vector
• ||q||, ||p|| = Euclidean norms (magnitudes) of each vector
• cos(θ) = cosine of the angle between vectors. Values range from −1 (opposite meaning) to +1 (identical meaning). By normalizing for magnitude, cosine similarity captures semantic direction only.

Smart Search (Hybrid)

What it does: Smart Search runs two searches over your archives at once — a keyword search (BM25) and a meaning-based matrix search (vector) — then intelligently merges their results into a single list. It works like asking two research assistants with different strengths to each find relevant passages, then combining their recommendations. A passage that both assistants independently flag as important rises to the top of your results; a passage found by only one still appears, but further down the list.

When to use it: This is the best default for most research. Use it when you want to be thorough — when you want to find passages that contain your exact words and passages that discuss the same idea in different language. It protects you from the blind spots of either method used alone: keyword search might miss relevant synonyms, and meaning-based search might miss rare proper names. Smart Search catches both.

Why it works: Each search method has strengths the other lacks. Keyword search is precise and predictable — if a word exists anywhere in your archives, it will find it. Meaning-based search understands synonyms and paraphrasing but can sometimes drift from what you typed. By combining both and promoting passages that appear in both result lists to higher positions, Smart Search gives you the reliability of exact matching together with the breadth of semantic understanding.

Mathematical notation

Combines BM25 keyword scoring with vector similarity using Reciprocal Rank Fusion (RRF) to merge the two ranked lists into a single result set. RRF(d)  =  ∑_{r ∈ R}  1 ⁄ (k + rank_r(d))

• d = a document appearing in one or more result lists
• R = the set of ranking systems (here: BM25 and vector search)
• rank_r(d) = the position of document d in ranking r (1 = top result)
• k = a smoothing constant (typically 60). Prevents top-ranked documents from dominating; higher values give more weight to documents that appear in multiple lists.

Search Settings

Passage Size

Set under Resource Management settings. How many tokens each indexed passage targets, selectable from 256, 512, 1024, or 2048. Smaller passages are more precise and give tighter quote attribution but may lose surrounding context; larger passages preserve context but can dilute relevance.

Advanced Search

Field Selectors

Restrict a search row to a specific field: title, author, or full text. “All Fields” searches across everything.

Boolean Operators

AND requires both conditions. OR matches either. NOT excludes results containing that term.

Attribution Filter

Distinguishes between original author text, editor/publisher annotations, and translator notes. Useful when publisher footnotes appear within an author’s chapters.