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, ...] = (),
    includes: 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). Mixed-model semantic lists and hybrid semantic+keyword lists use :func:~vera_doc.ranking.reciprocal_rank_fusion so a library searched with or without a local index returns the same chunk order for a fixed hybrid query. Keyword-only scores are only comparable within a file; those candidates keep their original score with reciprocal rank as a tiebreaker.

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__ –
  • index_search_report –

    Index status for the most recent search, including fallback reasons.

  • inspect –

    Summarize the corpus and optionally report per-archive progress.

  • 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

includes instance-attribute 

includes = includes

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 the most recent search used the local collection index.

Before the first search, this is whether an index is attached.

open classmethod 

open(
    directory: str,
    *,
    recursive: bool | None = None,
    excludes: list[str] | tuple[str, ...] | None = None,
    includes: 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.

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

    Glob patterns that a relative path must match when provided. Omitted includes keep every discovered file.

  • 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.

Selected files do not need a shared parent. Desktop multi-select can include paths on different Windows drives, where os.path.commonpath raises ValueError; the corpus root then falls back to the first file's parent. Result file attributes remain the original 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

index_search_report 

index_search_report() -> dict[str, Any]

Index status for the most recent search, including fallback reasons.

inspect 

inspect(
    *,
    progress: Callable[[dict[str, Any]], None]
    | None = None,
) -> dict[str, Any]

Summarize the corpus and optionally report per-archive progress.

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,
    where: Mapping[str, Any] | None = None,
) -> list[CorpusSearchResult]

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

where is applied before top_k. Caller tags stamped on chunks match every path. Convert-owned archive headers match indexed search; single-file and fallback search evaluate chunk metadata.

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

citation property 

citation: Citation

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.