Skip to content

Data models

All data models are defined in src/models.py as Pydantic BaseModel subclasses with strict validation. Template definitions live in src/templates.py.

Core models

These models represent the primary data structures that flow through the pipeline.

ExtractionResult

The output of the extraction stage. Contains all tables and context items detected on one or more PDF pages.

Field Type Description
tables list[TableModel] All detected tables (main, auxiliary, other)
context list[TextContextModel \| ImageContextModel] All non-table context items

TableModel

A single table extracted from a document page.

Field Type Description
table_id str Generated identifier (e.g., table_0_0)
role TableRole MAIN, AUXILIARY, or OTHER
page_number int Source page number
headers list[str] Column headers in order
rows list[dict[str, str]] Row data keyed by header name
confidence float Extraction confidence (0.0–1.0)
notes str \| None Extraction irregularities
bbox BoundingBox \| None Normalised bounding box on page
primary_key_column str \| None Header that uniquely identifies rows

TextContextModel

A text-based context item (general note, code requirement, spec).

Field Type Description
context_id str Generated identifier
type ContextType Always TEXT
page_number int Source page number
content str Full verbatim text
category ContextCategory Classification of the text block
category_detail str \| None Additional category information
scope list[str] \| None Row IDs this context applies to

ImageContextModel

An image-based context item (legend diagram, item card, dimension drawing).

Field Type Description
context_id str Generated identifier
type ContextType Always IMAGE
page_number int Source page number
content str File path or placeholder identifier
format str Image format (e.g., png)
dimensions tuple[int, int] Image dimensions
interpretation str \| None Detailed textual description of the image content

EnrichedRow

The final output of the enrichment stage. One instance per main schedule row.

Field Type Description
row_id str Primary key value from the main schedule
data dict[str, str] Column values keyed by schema column name
field_sources dict[str, FieldSource] Source of each populated field
confidence float Minimum confidence across all contributing specialists
reasoning str \| None Concatenated reasoning from all specialists

UserTableSchema

The user-defined output template that controls which columns the pipeline fills.

Field Type Description
template TemplateType Template type (e.g., STANDARD_TAKEOFF)
columns list[str] Ordered list of target column names

A model validator ensures Special Notes is always the last column, regardless of where the user places it in the list.

Core model relationships

The following diagram shows how the core models relate to each other.

classDiagram
    class ExtractionResult {
        tables: list~TableModel~
        context: list~ContextModel~
    }

    class TableModel {
        table_id: str
        role: TableRole
        headers: list~str~
        rows: list~dict~
        primary_key_column: str
    }

    class TextContextModel {
        context_id: str
        type: ContextType
        content: str
        category: ContextCategory
    }

    class ImageContextModel {
        context_id: str
        type: ContextType
        content: str
        interpretation: str
    }

    class EnrichedRow {
        row_id: str
        data: dict~str, str~
        field_sources: dict~str, FieldSource~
        confidence: float
    }

    class UserTableSchema {
        template: TemplateType
        columns: list~str~
    }

    ExtractionResult "1" *-- "many" TableModel
    ExtractionResult "1" *-- "many" TextContextModel
    ExtractionResult "1" *-- "many" ImageContextModel
    ExtractionResult --> EnrichedRow : enriched into
    UserTableSchema --> EnrichedRow : defines columns

Enum types

Pipeline enums

Enum Values Purpose
TableRole MAIN, AUXILIARY, OTHER Classifies table function in the document
ContextType TEXT, IMAGE Distinguishes text and image context items
ContextCategory GENERAL_NOTE, PERFORMANCE_SPEC, MATERIAL_REQUIREMENT, STRUCTURAL_CRITERIA, CODE_REQUIREMENT, OTHER Classifies text context content
FieldSource MAIN_TABLE, AUXILIARY_TABLE, TEXT_CONTEXT, IMAGE_CONTEXT, UNRESOLVED Tracks which source filled each field
StrategyType AUXILIARY_TABLE, TEXT_RULE, IMAGE_LEGEND, DIMENSION_CARD, MULTI_LABEL Identifies specialist enrichment strategies
MatchType EXACT, FUZZY, RULE_BASED, UNMATCHED Classification of match quality (used in legacy resolution)
ModelType FAST, ADVANCED Selects Gemini model tier
TemplateType STANDARD_TAKEOFF, STANDARD_TAKEOFF_TDL, GLASS_SCHEDULE, SHOP_DETAILS Predefined output templates

Domain enums

Enum Example values Purpose
WindowOperabilityType Casement Single, Direct Set / Picture / Fixed, Awning, Sliding Window, Double Hung Constrained operability values for windows
DoorOperabilityType Swing Single, Swing Double, Sliding Door, Folding, Pivot Constrained operability values for doors

Specialists that fill the Operability column must use values from these enums. The constraint string is injected into prompts at runtime via _build_operability_constraint().

Gemini response models

These models define the structured JSON schemas that Gemini returns. Each maps to a specific pipeline step.

Model Used by Returns
GeminiTableResult TABLE_EXTRACTION prompt list[GeminiTableModel] — detected tables
GeminiContextResult CONTEXT_EXTRACTION prompt list[GeminiTextContextModel \| GeminiImageContextModel] — context items
GeminiRoutingResult ROUTER prompt list[StrategyType] + reasoning
GeminiEnrichedRowResult All enrichment prompts list[GeminiEnrichedRow] — enriched rows with field sources
GeminiResolutionResult FUZZY_MATCHING, SEMANTIC_MATCHING list[GeminiResolutionModel] — match results (legacy)
GeminiCompoundResolutionResult COMPOUND_RESOLUTION list[GeminiCompoundResolution] — primary/secondary splits
GeminiRuleApplicationResult RULE_APPLICATION list[GeminiRuleApplication] — rules mapped to rows
GeminiColumnDetectionResult COLUMN_DETECTION list[GeminiColumnMatch] — column links between tables

All Gemini response models inherit from GeminiResponse, which provides confidence (float, 0.0–1.0) and notes (optional string for irregularities).