Helena Bioinformatics Mtdna Curation API

openapi: 3.2.0
info:
  title: Helix Insight - Variant Analysis Service Mtdna Curation API
  description: AI-powered variant analysis and interpretation service
  version: 0.1.0
tags:
- name: mtdna-curation
paths:
  /sessions/{session_id}/variants/{variant_idx}/mtdna-curation:
    patch:
      tags:
      - mtdna-curation
      summary: Update mtDNA curation evidence
      description: 'Update mtDNA curation fields with partial-update semantics.


        Mirrors override pattern (CR-HELENA-MUTABLE-STATE-001):

        - Writes only to PostgreSQL variant_annotations.

        - Read paths apply evaluator overlay to compute effective

        classification.


        Atomic semantics (addendum B3 / Option B): audit emit happens BEFORE

        db.commit. If audit fails, the PostgreSQL transaction is rolled back

        and the client receives HTTP 500. The geneticist retries; no silent

        state corruption.'
      operationId: update_mtdna_curation_sessions__session_id__variants__variant_idx__mtdna_curation_patch
      security:
      - HTTPBearer: []
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Session Id
      - name: variant_idx
        in: path
        required: true
        schema:
          type: integer
          title: Variant Idx
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCurationRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurationResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - mtdna-curation
      summary: Get current mtDNA curation
      description: 'Read current mtDNA curation + evaluator overlay. No audit emission.


        Pipeline acmg_class / acmg_criteria are resolved server-side from the

        session DuckDB raw_variants table (HELIX-CR-2026-MTDNA: replaces the

        earlier "frontend composes" pattern). Failure to read DuckDB returns

        (None, None) and is treated as non-fatal degradation -- curation

        fields and evaluator overlay remain valid response components.'
      operationId: get_mtdna_curation_sessions__session_id__variants__variant_idx__mtdna_curation_get
      security:
      - HTTPBearer: []
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Session Id
      - name: variant_idx
        in: path
        required: true
        schema:
          type: integer
          title: Variant Idx
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurationResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - mtdna-curation
      summary: Clear all mtDNA curation evidence
      description: 'Clear all 13 mt_* curation data fields + 3 attribution fields.


        Soft-clear semantics (mirror clear_acmg_override):

        - Row had only curation: row deleted.

        - Row also has flag/override: NULL the mt_* columns; row retained.


        Audit severity: CRITICAL (destructive operation).'
      operationId: clear_mtdna_curation_sessions__session_id__variants__variant_idx__mtdna_curation_delete
      security:
      - HTTPBearer: []
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Session Id
      - name: variant_idx
        in: path
        required: true
        schema:
          type: integer
          title: Variant Idx
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurationResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sessions/{session_id}/variants/{variant_idx}/mtdna-curation/preview:
    post:
      tags:
      - mtdna-curation
      summary: Preview curation evaluation without saving
      description: 'Pure-function preview. Does NOT write to DB. Does NOT emit audit.


        Used by frontend for live UI feedback as the geneticist fills in the

        curation form. Org boundary still enforced (session must belong to

        user''s org) to prevent reconnaissance.'
      operationId: preview_mtdna_curation_sessions__session_id__variants__variant_idx__mtdna_curation_preview_post
      security:
      - HTTPBearer: []
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Session Id
      - name: variant_idx
        in: path
        required: true
        schema:
          type: integer
          title: Variant Idx
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MtdnaCurationFields'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurationStateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    EffectiveClassificationResponse:
      properties:
        pipeline_acmg_class:
          type: string
          title: Pipeline Acmg Class
          description: Pipeline-original ACMG class from raw_variants
        pipeline_criteria:
          type: string
          title: Pipeline Criteria
          description: Pipeline-original ACMG criteria string
        evaluator_acmg_class:
          anyOf:
          - type: string
          - type: 'null'
          title: Evaluator Acmg Class
          description: Evaluator-derived effective ACMG class. None in c3a (combining rules not extracted). Future B3 Spike CR will populate this field.
        evaluator_criteria:
          type: string
          title: Evaluator Criteria
          description: Pipeline criteria + curated subset (computed via evaluator). Comma-joined.
        cat_m_messages:
          items:
            type: string
          type: array
          title: Cat M Messages
          description: ClinGen MMDWG Category M audit messages (M7a/M7b). M7a fires on PP1 disqualifier; M7b fires when curation contributes any criterion.
      type: object
      required:
      - pipeline_acmg_class
      - pipeline_criteria
      - evaluator_criteria
      title: EffectiveClassificationResponse
      description: 'Pipeline-original vs evaluator-overlay classification.


        Per addendum B2: evaluator_acmg_class is Optional[str] = None in c3a.

        Combining rules (Richards 2015) extraction is deferred to future B3

        Spike CR. Frontend renders ''Real classification updates after

        reclassify'' when evaluator_acmg_class is None.'
    CurationResponse:
      properties:
        session_id:
          type: string
          format: uuid
          title: Session Id
        variant_idx:
          type: integer
          title: Variant Idx
        curation_fields:
          $ref: '#/components/schemas/MtdnaCurationFields'
          description: Current stored curation values (all 13 fields surfaced; None for unpopulated criteria).
        curation_state:
          $ref: '#/components/schemas/CurationStateResponse'
        effective_classification:
          $ref: '#/components/schemas/EffectiveClassificationResponse'
        curated_by:
          anyOf:
          - $ref: '#/components/schemas/UserAttribution'
          - type: 'null'
          description: User who last edited curation. None when no curation has ever been saved on this variant.
        audit_event_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Audit Event Id
          description: Audit event UUID emitted on this write. None for GET responses (no audit emission on read paths).
        validation_warnings:
          items:
            type: string
          type: array
          title: Validation Warnings
          description: 'Non-blocking advisory warnings emitted during save. Curator may proceed regardless; warnings are logged in audit trail. HET-001: PP1 homoplasmy reminder fires when proband heteroplasmy >= 0.95 and homoplasmic_in_all=FALSE. GET, DELETE, and preview endpoints always return an empty list.'
      type: object
      required:
      - session_id
      - variant_idx
      - curation_fields
      - curation_state
      - effective_classification
      title: CurationResponse
      description: 'PATCH/GET response payload.


        PATCH returns audit_event_id (UUID); GET returns audit_event_id=None

        (read operations do not emit audit events).'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    MtdnaCurationFields:
      properties:
        mt_ps2_strength:
          anyOf:
          - type: string
            pattern: ^(VeryStrong|Strong|Moderate|Supporting)$
          - type: 'null'
          title: Mt Ps2 Strength
          description: 'PS2 (de novo) strength: VeryStrong/Strong/Moderate/Supporting'
        mt_ps3_evidence:
          anyOf:
          - type: string
            maxLength: 5000
          - type: 'null'
          title: Mt Ps3 Evidence
          description: PS3 functional studies evidence (cybrid + ETC <20% + load >=60%)
        mt_ps4_proband_count:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Mt Ps4 Proband Count
          description: PS4 unrelated proband count
        mt_ps4_haplogroup_diversity_count:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Mt Ps4 Haplogroup Diversity Count
          description: PS4 distinct top-level haplogroup count among probands
        mt_pm6_strength:
          anyOf:
          - type: string
            pattern: ^(VeryStrong|Strong|Moderate|Supporting)$
          - type: 'null'
          title: Mt Pm6 Strength
          description: PM6 (de novo without maternity confirmation) strength
        mt_pp1_maternal_member_count:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Mt Pp1 Maternal Member Count
          description: PP1 maternal family member count
        mt_pp1_homoplasmic_in_all:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Mt Pp1 Homoplasmic In All
          description: 'PP1 disqualifier: TRUE when variant is homoplasmic in all maternal members (segregation evidence cannot establish pathogenicity per ClinGen mtDNA VCEP v1.0.0; PP1 suppressed and Cat M7a audit fires).'
        mt_pp1_heteroplasmy_correlation:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Mt Pp1 Heteroplasmy Correlation
          description: PP1 heteroplasmy correlates with disease severity
        mt_pp4_etc_deficiency:
          anyOf:
          - type: string
            maxLength: 5000
          - type: 'null'
          title: Mt Pp4 Etc Deficiency
          description: PP4 ETC enzyme deficiency evidence (<20% activity)
        mt_bs2_strength:
          anyOf:
          - type: string
            pattern: ^(Strong|Supporting)$
          - type: 'null'
          title: Mt Bs2 Strength
          description: 'BS2 (heteroplasmy in healthy adult) strength: Strong or Supporting'
        mt_bs3_evidence:
          anyOf:
          - type: string
            maxLength: 5000
          - type: 'null'
          title: Mt Bs3 Evidence
          description: BS3 functional studies evidence (no effect)
        mt_bs4_evidence:
          anyOf:
          - type: string
            maxLength: 5000
          - type: 'null'
          title: Mt Bs4 Evidence
          description: BS4 lack of segregation OR paternal segregation
        mt_bp5_evidence:
          anyOf:
          - type: string
            maxLength: 5000
          - type: 'null'
          title: Mt Bp5 Evidence
          description: BP5 mtDNA variant in nDNA-related disease case
      type: object
      title: MtdnaCurationFields
      description: '13 mtDNA curation data fields.


        All optional -- used both as PATCH body (partial update; only provided

        fields are persisted) and as GET response payload (all fields surfaced

        with current stored values, None for unpopulated criteria).


        Field-level validators encode McCormick 2020 Table 1 strength tiers

        and non-negative count invariants. Server-side defense-in-depth:

        domain entity also re-validates in __post_init__ (single source of

        truth for invariants).'
    UpdateCurationRequest:
      properties:
        curation:
          $ref: '#/components/schemas/MtdnaCurationFields'
          description: Partial update -- only fields explicitly set by client are persisted. Unset fields retain previous values.
        pipeline_acmg_class:
          type: string
          pattern: ^(P|LP|VUS|LB|B)$
          title: Pipeline Acmg Class
          description: Pipeline-original ACMG class read from variants list. Captured for audit before/after comparison.
        pipeline_acmg_criteria:
          type: string
          title: Pipeline Acmg Criteria
          description: Pipeline-original ACMG criteria string. Captured for audit.
      type: object
      required:
      - curation
      - pipeline_acmg_class
      - pipeline_acmg_criteria
      title: UpdateCurationRequest
      description: 'PATCH /sessions/{sid}/variants/{vidx}/mtdna-curation request body.


        Wraps MtdnaCurationFields with pipeline classification capture for

        audit trail. Pipeline values are read by frontend from the variants

        list (DuckDB raw_variants); server records them verbatim in audit

        metadata for reproducibility.'
    UserAttribution:
      properties:
        user_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: User Id
          description: User UUID. May be None for historical records migrated from DuckDB where original user was not tracked.
        user_name:
          type: string
          title: User Name
          description: Display name of the user. For historical records, may be 'system:historical-migration' or 'unknown-historical'.
        timestamp:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Timestamp
          description: When the action occurred. None for historical records without precise timestamp.
      type: object
      required:
      - user_name
      title: UserAttribution
      description: 'Identifies a user who performed an action, with optional timestamp.


        Used in flag/override responses and annotation records. Both user_id

        and user_name are required — user_id for system references, user_name

        for display. timestamp optional because some historical records

        (migrated from DuckDB) lack precise timestamps.'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    CurationStateResponse:
      properties:
        has_curated_flags:
          additionalProperties:
            type: boolean
          type: object
          title: Has Curated Flags
          description: 10 keys (ps2, ps3, ps4, pm6, pp1, pp4, bs2, bs3, bs4, bp5) -> bool. PP1 may be False even when populated if disqualifier (homoplasmic_in_all=TRUE) fires.
        strength_enums:
          additionalProperties:
            anyOf:
            - type: string
            - type: 'null'
          type: object
          title: Strength Enums
          description: 5 keys (ps2, pm6, bs2, ps4, pp1) -> derived strength string or None. ps4/pp1 strengths are inline-derived from counts.
        pp1_disqualified:
          type: boolean
          title: Pp1 Disqualified
          description: TRUE when PP1 evidence populated AND homoplasmic_in_all=TRUE. Triggers Cat M7a audit message.
        curated_contributed:
          type: boolean
          title: Curated Contributed
          description: TRUE when at least one of the 10 has_curated flags is TRUE
        emitted_curated_criteria:
          items:
            type: string
          type: array
          title: Emitted Curated Criteria
          description: 'Ordered list of criterion codes (e.g. ''PS3_Supporting'', ''PP1_Moderate'') emitted by curated evidence. Tier-suffix convention: bare = ACMG default per Richards 2015; explicit suffix = strength differs from default OR McCormick downgrade (PS3, BS3 always _Supporting).'
      type: object
      required:
      - has_curated_flags
      - strength_enums
      - pp1_disqualified
      - curated_contributed
      - emitted_curated_criteria
      title: CurationStateResponse
      description: 'Evaluator output -- what curated criteria fired and why.


        Computed by the pure-function mmdwg_evaluator.evaluate_mmdwg_criteria.

        Fields mirror MmdwgEvaluationResult fields used by the frontend.'
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer