Records

This is an automatically generated API reference of VERA record and result types.

models

Classes:

• ChunkRecord –

  Immutable searchable chunk supplied by the caller.

• AttachmentRecord –

  Opaque binary attachment stored in a .vera archive.

• AttachmentRef –

  Reference from a chunk to a stored attachment.

• Citation –

  Typed citation fields extracted from chunk metadata.

• QueryResult –

  Ranked search hit from :meth:~vera_doc.document.VeraDocument.search.

ChunkRecord dataclass

ChunkRecord(
    id: str,
    text: str,
    metadata: JsonObject = dict(),
    vector: Sequence[float] | None = None,
    attachments: tuple[AttachmentRef, ...] = (),
)

Immutable searchable chunk supplied by the caller.

Attributes:

• id (str) –

  Stable identifier within the archive.

• text (str) –

  Non-empty searchable content.

• metadata (JsonObject) –

  JSON-compatible citation and filter fields.

• vector (Sequence[float] | None) –

  Optional pre-computed embedding. When omitted, the configured embedding function embeds text on write.

• attachments (tuple[AttachmentRef, ...]) –

  Links to stored binary attachments.

Raises:

• ValueError –

  When id or text is empty or vector is invalid.

• TypeError –

  When metadata contains non-JSON values.

Methods:

• __post_init__ –

id instance-attribute

id: str

text instance-attribute

text: str

metadata class-attribute instance-attribute

metadata: JsonObject = field(default_factory=dict)

vector class-attribute instance-attribute

vector: Sequence[float] | None = None

attachments class-attribute instance-attribute

attachments: tuple[AttachmentRef, ...] = ()

__post_init__

__post_init__() -> None

AttachmentRecord dataclass

AttachmentRecord(
    id: str,
    data: bytes,
    media_type: str,
    filename: str | None = None,
    checksum: str | None = None,
    metadata: JsonObject = dict(),
)

Opaque binary attachment stored in a .vera archive.

Attributes:

• id (str) –

  Stable attachment identifier.

• data (bytes) –

  Raw attachment bytes.

• media_type (str) –

  MIME type (for example "application/pdf").

• filename (str | None) –

  Optional original filename.

• checksum (str | None) –

  Optional SHA-256 hex digest. Computed automatically when omitted; validated when supplied.

• metadata (JsonObject) –

  JSON-compatible attachment metadata.

Raises:

• ValueError –

  When checksum does not match data.

Methods:

• __post_init__ –

id instance-attribute

id: str

data instance-attribute

data: bytes

media_type instance-attribute

media_type: str

filename class-attribute instance-attribute

filename: str | None = None

checksum class-attribute instance-attribute

checksum: str | None = None

metadata class-attribute instance-attribute

metadata: JsonObject = field(default_factory=dict)

__post_init__

__post_init__() -> None

AttachmentRef dataclass

AttachmentRef(attachment_id: str, role: str | None = None)

Reference from a chunk to a stored attachment.

Attributes:

• attachment_id (str) –

  ID of the stored attachment.

• role (str | None) –

  Optional semantic role (for example "source" or "figure").

Methods:

• __post_init__ –

attachment_id instance-attribute

attachment_id: str

role class-attribute instance-attribute

role: str | None = None

__post_init__

__post_init__() -> None

Citation dataclass

Citation(
    page_start: int | None = None,
    page_end: int | None = None,
    heading_path: str | None = None,
    source_filename: str | None = None,
    document_id: str | None = None,
)

Typed citation fields extracted from chunk metadata.

Methods:

• from_metadata –

  Build a citation from a chunk metadata mapping.

Attributes:

• page_start (int | None) –
• page_end (int | None) –
• heading_path (str | None) –
• source_filename (str | None) –
• document_id (str | None) –

page_start class-attribute instance-attribute

page_start: int | None = None

page_end class-attribute instance-attribute

page_end: int | None = None

heading_path class-attribute instance-attribute

heading_path: str | None = None

source_filename class-attribute instance-attribute

source_filename: str | None = None

document_id class-attribute instance-attribute

document_id: str | None = None

from_metadata classmethod

from_metadata(metadata: Mapping[str, Any]) -> Citation

Build a citation from a chunk metadata mapping.

QueryResult dataclass

QueryResult(
    record: ChunkRecord,
    score: float,
    semantic_score: float | None = None,
    keyword_score: float | None = None,
    before: tuple[ChunkRecord, ...] = (),
    after: tuple[ChunkRecord, ...] = (),
)

Ranked search hit from :meth:~vera_doc.document.VeraDocument.search.

Attributes:

• record (ChunkRecord) –

  Matching chunk record.

• score (float) –

  Combined relevance score for the selected mode.

• semantic_score (float | None) –

  Raw semantic score, when applicable.

• keyword_score (float | None) –

  Raw keyword score, when applicable.

Methods:

• as_dict –

  Return a JSON-serializable representation of this result.

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]

Return a JSON-serializable representation of this result.

See CorpusSearchResult for multi-document search results.