temdb-models 2.0.0__tar.gz

temdb_models-2.0.0/.gitignore

@@ -0,0 +1,155 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/

temdb_models-2.0.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: temdb-models
+Version: 2.0.0
+Summary: Shared Pydantic models for TEMdb
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0

temdb_models-2.0.0/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "temdb-models"
+version = "2.0.0"
+description = "Shared Pydantic models for TEMdb"
+requires-python = ">=3.10"
+dependencies = [
+    "pydantic>=2.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/temdb"]

temdb_models-2.0.0/src/temdb/models/__init__.py

@@ -0,0 +1,153 @@
+from temdb.models.acquisition import (
+    AcquisitionBase,
+    AcquisitionCreate,
+    AcquisitionFullMetadata,
+    AcquisitionParams,
+    AcquisitionResponse,
+    AcquisitionUpdate,
+    Calibration,
+    HardwareParams,
+    LensCorrectionModel,
+    StorageLocation,
+    StorageLocationCreate,
+)
+from temdb.models.block import (
+    BlockBase,
+    BlockCreate,
+    BlockResponse,
+    BlockUpdate,
+)
+from temdb.models.cutting_session import (
+    CuttingSessionBase,
+    CuttingSessionCreate,
+    CuttingSessionResponse,
+    CuttingSessionUpdate,
+)
+from temdb.models.enums import (
+    AcquisitionStatus,
+    AcquisitionTaskStatus,
+    SectionQuality,
+)
+from temdb.models.error import APIErrorResponse
+from temdb.models.quality_control import (
+    AcquisitionFocusScoresResponse,
+    BadFocusTileInfo,
+    BadFocusTilesResponse,
+    TileFocusScore,
+)
+from temdb.models.roi import (
+    ROIBase,
+    ROIChildrenResponse,
+    ROICreate,
+    ROIResponse,
+    ROIUpdate,
+)
+from temdb.models.section import (
+    SectionBase,
+    SectionCreate,
+    SectioningRunParameters,
+    SectionMetrics,
+    SectionResponse,
+    SectionUpdate,
+)
+from temdb.models.specimen import (
+    SpecimenBase,
+    SpecimenCreate,
+    SpecimenResponse,
+    SpecimenUpdate,
+)
+from temdb.models.substrate import (
+    Aperture,
+    ReferencePoints,
+    SubstrateBase,
+    SubstrateCreate,
+    SubstrateMetadata,
+    SubstrateResponse,
+    SubstrateUpdate,
+)
+from temdb.models.task import (
+    AcquisitionTaskBase,
+    AcquisitionTaskCreate,
+    AcquisitionTaskResponse,
+    AcquisitionTaskUpdate,
+)
+from temdb.models.tile import (
+    Matcher,
+    TileBase,
+    TileCreate,
+    TileResponse,
+    TileUpdate,
+)
+
+__all__ = [
+    # Enums
+    "AcquisitionStatus",
+    "AcquisitionTaskStatus",
+    "SectionQuality",
+    # Tile
+    "Matcher",
+    "TileBase",
+    "TileCreate",
+    "TileUpdate",
+    "TileResponse",
+    # Acquisition
+    "AcquisitionBase",
+    "AcquisitionCreate",
+    "AcquisitionUpdate",
+    "AcquisitionResponse",
+    "AcquisitionFullMetadata",
+    "HardwareParams",
+    "AcquisitionParams",
+    "Calibration",
+    "LensCorrectionModel",
+    "StorageLocation",
+    "StorageLocationCreate",
+    # Specimen
+    "SpecimenBase",
+    "SpecimenCreate",
+    "SpecimenUpdate",
+    "SpecimenResponse",
+    # Block
+    "BlockBase",
+    "BlockCreate",
+    "BlockUpdate",
+    "BlockResponse",
+    # ROI
+    "ROIBase",
+    "ROICreate",
+    "ROIUpdate",
+    "ROIResponse",
+    "ROIChildrenResponse",
+    # Section
+    "SectionBase",
+    "SectionCreate",
+    "SectionUpdate",
+    "SectionResponse",
+    "SectionMetrics",
+    "SectioningRunParameters",
+    # Substrate
+    "SubstrateBase",
+    "SubstrateCreate",
+    "SubstrateUpdate",
+    "SubstrateResponse",
+    "ReferencePoints",
+    "Aperture",
+    "SubstrateMetadata",
+    # Task
+    "AcquisitionTaskBase",
+    "AcquisitionTaskCreate",
+    "AcquisitionTaskUpdate",
+    "AcquisitionTaskResponse",
+    # CuttingSession
+    "CuttingSessionBase",
+    "CuttingSessionCreate",
+    "CuttingSessionUpdate",
+    "CuttingSessionResponse",
+    # Error
+    "APIErrorResponse",
+    # Quality Control
+    "TileFocusScore",
+    "AcquisitionFocusScoresResponse",
+    "BadFocusTileInfo",
+    "BadFocusTilesResponse",
+]

temdb_models-2.0.0/src/temdb/models/acquisition.py

@@ -0,0 +1,134 @@
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+from temdb.models.enums import AcquisitionStatus
+
+
+class LensCorrectionModel(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    id: int = Field(..., description="ID of lens correction model")
+    type: str = Field(
+        ...,
+        description="Transform type as defined in Render Transform Spec",
+    )
+    class_name: str = Field(
+        ...,
+        description="Class name of lens correction model from mpicbg-compatible className",
+    )
+    data_string: str = Field(
+        ...,
+        description="Data string of lens correction model from mpicbg-compatible dataString",
+    )
+
+
+class Calibration(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    pixel_size: float = Field(..., description="Pixel size in nm")
+    rotation_angle: float = Field(..., description="Rotation angle in degrees")
+    lens_model: LensCorrectionModel | None = Field(None, description="Lens correction model")
+    aperture_centroid: list[float] | None = Field(None, description="Aperture centroid in stage coordinates in nm")
+
+
+class HardwareParams(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    scope_id: str = Field(..., description="ID of microscope")
+    camera_model: str = Field(..., description="Model of camera")
+    camera_serial: str = Field(..., description="Serial number of camera")
+    camera_bit_depth: int = Field(..., description="Native bit depth of camera")
+    media_type: str = Field(..., description="Type of substrate in microscope")
+
+
+class AcquisitionParams(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    magnification: int = Field(..., description="Magnification of acquisition")
+    spot_size: int = Field(..., description="Spot size of acquisition")
+    exposure_time: int = Field(..., description="Exposure time of camera in ms")
+    tile_size: list[int] = Field(..., description="Shape of the image tile in pixels")
+    tile_overlap: float = Field(..., description="Pixel overlap to neighboring tiles")
+    saved_bit_depth: int = Field(..., description="Bit depth of saved image")
+
+
+class StorageLocation(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    location_type: str = Field(..., description="Type of storage location, e.g. local, s3, etc.")
+    base_path: str = Field(..., description="Base path of storage location")
+    is_current: bool = Field(..., description="Whether this is the current storage location")
+    date_added: datetime = Field(..., description="Date storage location was added")
+    metadata: dict[str, Any] = Field(..., description="Metadata of storage location")
+
+
+class StorageLocationCreate(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    location_type: str = Field(..., description="Type of storage location, e.g. local, s3, etc.")
+    base_path: str = Field(..., description="Base path of storage location")
+    metadata: dict[str, Any] = Field(default_factory=dict, description="Metadata of storage location")
+
+
+class AcquisitionBase(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    hardware_settings: HardwareParams | None = None
+    acquisition_settings: AcquisitionParams | None = None
+    calibration_info: Calibration | None = None
+    status: AcquisitionStatus | None = None
+    tilt_angle: float | None = Field(None, description="Tilt angle of acquisition in degrees")
+    lens_correction: bool | None = Field(None, description="Whether this acquisition is a lens correction calibration")
+    end_time: datetime | None = Field(None, description="End time of acquisition")
+    storage_locations: list[StorageLocation] | None = Field(None, description="Storage locations of acquisition")
+    montage_set_name: str | None = Field(None, description="Name of montage set")
+    sub_region: dict[str, int] | None = Field(None, description="Sub region of acquisition")
+    replaces_acquisition_id: int | None = Field(None, description="ID of acquisition this acquisition replaces")
+
+
+class AcquisitionCreate(AcquisitionBase):
+    acquisition_id: str = Field(..., description="Unique acquisition identifier")
+    montage_id: str = Field(..., description="Montage identifier")
+    roi_id: str = Field(..., description="ROI identifier")
+    acquisition_task_id: str = Field(..., description="Parent task identifier")
+    hardware_settings: HardwareParams = Field(..., description="Hardware settings of acquisition")
+    acquisition_settings: AcquisitionParams = Field(..., description="Acquisition settings of acquisition")
+    tilt_angle: float = Field(..., description="Tilt angle of acquisition in degrees")
+    lens_correction: bool = Field(..., description="Whether this acquisition is a lens correction calibration")
+    status: AcquisitionStatus = Field(default=AcquisitionStatus.IMAGING, description="Status of acquisition")
+    start_time: datetime | None = Field(None, description="Start time of acquisition (defaults to now if not provided)")
+
+
+class AcquisitionUpdate(AcquisitionBase):
+    calibration_info: dict[str, Any] | None = Field(None, description="Calibration information of acquisition")
+
+
+class AcquisitionResponse(AcquisitionBase):
+    acquisition_id: str = Field(..., description="Unique acquisition identifier")
+    montage_id: str = Field(..., description="Montage identifier")
+    specimen_id: str = Field(..., description="Specimen identifier")
+    roi_id: str = Field(..., description="ROI identifier")
+    acquisition_task_id: str = Field(..., description="Parent task identifier")
+    hardware_settings: HardwareParams = Field(..., description="Hardware settings of acquisition")
+    acquisition_settings: AcquisitionParams = Field(..., description="Acquisition settings of acquisition")
+    status: AcquisitionStatus = Field(..., description="Status of acquisition")
+    start_time: datetime = Field(..., description="Start time of acquisition")
+
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+
+class AcquisitionFullMetadata(BaseModel):
+    """Acquisition with complete hierarchy metadata."""
+
+    model_config = ConfigDict(extra="allow")
+
+    acquisition: AcquisitionResponse
+    task: dict[str, Any] | None = None
+    roi: dict[str, Any] | None = None
+    section: dict[str, Any] | None = None
+    cutting_session: dict[str, Any] | None = None
+    block: dict[str, Any] | None = None
+    specimen: dict[str, Any] | None = None
+    substrate: dict[str, Any] | None = None

temdb_models-2.0.0/src/temdb/models/block.py

@@ -0,0 +1,27 @@
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class BlockBase(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    microCT_info: dict[str, Any] | None = Field(None, description="MicroCT information of block")
+
+
+class BlockCreate(BlockBase):
+    block_id: str = Field(..., description="Unique block identifier")
+    specimen_id: str = Field(..., description="Parent specimen ID")
+
+
+class BlockUpdate(BlockBase):
+    pass
+
+
+class BlockResponse(BlockBase):
+    block_id: str = Field(..., description="Unique block identifier")
+    specimen_id: str = Field(..., description="Parent specimen ID")
+
+    created_at: datetime | None = None
+    updated_at: datetime | None = None

temdb_models-2.0.0/src/temdb/models/cutting_session.py

@@ -0,0 +1,47 @@
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class CuttingSessionBase(BaseModel):
+    """Base cutting session fields."""
+
+    model_config = ConfigDict(extra="allow")
+
+    start_time: datetime | None = Field(None, description="Time when cutting session started")
+    end_time: datetime | None = Field(None, description="Time when cutting session ended")
+    operator: str | None = Field(None, description="Operator of cutting session")
+    sectioning_device: str | None = Field(None, description="Microtome/Device used for sectioning")
+    media_type: str | None = Field(None, description="Type of substrate the sections are placed upon")
+    knife_id: str | None = Field(None, description="Identifier for the knife used")
+
+
+class CuttingSessionCreate(CuttingSessionBase):
+    """Schema for creating a cutting session."""
+
+    cutting_session_id: str = Field(..., description="Unique cutting session identifier")
+    block_id: str = Field(..., description="ID of block cutting session is associated with")
+    start_time: datetime = Field(..., description="Time when cutting session started")
+    sectioning_device: str = Field(..., description="Device used for sectioning")
+    media_type: str = Field(..., description="Type of substrate the sections are placed upon")
+
+
+class CuttingSessionUpdate(CuttingSessionBase):
+    """Schema for updating a cutting session."""
+
+    block_id: str | None = Field(None, description="ID of block")
+    specimen_id: str | None = Field(None, description="ID of specimen")
+
+
+class CuttingSessionResponse(CuttingSessionBase):
+    """Schema for cutting session API responses."""
+
+    cutting_session_id: str = Field(..., description="Unique cutting session identifier")
+    specimen_id: str = Field(..., description="ID of specimen")
+    block_id: str = Field(..., description="ID of block")
+    start_time: datetime = Field(..., description="Time when cutting session started")
+    sectioning_device: str = Field(..., description="Device used for sectioning")
+    media_type: str = Field(..., description="Type of substrate the sections are placed upon")
+
+    created_at: datetime | None = None
+    updated_at: datetime | None = None

temdb_models-2.0.0/src/temdb/models/enums.py

@@ -0,0 +1,27 @@
+from enum import Enum
+
+
+class SectionQuality(str, Enum):
+    GOOD = "good"
+    BROKEN = "broken"
+    THIN = "thin"
+    THICK = "thick"
+    EMPTY = "empty"
+
+
+class AcquisitionTaskStatus(str, Enum):
+    PLANNED = "Planned"
+    IN_PROGRESS = "In Progress"
+    COMPLETED = "Completed"
+    FAILED = "Failed"
+    ABORTED = "Aborted"
+
+
+class AcquisitionStatus(str, Enum):
+    IMAGING = "imaging"
+    ACQUIRED = "acquired"
+    ABORTED = "aborted"
+    QC_FAILED = "failed"
+    QC_PASSED = "qc-passed"
+    QC_PENDING = "qc-pending"
+    TO_BE_REIMAGED = "to be re-imaged"

temdb_models-2.0.0/src/temdb/models/error.py

@@ -0,0 +1,16 @@
+"""API error response models."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class APIErrorResponse(BaseModel):
+    """Standard structure for API error responses."""
+
+    detail: str = Field(..., description="Human-readable description of the error.")
+    error_code: str | None = Field(None, description="Optional machine-readable error code.")
+    context: dict[str, Any] | None = Field(
+        None,
+        description="Optional additional context about the error.",
+    )

temdb_models-2.0.0/src/temdb/models/quality_control.py

@@ -0,0 +1,43 @@
+from pydantic import BaseModel, Field
+
+
+class TileFocusScore(BaseModel):
+    """Represents focus score data for a single tile."""
+
+    tile_id: str = Field(..., description="Unique ID of the tile.")
+    raster_index: int = Field(..., description="Sequential index of the tile within the acquisition raster.")
+    focus_score: float = Field(..., description="Calculated focus score for the tile.")
+
+
+class AcquisitionFocusScoresResponse(BaseModel):
+    """Response model containing focus scores for an acquisition."""
+
+    acquisition_id: str = Field(..., description="ID of the acquisition analyzed.")
+    tile_count: int = Field(..., description="Total number of tiles found for this acquisition.")
+    focus_scores: list[TileFocusScore] = Field(..., description="List of focus scores for each tile.")
+    mean_focus: float | None = Field(None, description="Mean focus score across all tiles.")
+    median_focus: float | None = Field(None, description="Median focus score across all tiles.")
+    stddev_focus: float | None = Field(None, description="Standard deviation of focus scores across all tiles.")
+    min_focus: float | None = Field(None, description="Minimum focus score found.")
+    max_focus: float | None = Field(None, description="Maximum focus score found.")
+
+
+class BadFocusTileInfo(BaseModel):
+    """Information about a tile with bad focus."""
+
+    tile_id: str
+    acquisition_id: str
+    raster_index: int
+    focus_score: float
+    image_path: str
+    stage_position: dict[str, float]
+    roi_id: str | None = None
+    specimen_id: str | None = None
+
+
+class BadFocusTilesResponse(BaseModel):
+    """Response model for bad focus tiles query."""
+
+    threshold: float
+    count: int
+    tiles: list[BadFocusTileInfo]

temdb_models-2.0.0/src/temdb/models/roi.py

@@ -0,0 +1,88 @@
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class ROIBase(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    aperture_width_height: list[float] | None = Field(
+        None,
+        description="Width and height of aperture in mm calculated from aperture_image",
+    )
+    aperture_centroid: list[float] | None = Field(
+        None,
+        description="Center of aperture measured in pixel coordinates from aperture_image",
+    )
+    aperture_bounding_box: list[float] | None = Field(
+        None,
+        description="Bounding box of aperture measured in pixel coordinates",
+    )
+    aperture_image: str | None = Field(None, description="URL of aperture image")
+    optical_pixel_size: float | None = Field(None, description="Optical resolution in nm per pixel")
+    scale_y: float | None = Field(None, description="Scaling factor for y-axis")
+    barcode: int | str | None = Field(None, description="Barcode of ROI if present")
+    rois: list[Any] | None = Field(None, description="List of ROIs")
+    bucket: str | None = Field(None, description="Bucket of ROI")
+    roi_mask: str | None = Field(None, description="URL of ROI mask")
+    roi_mask_bucket: str | None = Field(None, description="Bucket of ROI mask")
+    corners: dict[str, Any] | None = Field(None, description="Corners of ROI")
+    corners_perpendicular: dict[str, Any] | None = Field(None, description="Perpendicular corners of ROI")
+    rule: str | None = Field(None, description="Rule for ROI corner detection")
+    edits: list[Any] | None = Field(None, description="List of edits to ROI")
+    auto_roi: bool | None = Field(None, description="Flag if auto generated ROI was used")
+    roi_parameters: dict[str, Any] | None = Field(None, description="Parameters of ROI")
+    vertices: list[Any] | None = Field(None, description="Vertices of the ROI polygon")
+
+
+class ROICreate(ROIBase):
+    roi_number: int = Field(..., description="Sequential number for this ROI within its parent context")
+    section_id: str = Field(..., description="ID of section")
+    specimen_id: str = Field(..., description="ID of specimen")
+    block_id: str = Field(..., description="ID of block")
+    substrate_media_id: str = Field(..., description="Media ID of the substrate this section is placed on")
+    section_number: int | None = Field(None, description="Number of section from collection")
+    parent_roi_id: str | None = Field(
+        None,
+        description="Hierarchical ID of parent ROI (e.g., 'SPEC001.BLK001.SEC001.SUB001.ROI001')",
+    )
+
+    @field_validator("parent_roi_id", mode="after")
+    @classmethod
+    def validate_parent_roi_id(cls, v: str | None) -> str | None:
+        if v is not None:
+            if ".ROI" not in v:
+                raise ValueError(
+                    "parent_roi_id must contain .ROI and follow format: SPEC###.BLK###.SEC###.SUB###.ROI###[.ROI###...]"
+                )
+            parts = v.split(".")
+            if len(parts) < 5:
+                raise ValueError("parent_roi_id must follow format: SPEC###.BLK###.SEC###.SUB###.ROI###[.ROI###...]")
+            if not parts[-1].startswith("ROI"):
+                raise ValueError("parent_roi_id must end with a ROI segment (e.g., ROI001)")
+        return v
+
+
+class ROIUpdate(ROIBase):
+    pass
+
+
+class ROIResponse(ROIBase):
+    roi_id: str = Field(..., description="Hierarchical ID of ROI")
+    roi_number: int = Field(..., description="Sequential number for this ROI within its parent context")
+    section_id: str = Field(..., description="ID of section")
+    specimen_id: str = Field(..., description="ID of specimen")
+    block_id: str = Field(..., description="ID of block")
+    substrate_media_id: str = Field(..., description="Media ID of the substrate")
+    hierarchy_level: int = Field(..., description="Depth level in ROI hierarchy (1=top-level, 2=child, etc.)")
+    is_parent: bool = Field(default=False, description="Whether this ROI has child ROIs")
+
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+
+class ROIChildrenResponse(BaseModel):
+    """Response model for ROI children query."""
+
+    children: list[ROIResponse]

temdb_models-2.0.0/src/temdb/models/section.py

@@ -0,0 +1,98 @@
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+from temdb.models.enums import SectionQuality
+
+
+class SectioningRunParameters(BaseModel):
+    """Parameters from a sectioning run."""
+
+    model_config = ConfigDict(extra="allow")
+
+    cutting_speed_mms: float | None = Field(None, description="Cutting speed in mm/s")
+    retract_speed_mms: float | None = Field(None, description="Retract speed in mm/s")
+    water_level_mm: float | None = Field(None, description="Water level in boat in mm")
+    wafer_set_level: float | None = Field(None, description="Wafer set level value")
+    tape_speed: float | None = Field(None, description="Main tape speed value")
+    new_tape_speed: float | None = Field(None, description="Temporary tape speed during timePhi")
+    tape_cycle: float | None = Field(None, description="Tape cycle duration/value")
+    cut_cycle: float | None = Field(None, description="Cut cycle duration/value")
+    phiset: float | None = Field(None, description="Phi set value")
+    phi_offset: float | None = Field(None, description="Actual phi value during picking")
+    time_phi: float | None = Field(None, description="Time associated with phi movement")
+    water_added: bool | None = Field(None, description="Flag indicating if water was added during this cycle")
+    other_metadata: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Dictionary for any other arbitrary run parameters",
+    )
+
+
+class SectionMetrics(BaseModel):
+    """Metrics and parameters of a section."""
+
+    model_config = ConfigDict(extra="allow")
+
+    quality: SectionQuality | None = Field(None, description="Qualitative state of the section (e.g., Good, Broken)")
+    thickness_um: float | None = Field(None, description="Measured section thickness in micrometers")
+    knife_quality: str | None = Field(None, description="Assessment of the knife condition at the time of cutting")
+    tissue_confidence_score: float | None = Field(
+        None, description="Confidence score for tissue detection on substrate"
+    )
+    run_parameters: SectioningRunParameters | None = Field(
+        None, description="Detailed parameters from the sectioning run"
+    )
+
+
+class SectionBase(BaseModel):
+    """Base section fields."""
+
+    model_config = ConfigDict(extra="allow")
+
+    section_number: int | None = Field(None, gt=0, description="Sequential section number within the cutting session")
+    timestamp: datetime | None = Field(None, description="Timestamp of section creation/cutting")
+    optical_image: dict[str, Any] | None = Field(
+        None,
+        description="Metadata about optical image collected before imaging",
+    )
+    aperture_uid: str | None = Field(
+        None,
+        description="UID of the specific aperture holding this section",
+    )
+    aperture_index: int | None = Field(
+        None,
+        description="Index of the specific aperture holding this section",
+    )
+    barcode: str | None = Field(None, description="Barcode scanned for this section, if any")
+    section_metrics: SectionMetrics | None = Field(None, description="Metrics and parameters of the section")
+
+
+class SectionCreate(SectionBase):
+    """Schema for creating a section."""
+
+    cutting_session_id: str = Field(..., description="ID of the cutting session this section belongs to")
+    media_id: str = Field(
+        ...,
+        description="ID of the substrate (wafer, tape, etc.) this section is placed on",
+    )
+    section_number: int = Field(..., gt=0, description="Sequential section number")
+
+
+class SectionUpdate(SectionBase):
+    """Schema for updating a section."""
+
+    pass
+
+
+class SectionResponse(SectionBase):
+    """Schema for section API responses."""
+
+    section_id: str = Field(..., description="Unique, system-generated ID for the section")
+    section_number: int = Field(..., gt=0, description="Sequential section number within the cutting session")
+    cutting_session_id: str = Field(..., description="ID of the cutting session")
+    block_id: str = Field(..., description="ID of the block")
+    specimen_id: str = Field(..., description="ID of the specimen")
+    media_id: str = Field(..., description="ID of the substrate")
+
+    created_at: datetime | None = None
+    updated_at: datetime | None = None

temdb_models-2.0.0/src/temdb/models/specimen.py

@@ -0,0 +1,30 @@
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class SpecimenBase(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    description: str | None = Field(None, description="Description of specimen, used for additional notes.")
+    specimen_images: set[str] | None = Field(None, description="Images of specimen")
+    functional_imaging_metadata: dict[str, Any] | None = Field(
+        None,
+        description="Functional imaging metadata of specimen, optional links to other datasets",
+    )
+
+
+class SpecimenCreate(SpecimenBase):
+    specimen_id: str = Field(..., description="Unique specimen identifier")
+
+
+class SpecimenUpdate(SpecimenBase):
+    pass
+
+
+class SpecimenResponse(SpecimenBase):
+    specimen_id: str = Field(..., description="Unique specimen identifier")
+
+    created_at: datetime | None = None
+    updated_at: datetime | None = None

temdb_models-2.0.0/src/temdb/models/substrate.py

@@ -0,0 +1,115 @@
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ReferencePoints(BaseModel):
+    """Reference points for substrate calibration."""
+
+    model_config = ConfigDict(extra="allow")
+
+    origin: tuple[float, float, float] | None = Field(None, description="Origin point (x, y, z)")
+    end: tuple[float, float, float] | None = Field(None, description="End point (x, y, z)")
+    ref: tuple[float, float, float] | None = Field(None, description="Reference point (x, y, z)")
+
+
+class Aperture(BaseModel):
+    """Represents a single aperture or slot on a substrate."""
+
+    model_config = ConfigDict(extra="allow")
+
+    uid: str = Field(
+        ...,
+        description="Unique identifier for this aperture within the substrate",
+    )
+    index: int = Field(..., description="Sequential index of the aperture")
+    centroid: tuple[float, float, float] | None = Field(
+        None, description="Calculated centroid of the aperture (X, Y, Z)"
+    )
+    shape: str | None = Field(
+        None,
+        description="Raw description of the aperture shape",
+    )
+    shape_type: str | None = None
+    shape_params: dict[str, Any] | None = None
+    status: str | None = Field(None, description="Status of the aperture (e.g., available, used, damaged)")
+    tracking_uid: str | None = Field(
+        None,
+        alias="tuid",
+        description="Tracking UID from source if available",
+    )
+
+
+class SubstrateMetadata(BaseModel):
+    """General metadata about a substrate."""
+
+    model_config = ConfigDict(extra="allow")
+
+    name: str | None = Field(None, description="User-defined name for the substrate")
+    user: str | None = Field(None, description="User associated with substrate creation/calibration")
+    created: datetime | None = Field(None, description="Timestamp from source metadata 'created'")
+    calibrated: datetime | None = Field(None, description="Timestamp from source metadata 'calibrated'")
+    extra: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Dictionary for any other key-value metadata items",
+    )
+
+
+class SubstrateBase(BaseModel):
+    """Base substrate fields."""
+
+    model_config = ConfigDict(extra="allow")
+
+    uid: str | None = Field(
+        None,
+        description="Overall unique identifier for the substrate instance",
+    )
+    status: str | None = Field(
+        None,
+        description="Status of the entire substrate (e.g., new, in_use, full, retired)",
+    )
+    refpoint: ReferencePoints | None = Field(None, description="Reference points in local substrate coordinates")
+    refpoint_world: ReferencePoints | None = Field(
+        None, description="Reference points mapped to world/stage coordinates"
+    )
+    source_path: str | None = Field(
+        None,
+        description="Path or identifier of the source file defining this substrate",
+    )
+    metadata: SubstrateMetadata | None = Field(None, description="General metadata about the substrate")
+    apertures: list[Aperture] | None = Field(
+        None,
+        description="List of apertures or slots defined on this substrate",
+    )
+
+
+class SubstrateCreate(SubstrateBase):
+    """Schema for creating a substrate."""
+
+    media_id: str = Field(
+        ...,
+        description="Primary unique identifier for this substrate (e.g., wafer ID, tape reel ID)",
+    )
+    media_type: str = Field(..., description="Type of substrate (e.g., 'wafer', 'tape', 'stick', 'grid')")
+    status: str | None = Field(
+        "new",
+        description="Status of the entire substrate",
+    )
+
+
+class SubstrateUpdate(SubstrateBase):
+    """Schema for updating a substrate."""
+
+    media_id: str | None = Field(None, description="Primary unique identifier")
+    media_type: str | None = Field(None, description="Type of substrate")
+
+
+class SubstrateResponse(SubstrateBase):
+    """Schema for substrate API responses."""
+
+    media_id: str = Field(..., description="Primary unique identifier")
+    media_type: str = Field(..., description="Type of substrate")
+
+    created_at: datetime | None = None
+    updated_at: datetime | None = None

temdb_models-2.0.0/src/temdb/models/task.py

@@ -0,0 +1,55 @@
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+from temdb.models.enums import AcquisitionTaskStatus
+
+
+class AcquisitionTaskBase(BaseModel):
+    """Base acquisition task fields."""
+
+    model_config = ConfigDict(extra="allow")
+
+    task_type: str | None = Field(None, description="Type of acquisition task")
+    version: int | None = Field(None, description="Version number of this task")
+    status: AcquisitionTaskStatus | None = Field(None, description="Status of acquisition task")
+    error_message: str | None = Field(None, description="Error message if failed")
+    started_at: datetime | None = Field(None, description="When task execution began")
+    completed_at: datetime | None = Field(None, description="When task finished (success or failure)")
+    tags: list[str] | None = Field(None, description="Tags for filtering")
+    metadata: dict[str, Any] | None = Field(None, description="Additional metadata")
+
+
+class AcquisitionTaskCreate(AcquisitionTaskBase):
+    """Schema for creating an acquisition task."""
+
+    task_id: str = Field(..., description="Unique identifier for this task")
+    specimen_id: str = Field(..., description="ID of specimen")
+    block_id: str = Field(..., description="ID of block")
+    roi_id: str = Field(..., description="ID of region of interest to be acquired")
+    task_type: str = Field(default="standard_acquisition", description="Type of acquisition task")
+    version: int = Field(default=1, description="Version number of this task")
+    status: AcquisitionTaskStatus = Field(default=AcquisitionTaskStatus.PLANNED)
+    tags: list[str] = Field(default_factory=list, description="Tags for filtering")
+    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
+
+
+class AcquisitionTaskUpdate(AcquisitionTaskBase):
+    """Schema for updating an acquisition task."""
+
+    pass
+
+
+class AcquisitionTaskResponse(AcquisitionTaskBase):
+    """Schema for acquisition task API responses."""
+
+    task_id: str = Field(..., description="Unique identifier for this task")
+    specimen_id: str = Field(..., description="ID of specimen")
+    block_id: str = Field(..., description="ID of block")
+    roi_id: str = Field(..., description="ID of region of interest")
+    task_type: str = Field(..., description="Type of acquisition task")
+    version: int = Field(..., description="Version number of this task")
+    status: AcquisitionTaskStatus = Field(..., description="Status of acquisition task")
+
+    created_at: datetime | None = None
+    updated_at: datetime | None = None

temdb_models-2.0.0/src/temdb/models/tile.py

@@ -0,0 +1,77 @@
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Matcher(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    row: int = Field(..., description="Row index of the tile")
+    col: int = Field(..., description="Column index of the tile")
+    dX: float = Field(..., description="X offset of the tile")
+    dY: float = Field(..., description="Y offset of the tile")
+    dXsd: float = Field(..., description="X offset standard deviation of the tile")
+    dYsd: float = Field(..., description="Y offset standard deviation of the tile")
+    distance: float = Field(..., description="Distance between the tiles")
+    rotation: float = Field(..., description="Rotation of the tile")
+    match_quality: float = Field(..., description="Quality of the match")
+    position: int = Field(..., description="Position of the match")
+    pX: list[float] = Field(..., description="X position of the points in the template tile")
+    pY: list[float] = Field(..., description="Y position of the points in the template tile")
+    qX: list[float] = Field(..., description="X position of the points in the reference tile")
+    qY: list[float] = Field(..., description="Y position of the points in the reference tile")
+
+
+class TileBase(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    stage_position: dict[str, float] | None = Field(
+        None, description="Stage position of the tile in stage coordinates in nm"
+    )
+    raster_position: dict[str, int] | None = Field(None, description="Row, column raster position of the tile")
+    focus_score: float | None = Field(None, description="Focus score of the tile")
+    min_value: float | None = Field(None, description="Minimum pixel value of the tile")
+    max_value: float | None = Field(None, description="Maximum pixel value of the tile")
+    mean_value: float | None = Field(None, description="Mean pixel value of the tile")
+    std_value: float | None = Field(None, description="Standard deviation of pixel values of the tile")
+    image_path: str | None = Field(None, description="URL to the image of the tile")
+    matcher: list[Matcher] | None = Field(None, description="List of matchers for the tile")
+    supertile_id: str | None = Field(None, description="ID of the supertile the tile belongs to")
+    supertile_raster_position: dict[str, int] | None = Field(
+        None, description="Row, column raster position of the supertile"
+    )
+
+
+class TileCreate(TileBase):
+    tile_id: str = Field(..., description="Unique tile identifier")
+    raster_index: int = Field(..., description="Index of the tile in the raster")
+    stage_position: dict[str, float] = Field(..., description="Stage position of the tile in stage coordinates in nm")
+    raster_position: dict[str, int] = Field(..., description="Row, column raster position of the tile")
+    focus_score: float = Field(..., description="Focus score of the tile")
+    min_value: float = Field(..., description="Minimum pixel value of the tile")
+    max_value: float = Field(..., description="Maximum pixel value of the tile")
+    mean_value: float = Field(..., description="Mean pixel value of the tile")
+    std_value: float = Field(..., description="Standard deviation of pixel values of the tile")
+    image_path: str = Field(..., description="URL to the image of the tile")
+
+
+class TileUpdate(TileBase):
+    pass
+
+
+class TileResponse(TileBase):
+    tile_id: str = Field(..., description="Unique tile identifier")
+    acquisition_id: str = Field(..., description="Parent acquisition ID")
+    raster_index: int = Field(..., description="Index of the tile in the raster")
+    stage_position: dict[str, float] = Field(..., description="Stage position of the tile in stage coordinates in nm")
+    raster_position: dict[str, int] = Field(..., description="Row, column raster position of the tile")
+    focus_score: float = Field(..., description="Focus score of the tile")
+    min_value: float = Field(..., description="Minimum pixel value of the tile")
+    max_value: float = Field(..., description="Maximum pixel value of the tile")
+    mean_value: float = Field(..., description="Mean pixel value of the tile")
+    std_value: float = Field(..., description="Standard deviation of pixel values of the tile")
+    image_path: str = Field(..., description="URL to the image of the tile")
+
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+    version: int | None = Field(None, description="Document version number")