app/models/template.py

"""Pydantic models for the internal template schema.

Stars output is a paired format:
  - Data file: matrix (data variables as rows, samples as columns)
  - Metadata file: sample-level annotations (one row per sample)
  Only Sample_ID and Subject_title are required linking fields.

Qvey output is a single flat CSV:
  - Row 1: q1, q2, q3, ... (question numbers)
  - Row 2: original column headers
  - Row 3+: data rows
"""

from enum import Enum

from pydantic import BaseModel


class ProductType(str, Enum):
    """Supported output products."""

    STARS = "stars"
    QVEY = "qvey"


class TemplateSchema(BaseModel):
    """Template definition for a product's output format."""

    template_name: str
    version: str
    product: ProductType = ProductType.STARS
    # Required linking fields (Stars only)
    sample_id_field: str = ""
    subject_id_field: str = ""
    # Optional: known metadata field names (hints for the AI, not exhaustive)
    common_metadata_fields: list[str] = []