Skip to content

Corpus

This is an automatically generated API reference for searching a folder of .vera files as one collection.

corpus

Corpus search: query a folder of .vera files as a single collection.

Classes:

  • VeraCorpus –

    A folder of .vera files searchable as one corpus.

  • CorpusSearchResult –

    A search result attributed to the .vera file it came from.

VeraCorpus 

VeraCorpus(directory: str, paths: list[str], *, recursive: bool = False, excludes: tuple[str, ...] = (), max_open_documents: int = 16, collection_index: VeraCollectionIndex | None = None, index_status: dict[str, Any] | None = None, invalid_files: list[dict[str, str]] | None = None)

A folder of .vera files searchable as one corpus.

Documents needed for citations and figures are opened lazily with a bounded LRU cache. File fan-out search uses parallel short-lived connections; a fresh local collection index is preferred automatically. Each file's query embedding uses that file's recorded embedding model, so a corpus may mix models.

Ranking: semantic results are merged by raw cosine score (comparable across files that share a model). Keyword and hybrid scores are only normalized within a file. Keyword and hybrid candidates use their within-file score with reciprocal rank as a tiebreaker; each result keeps its original score.

Methods:

  • open –

    Open a directory of .vera files for corpus search.

  • from_paths –

    Build a corpus from an explicit list of .vera file paths.

  • document –

    Return the (cached) open VeraDocument for a file in this corpus.

  • close –
  • __enter__ –
  • __exit__ –
  • inspect –

    Summarize the corpus: file count, total pages/chunks, models used.

  • inspect_summary –

    Open a library quickly without validating every archive.

  • search –

    Search every file in the corpus and return the fused top_k results.

Attributes:

directory instance-attribute 

directory = directory

paths instance-attribute 

paths = paths

recursive instance-attribute 

recursive = recursive

excludes instance-attribute 

excludes = excludes

max_open_documents instance-attribute 

max_open_documents = max(1, max_open_documents)

index_status instance-attribute 

index_status = index_status or {'exists': False, 'fresh': False, 'reasons': ['index is missing']}

invalid_files instance-attribute 

invalid_files = invalid_files or []

skipped_semantic_model_groups instance-attribute 

skipped_semantic_model_groups: list[dict[str, Any]] = []

uses_index property 

uses_index: bool

Whether searches are currently served by the local collection index.

open classmethod 

open(directory: str, *, recursive: bool | None = None, excludes: list[str] | tuple[str, ...] | None = None, max_open_documents: int = 16, use_index: bool = True, default_recursive: bool = False, allow_empty: bool = False) -> 'VeraCorpus'

Open a directory of .vera files for corpus search.

Parameters:

  • directory (str) –

    Root directory containing .vera archives.

  • recursive (bool | None, default: None ) –

    When True, include nested directories. When None, use persisted index settings when an index exists.

  • excludes (list[str] | tuple[str, ...] | None, default: None ) –

    Glob patterns to skip.

  • max_open_documents (int, default: 16 ) –

    LRU cache size for opened documents.

  • use_index (bool, default: True ) –

    When True, use a fresh local index when available.

  • default_recursive (bool, default: False ) –

    Default recursion when no index exists.

  • allow_empty (bool, default: False ) –

    When True, allow opening a directory with no valid archives.

Returns:

  • 'VeraCorpus' –

    A corpus handle ready for :meth:search.

Raises:

  • NotADirectoryError –

    When directory is not a directory.

  • FileNotFoundError –

    When no valid archives are found and allow_empty is false.

from_paths classmethod 

from_paths(paths: list[str]) -> 'VeraCorpus'

Build a corpus from an explicit list of .vera file paths.

document 

document(file: str) -> VeraDocument

Return the (cached) open VeraDocument for a file in this corpus.

close 

close() -> None

__enter__ 

__enter__() -> 'VeraCorpus'

__exit__ 

__exit__(*exc) -> None

inspect 

inspect() -> dict[str, Any]

Summarize the corpus: file count, total pages/chunks, models used.

inspect_summary 

inspect_summary() -> dict[str, Any]

Open a library quickly without validating every archive.

A fresh collection index supplies persisted metrics from its last validated build. Missing or stale indexes return discovery counts only; callers can run inspect explicitly when they need a deep scan.

search 

search(text: str, *, mode: str = 'hybrid', top_k: int = 10, context_chunks: int = 0) -> list[CorpusSearchResult]

Search every file in the corpus and return the fused top_k results.

CorpusSearchResult dataclass 

CorpusSearchResult(record: ChunkRecord, score: float, semantic_score: float | None = None, keyword_score: float | None = None, before: tuple[ChunkRecord, ...] = (), after: tuple[ChunkRecord, ...] = (), file: str = '')

Bases: QueryResult

A search result attributed to the .vera file it came from.

Methods:

Attributes:

file class-attribute instance-attribute 

file: str = ''

record instance-attribute 

record: ChunkRecord

score instance-attribute 

score: float

semantic_score class-attribute instance-attribute 

semantic_score: float | None = None

keyword_score class-attribute instance-attribute 

keyword_score: float | None = None

before class-attribute instance-attribute 

before: tuple[ChunkRecord, ...] = ()

after class-attribute instance-attribute 

after: tuple[ChunkRecord, ...] = ()

chunk_id property 

chunk_id: str

text property 

text: str

page_start property 

page_start: int | None

page_end property 

page_end: int | None

heading_path property 

heading_path: str | None

source_filename property 

source_filename: str | None

document_id property 

document_id: str | None

before_chunks property 

before_chunks: list[dict[str, Any]]

after_chunks property 

after_chunks: list[dict[str, Any]]

as_dict 

as_dict() -> dict[str, Any]

For large libraries, pair with a persistent library index.