Skip to content
RAGLite

Options and types

Option names are the same in both SDKs: Python takes them as dict keys ({"topK": 3}). Python methods also take common options as keyword arguments, such as search(q, top_k=3) and build(rebuild=True).

Document and collection options

Section titled “Document and collection options”

new Document(path, options), Document.fromText(id, text, options) and new DocumentCollection(sources, options) take:

Option Default Meaning
embeddings the existing index’s, else { provider: "local" } { provider, model?, apiKey?, baseURL? }. See Choosing providers
llm none { provider, model?, apiKey?, baseURL?, temperature?, maxTokens? }. Needed by ask()
chunkSize the existing index’s, else 500 Words per chunk; characters for text without spaces (Chinese, Japanese, Thai, …)
overlap the existing index’s, else 50 Overlap between chunks, in the same units
topK 5 Results returned by search() and passages given to ask()
scoreThreshold 0 Minimum cosine similarity (0..1)
retrieval { mode: "vector" } Default mode and hybrid options. See Hybrid search
rerank none Default reranker for search() and ask(). See Reranking
metadata none Your own fields, added to results and usable in filter. See Metadata filters
storeDir ".raglite" Where indexes are saved
vectorStore memory store A provider config or a VectorStore instance. See Vector stores
logLevel "info" "silent", "info" or "debug". Logs go to stderr

build()

Section titled “build()”
Option Python keyword Meaning
rebuild rebuild Re-index even if nothing changed
chunkSize, overlap, embeddings chunk_size, overlap, embeddings Override the constructor options for this build
onProgress on_progress Called after each batch of 64 chunks with { source, embedded, total }
signal cancel AbortSignal (TypeScript) or threading.Event (Python) that stops the build

Document.build() returns { chunkCount, cached, embeddingProvider, embeddingModel, dimensions }. DocumentCollection.build() returns { totalDocuments, totalChunks, cachedDocuments, newDocuments, errors }.

Section titled “search()”
Option Python keyword Meaning
topK top_k Number of results
scoreThreshold score_threshold Minimum cosine similarity
mode mode "vector", "keyword" or "hybrid"
hybrid hybrid { rrfK?, candidates?, weights? }
filter filter Only chunks whose metadata matches. See Metadata filters
rerank rerank { provider, model?, apiKey?, baseURL?, llm?, candidates? }, a function, or false. See Reranking

ask() and askStream()

Section titled “ask() and askStream()”

All search() options, plus:

Option Meaning
llm Overrides the document’s LLM for this call
includeCitations Ask the LLM to cite passages as [n] (default true)
systemHint Extra instructions appended to the system prompt
signal TypeScript only: cancels the LLM request

SearchResult

Section titled “SearchResult”
Field Meaning
id Chunk id
text The chunk text
metadata { source, chunk, totalChunks, page?, pageEnd?, section? }, plus your own metadata fields
score Cosine similarity (vector mode), fused rank score 0..1 (keyword and hybrid), or the reranker’s score
distance 1 - score
scores Keyword and hybrid modes, and with rerank: { vector?, keyword?, fused?, rerank? }

AnswerResult

Section titled “AnswerResult”
Field Meaning
text The answer
citations Citation[], in order of first citation. See Citations
provider, model The LLM that answered
usage { promptTokens?, completionTokens?, totalTokens? }, when the provider reports it
finishReason Why the LLM stopped, when reported

Citation is { n, source, chunk, page?, pageEnd?, section?, text }.

Errors

Section titled “Errors”

Every error extends RagLiteError.

Error Thrown when
ConfigError Invalid options, or a provider package or extra is missing
FileNotIndexedError search() or ask() on a document that was never built
UnsupportedFileTypeError The file type has no loader
LoaderError A file cannot be read or has no text
ChunkingError Invalid chunk settings, such as overlap ≥ chunkSize
EmbeddingError The embedding provider failed
LLMError The LLM provider failed
VectorDBError The vector store failed
BuildCancelledError Python only: a build was cancelled. TypeScript throws the signal’s AbortError

Building blocks

Section titled “Building blocks”

The pieces Document uses are exported for use on their own, for example to embed text for another system or to chunk text the same way RAGLite does.

import { createEmbedder, getLoader, RecursiveChunker } from "raglite-toolkit";


const text = await getLoader("./policy.pdf").load();
const chunks = new RecursiveChunker(500, 50).split(text);


const embedder = await createEmbedder({ provider: "openai" });
const vectors = await embedder.embedDocuments(chunks);
const query = await embedder.embedQuery("refund policy");

Loaders and chunkers cannot be swapped inside a Document. To index text from another format, extract it yourself and use Document.fromText() / Document.from_text().

Exports

Section titled “Exports”
import {
  Document,
  DocumentCollection,
  createMcpServer,
  serveMcp,
  searchTool,
  extractCitations,
  createEmbedder,
  evaluate,
  parseQuestions,
  formatReport,
  matchesFilter,
  DEFAULT_LLM_MODELS,
  DEFAULT_EMBEDDING_MODELS,
  DEFAULT_RERANK_MODELS,
} from "raglite-toolkit";