localvectordb.core module

LocalVectorDB v1.0 Core Components

This module contains the foundational classes and data structures for the new document-first architecture.

localvectordb.core.DocumentScoringMethod

Document scoring methods for aggregating chunk scores into a document score:

“best”: Highest chunk score (single best passage matters)
“average”: Mean of all chunk scores (overall quality)
“frequency_boost”: Boosts the best chunk score by the number of quality chunks (default, good for comprehensive docs) - frequency_bias (0.3): How much to boost based on chunk count

alias of Literal[‘best’, ‘average’, ‘frequency_boost’]

class localvectordb.core.MetadataFieldType(*values)

Bases: str, Enum

TEXT = 'text'

INTEGER = 'integer'

REAL = 'real'

BOOLEAN = 'boolean'

DATE = 'date'

JSON = 'json'

valid_types() → Tuple[Type[Any], ...]

class localvectordb.core.MetadataField(type: MetadataFieldType | str | Type, indexed: bool = False, required: bool = False, default_value: Any = None, embedding_enabled: bool = False, fts_enabled: bool = False)

Bases: object

Defines a metadata field for documents.

Parameters:

type (MetadataFieldType or str or Type) – The type of the metadata field.
indexed (bool, optional) – Whether the field is indexed in the database, by default False.
required (bool, optional) – Whether the field is required, by default False.
default_value (Any, optional) – Default value for the field if not provided, by default None.
embedding_enabled (bool, optional) – Whether this field should have its own embeddings for vector search. Only applicable to TEXT and JSON fields, by default False.
fts_enabled (bool, optional) – Whether this field should have full-text search enabled. Only applicable to TEXT fields, by default False.

type: MetadataFieldType | str | Type

indexed: bool = False

required: bool = False

default_value: Any = None

embedding_enabled: bool = False

fts_enabled: bool = False

__init__(type: MetadataFieldType | str | Type, indexed: bool = False, required: bool = False, default_value: Any = None, embedding_enabled: bool = False, fts_enabled: bool = False) → None

class localvectordb.core.ChunkPosition(start: int, end: int, line: int, column: int, end_line: int, end_column: int)

Bases: object

Exact position tracking for a chunk in the original document.

Parameters:

start (int) – Character start position in the original document.
end (int) – Character end position in the original document.
line (int) – Line number in the original document (1-based).
column (int) – Column number in the original document (1-based).
end_line (int) – Line number of end of chunk in original document (1-based)
end_column (int) – Column number of end of chunk in original document (1-based)

start: int

end: int

line: int

column: int

end_line: int

end_column: int

to_dict() → dict

Convert the ChunkPosition to a dictionary.

Returns:: Dictionary representation with keys ‘start’, ‘end’, ‘line’, ‘column’.
Return type:: dict

Examples

>>> pos = ChunkPosition(start=0, end=10, line=1, column=1, end_line=1, end_column=10)
>>> pos.to_dict()
{'start': 0, 'end': 10, 'line': 1, 'column': 1, 'end_line': 1, 'end_column': 10}

classmethod from_dict(data: dict) → ChunkPosition

Create a ChunkPosition instance from a dictionary.

Parameters:: data (dict) – Dictionary with keys ‘start’, ‘end’, ‘line’, ‘column’.
Returns:: The constructed ChunkPosition object.
Return type:: ChunkPosition

Examples

>>> data = {'start': 0, 'end': 10, 'line': 1, 'column': 1, 'end_line': 1, 'end_column': 10}
>>> ChunkPosition.from_dict(data)
ChunkPosition(start=0, end=10, line=1, column=1, end_line=1, end_column=10)

__init__(start: int, end: int, line: int, column: int, end_line: int, end_column: int) → None

class localvectordb.core.Chunk(content: str, position: ChunkPosition, tokens: int, index: int, faiss_id: int | None = None, content_hash: str | None = None)

Bases: object

Internal representation of a document chunk.

Encapsulates the content, position metadata, token count, and optional FAISS index identifier for a text segment.

Parameters:

content (str) – The text content of the chunk.
position (ChunkPosition) – The location of this chunk in the original document.
tokens (int) – Number of tokens in this chunk.
index (int) – Sequential index of the chunk within the document.
faiss_id (int, optional) – Identifier in the FAISS index, if applicable.

content: str

position: ChunkPosition

tokens: int

index: int

faiss_id: int | None = None

content_hash: str | None = None

calculate_content_hash() → str: Calculate SHA-256 hash of chunk content

content_equals(other: Chunk) → bool: Check if this chunk has the same content as another chunk

get_context(original: str, window: int = 100) → str: Get chunk with surrounding context from original document

highlight_in_original(original: str) → str: Return original text with chunk highlighted

__init__(content: str, position: ChunkPosition, tokens: int, index: int, faiss_id: int | None = None, content_hash: str | None = None) → None

Bases: object

Boundary information for a detected section in a document.

Used during ingestion to track where sections start and end in the original text.

index: int

heading: str | None

heading_level: int | None

start_pos: int

end_pos: int

start_line: int | None = None

end_line: int | None = None

metadata: Dict[str, Any] | None = None

__init__(index: int, heading: str | None, heading_level: int | None, start_pos: int, end_pos: int, start_line: int | None = None, end_line: int | None = None, metadata: Dict[str, Any] | None = None) → None

Bases: object

A section within a document, grouping multiple chunks.

Sections are an overlay on top of existing chunking. They provide a mid-level abstraction between documents and chunks for hierarchical retrieval.

index: int

heading: str | None

heading_level: int | None

start_pos: int

end_pos: int

start_line: int | None = None

end_line: int | None = None

content_hash: str | None = None

metadata: Dict[str, Any] | None = None

faiss_id: int | None = None

chunks: List[Chunk] | None = None

classmethod from_boundary(boundary: SectionBoundary, content_hash: str, faiss_id: int | None = None, chunks: List[Chunk] | None = None) → Section: Create a Section from a SectionBoundary.

__init__(index: int, heading: str | None, heading_level: int | None, start_pos: int, end_pos: int, start_line: int | None = None, end_line: int | None = None, content_hash: str | None = None, metadata: Dict[str, Any] | None = None, faiss_id: int | None = None, chunks: List[Chunk] | None = None) → None

class localvectordb.core.Document(id: str, content: str, metadata: Dict[str, ~typing.Any]=<factory>, created_at: datetime | None = None, updated_at: datetime | None = None, content_hash: str | None = None, chunks: List[Chunk] | None = None, sections: List[Section] | None = None)

Bases: object

A document in the vector database

id: str

content: str

metadata: Dict[str, Any]

created_at: datetime | None = None

updated_at: datetime | None = None

content_hash: str | None = None

chunks: List[Chunk] | None = None

sections: List[Section] | None = None

needs_update(new_content: str) → bool: Check if document content has changed

classmethod from_dict(data: dict) → Document | None: Create a Document from a dictionary response

__init__(id: str, content: str, metadata: Dict[str, ~typing.Any]=<factory>, created_at: datetime | None = None, updated_at: datetime | None = None, content_hash: str | None = None, chunks: List[Chunk] | None = None, sections: List[Section] | None = None) → None

class localvectordb.core.QueryResult(id: str, score: float, type: ~typing.Literal['document', 'chunk', 'section', 'context', 'enriched', 'group', 'aggregation'], content: str, metadata: ~typing.Dict[str, ~typing.Any] = <factory>, document_id: str | None = None, position: ~localvectordb.core.ChunkPosition | None = None)

Bases: object

Result from a search query

id: str

score: float

type: Literal['document', 'chunk', 'section', 'context', 'enriched', 'group', 'aggregation']

content: str

metadata: Dict[str, Any]

document_id: str | None = None

position: ChunkPosition | None = None

get_context(original: str, window: int = 100) → str | None: Get context around chunk (only for chunk results)

classmethod from_dict(data: dict) → QueryResult | None: Create a QueryResult from a dictionary response

__init__(id: str, score: float, type: ~typing.Literal['document', 'chunk', 'section', 'context', 'enriched', 'group', 'aggregation'], content: str, metadata: ~typing.Dict[str, ~typing.Any] = <factory>, document_id: str | None = None, position: ~localvectordb.core.ChunkPosition | None = None) → None

class localvectordb.core.ChunkAlignment(chunk_index_1: int, chunk_index_2: int, similarity: float)

Bases: object

Alignment between a chunk in one document and its best match in another.

Parameters:

chunk_index_1 (int) – Chunk index in the first document.
chunk_index_2 (int) – Best-matching chunk index in the second document.
similarity (float) – Cosine similarity between the two chunks.

chunk_index_1: int

chunk_index_2: int

similarity: float

to_dict() → Dict[str, Any]: Serialize to a JSON-compatible dict.

classmethod from_dict(data: Dict[str, Any]) → ChunkAlignment: Reconstruct from a dict produced by to_dict().

__init__(chunk_index_1: int, chunk_index_2: int, similarity: float) → None

class localvectordb.core.DocumentComparisonResult(doc_id_1: str, doc_id_2: str, overall_similarity: float, chunk_alignments: List[ChunkAlignment], matched_ratio_1: float, matched_ratio_2: float, unmatched_chunks_1: List[int], unmatched_chunks_2: List[int])

Bases: object

Rich comparison result between two documents.

Parameters:

doc_id_1 (str) – ID of the first document.
doc_id_2 (str) – ID of the second document.
overall_similarity (float) – Centroid-level cosine similarity between documents.
chunk_alignments (List[ChunkAlignment]) – Best match per chunk in doc_1, sorted by similarity descending.
matched_ratio_1 (float) – Fraction of doc_1 chunks with a match >= threshold.
matched_ratio_2 (float) – Fraction of doc_2 chunks with a match >= threshold.
unmatched_chunks_1 (List[int]) – Chunk indices in doc_1 with no match >= threshold.
unmatched_chunks_2 (List[int]) – Chunk indices in doc_2 with no match >= threshold.

doc_id_1: str

doc_id_2: str

overall_similarity: float

chunk_alignments: List[ChunkAlignment]

matched_ratio_1: float

matched_ratio_2: float

unmatched_chunks_1: List[int]

unmatched_chunks_2: List[int]

to_dict() → Dict[str, Any]: Serialize to a JSON-compatible dict.

classmethod from_dict(data: Dict[str, Any]) → DocumentComparisonResult: Reconstruct from a dict produced by to_dict().

__init__(doc_id_1: str, doc_id_2: str, overall_similarity: float, chunk_alignments: List[ChunkAlignment], matched_ratio_1: float, matched_ratio_2: float, unmatched_chunks_1: List[int], unmatched_chunks_2: List[int]) → None

class localvectordb.core.DocumentSimilarityMatrix(matrix: ndarray, doc_ids: List[str], embeddings: ndarray)

Bases: object

NxN similarity matrix for a set of documents.

Parameters:

matrix (np.ndarray) – (N, N) array of pairwise similarity scores.
doc_ids (List[str]) – Ordered document IDs matching rows/columns.
embeddings (np.ndarray) – (N, D) document embeddings used to compute the matrix.

matrix: ndarray

doc_ids: List[str]

embeddings: ndarray

to_dict() → Dict[str, Any]: Serialize to a JSON-compatible dict (arrays become nested lists).

classmethod from_dict(data: Dict[str, Any]) → DocumentSimilarityMatrix: Reconstruct from a dict produced by to_dict().

__init__(matrix: ndarray, doc_ids: List[str], embeddings: ndarray) → None

class localvectordb.core.ChunkSimilarityMatrix(matrix: ndarray, doc_id_1: str, doc_id_2: str, chunk_indices_1: List[int], chunk_indices_2: List[int])

Bases: object

Chunk-level pairwise similarity matrix between (or within) documents.

For cross-document comparison, doc_id_1 and doc_id_2 differ. For self-comparison (chord diagrams), they are the same.

Parameters:

matrix (np.ndarray) – (C1, C2) array of pairwise chunk similarity scores.
doc_id_1 (str) – First document ID.
doc_id_2 (str) – Second document ID (same as doc_id_1 for self-comparison).
chunk_indices_1 (List[int]) – Chunk indices for rows.
chunk_indices_2 (List[int]) – Chunk indices for columns.

matrix: ndarray

doc_id_1: str

doc_id_2: str

chunk_indices_1: List[int]

__init__(matrix: ndarray, doc_id_1: str, doc_id_2: str, chunk_indices_1: List[int], chunk_indices_2: List[int]) → None

chunk_indices_2: List[int]