Helena Bioinformatics Graph API

openapi: 3.2.0
info:
  title: Helix Insight - Variant Analysis Service Graph API
  description: AI-powered variant analysis and interpretation service
  version: 0.1.0
tags:
- name: Graph
paths:
  /sessions/{session_id}/graph:
    get:
      tags:
      - Graph
      summary: Pangenome graph view for a locus window
      description: The T3 compact-JSON pangenome graph (nodes, edges, paths, bubbles, meta) for [start, end] on chrom, serialized by_alias so edges emit {from, to}.
      operationId: get_pangenome_graph_view_sessions__session_id__graph_get
      security:
      - HTTPBearer: []
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Session Id
      - name: chrom
        in: query
        required: true
        schema:
          type: string
          description: Chromosome (bare or chr-prefixed)
          title: Chrom
        description: Chromosome (bare or chr-prefixed)
      - name: start
        in: query
        required: true
        schema:
          type: integer
          minimum: 0
          description: Window start (bp)
          title: Start
        description: Window start (bp)
      - name: end
        in: query
        required: true
        schema:
          type: integer
          minimum: 0
          description: Window end (bp)
          title: End
        description: Window end (bp)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PangenomeGraphResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PangenomeMeta:
      properties:
        locus:
          type: string
          title: Locus
        coordinateSystem:
          type: string
          title: Coordinatesystem
          default: grch38-ref-path-ucsc-1based
        inferredPhasing:
          type: boolean
          title: Inferredphasing
          default: true
      type: object
      required:
      - locus
      title: PangenomeMeta
      description: 'The response metadata.


        coordinateSystem defaults to PANGENOME_COORDINATE_SYSTEM (the linear-browser

        basis, declared on the wire so the two views share selection).

        inferredPhasing is the phasing-honesty flag: True when the patient route is

        an INFERRED route (an unphased case threaded as if it had a single route),

        False when the route derives from real phasing (VCF PS tags). Default True

        is the conservative, honest default -- an unset flag must not assert real

        phasing; T6 owns flipping it to False only when phasing is real (CR Section

        2.3, AC-4). coordinateSystem / inferredPhasing are camelCase identifiers

        (no keyword clash, valid Python names), so they need no alias.'
    PangenomePrivateVariant:
      properties:
        position:
          type: integer
          title: Position
        gene:
          anyOf:
          - type: string
          - type: 'null'
          title: Gene
        acmgClass:
          anyOf:
          - type: string
          - type: 'null'
          title: Acmgclass
        evidence:
          anyOf:
          - $ref: '#/components/schemas/PangenomeBubbleEvidence'
          - type: 'null'
      type: object
      required:
      - position
      title: PangenomePrivateVariant
      description: 'A PRIVATE classified variant -- a ghost bubble.


        CR-2026-VA-PANGENOME-PRIVATE-VARIANT-GHOST-BUBBLE-001 (additive, modelled on

        PangenomeBubble + PangenomeBubbleEvidence). A private variant is a patient

        CLASSIFIED variant whose position is NOT an equal-position bubble.position --

        i.e. the HPRC panel carries no snarl for it, so the patient is threaded as a

        ROUTE through existing panel nodes and the variant forms no bubble. The

        serializer (T8) computes the set as the COMPLEMENT: the windowed classified

        SNVs whose position is not in {bubble.position}, from the SAME single windowed

        SNV read + the SAME snv_by_pos index the bubble evidence attach uses (no second

        read, no graph mutation, no schema change). The frontend renders each as an

        ACMG-coloured GHOST BUBBLE in the graph''s own grammar.


        position is the global 1-based UCSC bp -- the SAME shared-selection basis a

        bubble carries (PANGENOME_COORDINATE_SYSTEM), so the ghost selects the same

        site the linear view does. acmgClass + gene are read STRAIGHT from the backend

        classification (the snv''s own BrowserSnvOut.cls / .gene -- NEVER re-derived on

        the client). evidence REUSES the SAME PangenomeBubbleEvidence slot a bubble

        carries (the shared BrowserSnvOut), so the ghost opens the IDENTICAL evidence

        panel a bubble opens (one evidence model, no second graph-specific shape).'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    BrowserExonPextOut:
      properties:
        chrom:
          type: string
          title: Chrom
        gene:
          type: string
          title: Gene
        exonStart:
          type: integer
          title: Exonstart
        exonEnd:
          type: integer
          title: Exonend
        maxTissuePext:
          type: number
          title: Maxtissuepext
        meanPext:
          type: number
          title: Meanpext
        brainCortexPext:
          anyOf:
          - type: number
          - type: 'null'
          title: Braincortexpext
        wholeBloodPext:
          anyOf:
          - type: number
          - type: 'null'
          title: Wholebloodpext
        tier:
          type: string
          title: Tier
      type: object
      required:
      - chrom
      - gene
      - exonStart
      - exonEnd
      - maxTissuePext
      - meanPext
      - tier
      title: BrowserExonPextOut
      description: 'A per-exon pext marker (frontend BrowserExonPext).


        CR-2026-BROWSER-EVIDENCE-TRACKS-001-P2 (Wave 1, Phase 2): a NEW pext-lane

        source read from the read-only reference_db table exon_pext (gnomAD v4.1 /

        GTEx v10 per-exon expression proportion). Wire names are camelCase (the

        existing svType / iscaId convention). The per-field types follow EXON_PEXT_

        DDL (registry/exon_pext.py): chromosome / gene_symbol VARCHAR -> str;

        exon_start / exon_end BIGINT -> int; max_tissue_pext / mean_pext FLOAT NOT

        NULL -> float; brain_cortex_pext / whole_blood_pext FLOAT nullable ->

        Optional[float]. tier is DERIVED server-side from maxTissuePext via

        _pext_tier using the classifier''s exact PVS1 cut (acmg_classifier.py

        L5155-5160): one of ''full'' | ''downgrade'' | ''block'' (CR Section 2.3).'
    BrowserSnvOut:
      properties:
        chrom:
          type: string
          title: Chrom
        pos:
          type: integer
          title: Pos
        gene:
          anyOf:
          - type: string
          - type: 'null'
          title: Gene
        cls:
          anyOf:
          - type: string
          - type: 'null'
          title: Cls
        hgvs:
          anyOf:
          - type: string
          - type: 'null'
          title: Hgvs
        ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Ref
        alt:
          anyOf:
          - type: string
          - type: 'null'
          title: Alt
        bayesdelNoaf:
          anyOf:
          - type: number
          - type: 'null'
          title: Bayesdelnoaf
        bayesdelNoafPred:
          anyOf:
          - type: string
          - type: 'null'
          title: Bayesdelnoafpred
        spliceaiMax:
          anyOf:
          - type: number
          - type: 'null'
          title: Spliceaimax
        spliceaiPred:
          anyOf:
          - type: string
          - type: 'null'
          title: Spliceaipred
        phylop:
          anyOf:
          - type: number
          - type: 'null'
          title: Phylop
        gerp:
          anyOf:
          - type: number
          - type: 'null'
          title: Gerp
        alphamissense:
          anyOf:
          - type: number
          - type: 'null'
          title: Alphamissense
        sift:
          anyOf:
          - type: number
          - type: 'null'
          title: Sift
        metasvm:
          anyOf:
          - type: number
          - type: 'null'
          title: Metasvm
        dann:
          anyOf:
          - type: number
          - type: 'null'
          title: Dann
        mpc:
          anyOf:
          - type: number
          - type: 'null'
          title: Mpc
        af:
          anyOf:
          - type: number
          - type: 'null'
          title: Af
        afGrpmax:
          anyOf:
          - type: number
          - type: 'null'
          title: Afgrpmax
        popmax:
          anyOf:
          - type: string
          - type: 'null'
          title: Popmax
        hom:
          anyOf:
          - type: integer
          - type: 'null'
          title: Hom
        loeuf:
          anyOf:
          - type: number
          - type: 'null'
          title: Loeuf
        misZ:
          anyOf:
          - type: number
          - type: 'null'
          title: Misz
        pli:
          anyOf:
          - type: number
          - type: 'null'
          title: Pli
        clinvarSig:
          anyOf:
          - type: string
          - type: 'null'
          title: Clinvarsig
        reviewStars:
          anyOf:
          - type: integer
          - type: 'null'
          title: Reviewstars
        clinvarId:
          anyOf:
          - type: string
          - type: 'null'
          title: Clinvarid
        criteria:
          anyOf:
          - type: string
          - type: 'null'
          title: Criteria
        confidence:
          anyOf:
          - type: number
          - type: 'null'
          title: Confidence
        consequence:
          anyOf:
          - type: string
          - type: 'null'
          title: Consequence
        impact:
          anyOf:
          - type: string
          - type: 'null'
          title: Impact
        hgvsCdna:
          anyOf:
          - type: string
          - type: 'null'
          title: Hgvscdna
        transcriptId:
          anyOf:
          - type: string
          - type: 'null'
          title: Transcriptid
        transcriptRepresentations:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Transcriptrepresentations
        exonNumber:
          anyOf:
          - type: string
          - type: 'null'
          title: Exonnumber
        domains:
          anyOf:
          - type: string
          - type: 'null'
          title: Domains
        pm1Source:
          anyOf:
          - type: string
          - type: 'null'
          title: Pm1Source
        vcepApplied:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Vcepapplied
        vcepPanel:
          anyOf:
          - type: string
          - type: 'null'
          title: Vceppanel
        deNovo:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Denovo
        hiScore:
          anyOf:
          - type: integer
          - type: 'null'
          title: Hiscore
        tsScore:
          anyOf:
          - type: integer
          - type: 'null'
          title: Tsscore
      type: object
      required:
      - chrom
      - pos
      title: BrowserSnvOut
      description: 'A small variant marker (frontend BrowserSnv).


        CR-2026-BROWSER-EVIDENCE-TRACKS-001-P1 (Wave 1, Phase 1): the five

        established fields (chrom, pos, gene, cls, hgvs) are UNCHANGED. Below them

        35 ADDITIVE per-variant evidence fields are appended, ALL Optional with a

        None default (a pure additive contract widening -- an old frontend ignores

        the unknown keys, a new frontend can be built against the widened contract).

        Each field is read from the per-session `variants` table; a session whose

        table lacks a source column degrades to None via _evidence_columns_present

        (the schema-drift guard), so every field is genuinely optional.


        Wire names are camelCase (matching the existing svType / iscaId convention).

        The wire-name -> `variants` source-column mapping is CR Section 3a; the

        per-field types follow the source column types in variant_schema.py

        (re-verified 2026-06-20, Eunomia B1). CRITICAL (Eunomia B1): exonNumber and

        popmax are Optional[str] -- exon_number is VARCHAR(20) carrying the VEP

        "X/Y" form (e.g. "3/12"), popmax is VARCHAR(10) carrying a population LABEL,

        NOT a number; typing either as int would raise a Pydantic ValidationError

        -> 500 on a real coding-gene window, which the frontend degrade-clean

        handler masks as a silently-empty browser.'
    PangenomePath:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        route:
          items:
            type: string
          type: array
          title: Route
        bold:
          type: boolean
          title: Bold
          default: false
      type: object
      required:
      - id
      - name
      - route
      title: PangenomePath
      description: 'A haplotype route (GFA v1.1 walk / W-line).


        route is the ordered node-id array (the walk); name follows the PanSN

        convention the T1 asset records (sample#haplotype#contig, e.g.

        GRCh38#0#chr18). bold marks the patient''s threaded route (True); the

        reference backbone is False (default).'
    PangenomeBubble:
      properties:
        id:
          type: string
          title: Id
        position:
          type: integer
          title: Position
        alleles:
          items:
            type: string
          type: array
          title: Alleles
        evidence:
          anyOf:
          - $ref: '#/components/schemas/PangenomeBubbleEvidence'
          - type: 'null'
      type: object
      required:
      - id
      - position
      - alleles
      title: PangenomeBubble
      description: 'A variant site (a snarl / bubble).


        position is the reference-path position of the site in the SAME coordinate

        basis the linear browser uses (PANGENOME_COORDINATE_SYSTEM). evidence is

        Optional/None-defaulted: a bubble with no overlapping classifier evidence

        carries None, exactly as the linear view''s per-field None-degrade does. T8

        owns POPULATING evidence; T3 owns its SHAPE.'
    PangenomeBubbleEvidence:
      properties:
        snv:
          anyOf:
          - $ref: '#/components/schemas/BrowserSnvOut'
          - type: 'null'
        pext:
          anyOf:
          - $ref: '#/components/schemas/BrowserExonPextOut'
          - type: 'null'
      type: object
      title: PangenomeBubbleEvidence
      description: 'The bubble evidence SLOT -- the clinical-critical reuse of the shared

        linear-view evidence shape.


        It REUSES the SAME models the linear browser serves (BrowserSnvOut: the

        five established fields + 35 additive evidence fields; BrowserExonPextOut:

        the per-exon pext lane incl. the server-derived tier), imported from

        infrastructure.browser_evidence. There is NO second, graph-specific

        evidence shape: a bubble carries the SAME evidence the linear view serves

        so a clinician sees identical evidence in both views and the graph view

        never recomputes a verdict (CR Section 2.5). The serializer (T8) POPULATES

        this slot from the same classifier evidence the linear view reads (CR I3);

        T3 owns only the SHAPE.'
    PangenomeGraphResponse:
      properties:
        nodes:
          items:
            $ref: '#/components/schemas/PangenomeNode'
          type: array
          title: Nodes
        edges:
          items:
            $ref: '#/components/schemas/PangenomeEdge'
          type: array
          title: Edges
        paths:
          items:
            $ref: '#/components/schemas/PangenomePath'
          type: array
          title: Paths
        bubbles:
          items:
            $ref: '#/components/schemas/PangenomeBubble'
          type: array
          title: Bubbles
        privateVariants:
          items:
            $ref: '#/components/schemas/PangenomePrivateVariant'
          type: array
          title: Privatevariants
          default: []
        meta:
          $ref: '#/components/schemas/PangenomeMeta'
      type: object
      required:
      - nodes
      - edges
      - paths
      - bubbles
      - meta
      title: PangenomeGraphResponse
      description: 'The top-level compact-JSON pangenome graph response.


        The single wire contract assembled by the serializer (T8) and served by the

        endpoint (T9) as a response_model. The pipeline tasks (T4-T7) produce the

        nodes / edges / paths / bubbles; T8 attaches each bubble''s evidence and

        sets meta; T9 serves it with by_alias=True so the edge from/to and the

        camelCase fields reach the wire (CR Section 5 I1).'
    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
    PangenomeEdge:
      properties:
        from:
          type: string
          title: From
        to:
          type: string
          title: To
      type: object
      required:
      - from
      - to
      title: PangenomeEdge
      description: 'A graph edge (GFA v1.1 link / L-line): a directed node-id pair.


        The wire field names are `from` / `to`. `from` is a Python reserved

        keyword and cannot be a field name, so the Python fields are from_node /

        to_node carrying Field(alias=...) -- the SERIALIZED wire JSON is

        {"from": ..., "to": ...}. populate_by_name=True lets the serializer (T8)

        construct by Python name (from_node=...) while the endpoint (T9) serializes

        by alias (by_alias=True; CR Section 5 I1). Orientation is a server-side

        layout concern; the wire carries only the from/to node-id pair the frontend

        draws.'
    PangenomeNode:
      properties:
        id:
          type: string
          title: Id
        x:
          type: number
          title: X
        y:
          type: number
          title: Y
        label:
          type: string
          title: Label
        kind:
          type: string
          title: Kind
        length:
          type: integer
          title: Length
        bubbleId:
          anyOf:
          - type: string
          - type: 'null'
          title: Bubbleid
      type: object
      required:
      - id
      - x
      - y
      - label
      - kind
      - length
      title: PangenomeNode
      description: 'A graph node (GFA v1.1 segment / S-line).


        id is the segment name; length is the segment sequence length (GFA LN);

        label is a short display string (the node sequence or a truncation the

        serializer T8 decides); x / y are the server-computed layout coordinates

        (T7); kind is the node role for rendering, declared as str so the contract

        does not over-constrain a value set the pipeline (T8) owns (CR I4).


        bubbleId (CR-2026-VA-PANGENOME-VISUAL-LANGUAGE-001, T2): the id of the

        SNARL/bubble this node BELONGS to (its owning bubble''s id), surfaced by the

        serializer DIRECTLY from at_by_bubble_id (the producer membership truth) so

        the frontend resolves node -> bubble -> evidence.snv.cls as an O(1) EXACT

        lookup for the ACMG node colour -- NOT a client re-derivation from a lossy

        coordinate. ADDITIVE and backward-compatible: None for a node with no

        surfaced membership (a reference-backbone node, or an unanchored node) --

        an absent membership is None, never a wrong id. The membership COMPUTATION

        is unchanged (threading at_by_bubble_id); T2 only SURFACES it onto the node.'
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer