Helena Bioinformatics Simulation API

openapi: 3.2.0
info:
  title: Helix Insight - Variant Analysis Service Simulation API
  description: AI-powered variant analysis and interpretation service
  version: 0.1.0
tags:
- name: Simulation
paths:
  /api/v1/simulation/run:
    post:
      tags:
      - Simulation
      summary: Start CR simulation
      description: 'Start a CR simulation subprocess.


        Resolves session IDs via session-orchestration, writes them to a temp file,

        launches simulate_cr_template.py as subprocess. One simulation at a time.


        HELENA-PLATFORM-SIM-001'
      operationId: run_simulation_api_v1_simulation_run_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunSimulationRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/simulation/status:
    get:
      tags:
      - Simulation
      summary: Get simulation status
      description: 'Poll current simulation status.


        Status determination (priority order):

        CLAUSE 1: No state -> idle

        CLAUSE 2: Cancelled flag set -> cancelled (terminal)

        CLAUSE 3: Proc finished + success + JSON -> completed

        CLAUSE 4: Proc finished + other -> failed

        CLAUSE 5: Proc running + cancelling flag -> cancelling (transient)

        CLAUSE 6: Proc running -> running


        HELENA-PLATFORM-SIM-001

        CR-2026-SIMVIEW-CANCEL-001: cancelled + cancelling states added.'
      operationId: get_simulation_status_api_v1_simulation_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationStatusResponse'
      security:
      - HTTPBearer: []
  /api/v1/simulation/cancel:
    post:
      tags:
      - Simulation
      summary: Cancel running simulation
      description: 'Initiate cancellation of running simulation.


        Non-blocking: sends SIGTERM and returns immediately with status=''cancelling''.

        Background watcher handles graceful shutdown (up to 30s grace period) and

        falls back to SIGKILL if subprocess does not respond. Status endpoint

        returns ''cancelling'' during grace period, ''cancelled'' after subprocess exits.


        CR-2026-SIMVIEW-CANCEL-001'
      operationId: cancel_simulation_api_v1_simulation_cancel_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationStatusResponse'
      security:
      - HTTPBearer: []
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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
    SimulationStatusResponse:
      properties:
        run_id:
          type: string
          title: Run Id
        status:
          type: string
          title: Status
        cr_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Cr Id
        progress_current:
          type: integer
          title: Progress Current
          default: 0
        progress_total:
          type: integer
          title: Progress Total
          default: 0
        elapsed_seconds:
          type: number
          title: Elapsed Seconds
          default: 0
        result:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Result
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        log_lines:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Log Lines
      type: object
      required:
      - run_id
      - status
      title: SimulationStatusResponse
    RunSimulationRequest:
      properties:
        cr_id:
          type: string
          title: Cr Id
        scope:
          type: string
          title: Scope
        organization_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Organization Id
        user_ids:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: User Ids
      type: object
      required:
      - cr_id
      - scope
      title: RunSimulationRequest
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer