Data Models¶
This page documents the data structures used throughout Cite-Right. All models are Pydantic classes with validation and serialization support.
Input Types¶
SourceDocument¶
Represents a complete source document.
Location: src/cite_right/core/results.py
Fields:
id (str): Unique identifier for the document. Used in citation results to reference the source.
text (str): The complete document text. Citation character offsets refer to positions within this text.
metadata (Mapping[str, Any]): Optional additional information. Preserved through alignment and accessible in results.
Example:
from cite_right import SourceDocument
doc = SourceDocument(
id="annual_report_2024",
text="The full document text goes here...",
metadata={"author": "Finance Team", "date": "2024-03-15"},
)
SourceChunk¶
Represents a pre-chunked excerpt with position information.
Location: src/cite_right/core/results.py
class SourceChunk(BaseModel):
source_id: str
text: str
doc_char_start: int
doc_char_end: int
metadata: Mapping[str, Any] = {}
document_text: str | None = None
source_index: int | None = None
Fields:
source_id (str): Identifier of the parent document this chunk came from.
text (str): The chunk text.
doc_char_start (int): Starting character position in the original document.
doc_char_end (int): Ending character position in the original document.
metadata (Mapping[str, Any]): Optional additional information.
document_text (str | None): Full original document text. If provided, citation offsets are computed against the original document text.
source_index (int | None): Index of this source in the sources list. If None, the position in the sources list is used.
Example:
from cite_right import SourceChunk
chunk = SourceChunk(
source_id="annual_report_2024",
text="Revenue increased by 20% year-over-year.",
doc_char_start=1500,
doc_char_end=1540,
)
When citations are computed against chunks, the doc_char_start is added to citation offsets, producing positions in the original document.
Output Types¶
SpanCitations¶
Contains citation results for a single answer span.
Location: src/cite_right/core/results.py
class SpanCitations(BaseModel):
answer_span: AnswerSpan
citations: list[Citation]
retrieval_support: list[RetrievalSupport] = []
status: Literal["supported", "partial", "unsupported"]
Fields:
answer_span (AnswerSpan): The answer text segment being cited.
citations (list[Citation]): Ranked list of exact localized citations, best match first.
retrieval_support (list[RetrievalSupport]): Retrieval-only support signals for passages selected during lexical and/or embedding candidate search that did not produce an exact localized citation.
status (Literal["supported", "partial", "unsupported"]): Overall support level based on exact citation answer coverage. Retrieval support does not change status.
AnswerSpan¶
Represents a segment of the answer text.
Location: src/cite_right/core/results.py
class AnswerSpan(BaseModel):
text: str
char_start: int
char_end: int
kind: Literal["sentence", "clause", "paragraph"] = "sentence"
paragraph_index: int | None = None
sentence_index: int | None = None
Fields:
text (str): The span text.
char_start (int): Starting position in the original answer.
char_end (int): Ending position in the original answer.
kind (Literal["sentence", "clause", "paragraph"]): The type of segment, determined by the answer segmenter.
paragraph_index (int | None): Paragraph index containing this span.
sentence_index (int | None): Sentence index within the answer.
Citation¶
Contains details about a source match.
Location: src/cite_right/core/results.py
class Citation(BaseModel):
score: float
source_id: str
source_index: int
candidate_index: int
char_start: int
char_end: int
evidence: str
evidence_spans: list[EvidenceSpan] = []
exact_evidence: str
components: Mapping[str, float] = {}
Fields:
score (float): Overall match quality score.
source_id (str): Identifier of the source document.
source_index (int): Index of the source in the original sources list.
candidate_index (int): Internal index of the passage candidate.
char_start (int): Starting character position of the legacy contiguous evidence view in the source.
char_end (int): Ending character position of the legacy contiguous evidence view in the source.
evidence (str): The legacy contiguous evidence text from the source document. In multi-span mode this is the enclosing source slice, so it may include bridge text that was not matched directly.
evidence_spans (list[EvidenceSpan]): Exact matched evidence regions. This is the source of truth for precise offsets and highlighting.
exact_evidence (str): Canonical exact evidence text derived from evidence_spans. Multi-span citations join exact matched spans with " ... " to make omitted bridge text explicit.
components (Mapping[str, float]): Breakdown of score components. Typical keys include alignment_score, normalized_alignment, matches, answer_coverage, evidence_coverage, lexical_score, embedding_score, embedding_only, num_evidence_spans, evidence_chars_total, passage_char_start, and passage_char_end.
Verification:
The legacy contiguous evidence text always equals the rebased source-document slice:
def slice_source_text(source, char_start, char_end):
if source.full_text is not None:
return source.full_text[char_start:char_end]
return source.text[
char_start - source.base_doc_offset : char_end - source.base_doc_offset
]
assert (
slice_source_text(source, citation.char_start, citation.char_end)
== citation.evidence
)
For SourceChunk, citation.char_start and citation.char_end remain absolute offsets in the original document even though source.text may hold only the chunk text.
For precise attribution in multi-span mode, prefer:
RetrievalSupport¶
Represents a retrieval-only support signal without localized evidence spans.
Location: src/cite_right/core/results.py
class RetrievalSupport(BaseModel):
retrieval_score: float
source_id: str
source_index: int
candidate_index: int
passage_char_start: int
passage_char_end: int
passage_text: str
embedding_score: float
lexical_score: float
Fields:
retrieval_score (float): Combined retrieval score used for ranking support passages.
source_id (str): Identifier of the source document.
source_index (int): Index of the source in the original sources list.
candidate_index (int): Internal index of the passage candidate.
passage_char_start (int): Starting character position of the passage in the source.
passage_char_end (int): Ending character position of the passage in the source.
passage_text (str): Passage text from the source document.
embedding_score (float): Embedding similarity score when an embedder is provided.
lexical_score (float): Lexical overlap score from candidate selection.
Retrieval support is returned when a passage is selected during candidate search but does not produce an exact localized citation. Use it for semantic recall and UI hints, not as proof of exact grounding.
EvidenceSpan¶
Represents a single region of evidence text within a multi-span citation.
Location: src/cite_right/core/results.py
Alignment¶
Internal result from the Smith-Waterman alignment operation.
Location: src/cite_right/core/results.py
class Alignment(BaseModel):
score: int
token_start: int
token_end: int
query_start: int = 0
query_end: int = 0
matches: int = 0
match_blocks: list[tuple[int, int]] = []
Fields:
score (int): Raw alignment score.
token_start (int): Start token position in the candidate passage.
token_end (int): End token position in the candidate passage.
query_start (int): Start token position in the query (answer span).
query_end (int): End token position in the query.
matches (int): Number of matching tokens in the alignment.
match_blocks (list[tuple[int, int]]): Non-contiguous match blocks used for multi-span evidence.
Metric Types¶
HallucinationMetrics¶
Aggregate metrics from hallucination analysis.