Helena Bioinformatics Preprocessing API

openapi: 3.2.0
info:
  title: Helix Insight - Variant Analysis Service Preprocessing API
  description: AI-powered variant analysis and interpretation service
  version: 0.1.0
tags:
- name: preprocessing
paths:
  /preprocessing/databases:
    get:
      tags:
      - preprocessing
      summary: Get All Databases Status
      description: 'Get complete status of all reference databases.


        Returns identity, source files, parquet conversion, reference_db loading,

        freshness assessment, and validation results for each database.


        Fast endpoint (< 2 seconds): filesystem stat() calls + one DuckDB query.'
      operationId: get_all_databases_status_preprocessing_databases_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllDatabasesStatusResponse'
  /preprocessing/databases/{db_name}:
    get:
      tags:
      - preprocessing
      summary: Get Single Database Status
      description: 'Get detailed status of a single database.


        Includes everything from the list endpoint plus:

        - Per-chromosome row counts (for partitioned databases)

        - Column names in the DuckDB table

        - Sample data (first 5 rows)

        - Full conversion metadata JSON'
      operationId: get_single_database_status_preprocessing_databases__db_name__get
      parameters:
      - name: db_name
        in: path
        required: true
        schema:
          type: string
          title: Db Name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatabaseDetailResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /preprocessing/databases/{db_name}/update:
    post:
      tags:
      - preprocessing
      summary: Update Single Database
      description: 'Start the update pipeline for a single database.


        Returns immediately with task_id. Poll GET /preprocessing/tasks/{task_id}

        for progress.'
      operationId: update_single_database_preprocessing_databases__db_name__update_post
      parameters:
      - name: db_name
        in: path
        required: true
        schema:
          type: string
          title: Db Name
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDatabaseRequest'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskCreatedResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /preprocessing/update-all:
    post:
      tags:
      - preprocessing
      summary: Update All Databases
      description: 'Start the full preprocessing pipeline for all (or selected) databases.


        Processes databases in priority order. Equivalent to the legacy

        POST /preprocessing/start endpoint.'
      operationId: update_all_databases_preprocessing_update_all_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAllRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskCreatedResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /preprocessing/rebuild-reference-db:
    post:
      tags:
      - preprocessing
      summary: Rebuild Reference Db
      description: 'Rebuild reference_db.duckdb from existing parquet files.


        Does NOT re-download or re-convert. Creates a fresh DuckDB file

        from all available parquet data with atomic replacement.


        WARNING: Reference database is temporarily unavailable during rebuild.

        Active analysis sessions may fail.'
      operationId: rebuild_reference_db_preprocessing_rebuild_reference_db_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RebuildReferenceDBRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskCreatedResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /preprocessing/tasks/{task_id}:
    get:
      tags:
      - preprocessing
      summary: Get Task Status
      description: Get detailed progress for a running or completed task.
      operationId: get_task_status_preprocessing_tasks__task_id__get
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
          title: Task Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskStatusSchema'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /preprocessing/tasks:
    get:
      tags:
      - preprocessing
      summary: List Tasks
      description: Get status of all preprocessing tasks (running and historical).
      operationId: list_tasks_preprocessing_tasks_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskListResponse'
  /preprocessing/vep-cache/stats:
    get:
      tags:
      - preprocessing
      summary: Get Vep Cache Stats
      description: 'Get aggregated statistics for the VEP annotation cache.


        Read-only endpoint. Opens vep_cache.duckdb with read_only=True.

        Does not acquire any locks -- safe during concurrent pipeline runs.

        Typical response time: < 1 second for ~50M rows.'
      operationId: get_vep_cache_stats_preprocessing_vep_cache_stats_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VepCacheStatsResponse'
  /preprocessing/vep-cache/search:
    get:
      tags:
      - preprocessing
      summary: Search Vep Cache
      description: 'Search the VEP annotation cache by variant coordinates or gene symbol.


        Two modes:

        - Variant lookup: provide chromosome + position (optionally ref + alt)

        - Gene search: provide gene symbol


        All queries use parameterized SQL (B1). Read-only, no locks.'
      operationId: search_vep_cache_preprocessing_vep_cache_search_get
      parameters:
      - name: chromosome
        in: query
        required: false
        schema:
          type: string
          title: Chromosome
      - name: position
        in: query
        required: false
        schema:
          type: integer
          title: Position
      - name: ref
        in: query
        required: false
        schema:
          type: string
          title: Ref
      - name: alt
        in: query
        required: false
        schema:
          type: string
          title: Alt
      - name: gene
        in: query
        required: false
        schema:
          type: string
          title: Gene
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VepCacheSearchResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    DatabaseDetailResponse:
      properties:
        name:
          type: string
          title: Name
        display_name:
          type: string
          title: Display Name
        version:
          anyOf:
          - type: string
          - type: 'null'
          title: Version
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        priority:
          type: integer
          title: Priority
        enabled:
          type: boolean
          title: Enabled
          default: true
        license_required:
          type: boolean
          title: License Required
          default: false
        vep_required:
          type: boolean
          title: Vep Required
          default: false
        source_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Url
        source:
          $ref: '#/components/schemas/SourceStatusSchema'
        parquet:
          $ref: '#/components/schemas/ParquetStatusSchema'
        reference_db:
          $ref: '#/components/schemas/ReferenceDBTableSchema'
        freshness:
          $ref: '#/components/schemas/FreshnessSchema'
        validation:
          $ref: '#/components/schemas/ValidationSchema'
        detail:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Detail
      type: object
      required:
      - name
      - display_name
      - priority
      - source
      - parquet
      - reference_db
      - freshness
      - validation
      title: DatabaseDetailResponse
      description: Response for GET /preprocessing/databases/{db_name} with detail.
    UpdateAllRequest:
      properties:
        databases:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Databases
        force:
          type: boolean
          title: Force
          default: false
      type: object
      title: UpdateAllRequest
      description: Request for POST /preprocessing/update-all.
    DatabaseStatusSchema:
      properties:
        name:
          type: string
          title: Name
        display_name:
          type: string
          title: Display Name
        version:
          anyOf:
          - type: string
          - type: 'null'
          title: Version
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        priority:
          type: integer
          title: Priority
        enabled:
          type: boolean
          title: Enabled
          default: true
        license_required:
          type: boolean
          title: License Required
          default: false
        vep_required:
          type: boolean
          title: Vep Required
          default: false
        source_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Url
        source:
          $ref: '#/components/schemas/SourceStatusSchema'
        parquet:
          $ref: '#/components/schemas/ParquetStatusSchema'
        reference_db:
          $ref: '#/components/schemas/ReferenceDBTableSchema'
        freshness:
          $ref: '#/components/schemas/FreshnessSchema'
        validation:
          $ref: '#/components/schemas/ValidationSchema'
      type: object
      required:
      - name
      - display_name
      - priority
      - source
      - parquet
      - reference_db
      - freshness
      - validation
      title: DatabaseStatusSchema
      description: Complete status of one database.
    VepCacheChromosomeEntry:
      properties:
        chromosome:
          type: string
          title: Chromosome
        positive:
          type: integer
          title: Positive
        negative:
          type: integer
          title: Negative
      type: object
      required:
      - chromosome
      - positive
      - negative
      title: VepCacheChromosomeEntry
      description: Chromosome-level cache coverage.
    VepCacheStatsResponse:
      properties:
        file_exists:
          type: boolean
          title: File Exists
        file_size_bytes:
          type: integer
          title: File Size Bytes
          default: 0
        file_size_human:
          type: string
          title: File Size Human
          default: 0 B
        vep_version:
          anyOf:
          - type: string
          - type: 'null'
          title: Vep Version
        positive_count:
          type: integer
          title: Positive Count
          default: 0
        negative_count:
          type: integer
          title: Negative Count
          default: 0
        total_count:
          type: integer
          title: Total Count
          default: 0
        oldest_entry:
          anyOf:
          - type: string
          - type: 'null'
          title: Oldest Entry
        newest_entry:
          anyOf:
          - type: string
          - type: 'null'
          title: Newest Entry
        dedup_cutoff:
          anyOf:
          - type: string
          - type: 'null'
          title: Dedup Cutoff
        impact_distribution:
          items:
            $ref: '#/components/schemas/VepCacheDistributionEntry'
          type: array
          title: Impact Distribution
          default: []
        consequence_distribution:
          items:
            $ref: '#/components/schemas/VepCacheDistributionEntry'
          type: array
          title: Consequence Distribution
          default: []
        biotype_distribution:
          items:
            $ref: '#/components/schemas/VepCacheDistributionEntry'
          type: array
          title: Biotype Distribution
          default: []
        chromosome_distribution:
          items:
            $ref: '#/components/schemas/VepCacheChromosomeEntry'
          type: array
          title: Chromosome Distribution
          default: []
        sample_positive:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Sample Positive
          default: []
        sample_negative:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Sample Negative
          default: []
        query_time_ms:
          type: integer
          title: Query Time Ms
          default: 0
      type: object
      required:
      - file_exists
      title: VepCacheStatsResponse
      description: Response for GET /preprocessing/vep-cache/stats.
    UpdateDatabaseRequest:
      properties:
        steps:
          items:
            type: string
          type: array
          title: Steps
          default:
          - download
          - convert
          - load
        force:
          type: boolean
          title: Force
          default: false
      type: object
      title: UpdateDatabaseRequest
      description: Request for POST /preprocessing/databases/{db_name}/update.
    AllDatabasesStatusResponse:
      properties:
        reference_db:
          $ref: '#/components/schemas/ReferenceDBSummarySchema'
        databases:
          items:
            $ref: '#/components/schemas/DatabaseStatusSchema'
          type: array
          title: Databases
      type: object
      required:
      - reference_db
      - databases
      title: AllDatabasesStatusResponse
      description: Response for GET /preprocessing/databases.
    TaskCreatedResponse:
      properties:
        task_id:
          type: string
          title: Task Id
        status:
          type: string
          title: Status
        databases:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Databases
        status_url:
          type: string
          title: Status Url
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
        warning:
          anyOf:
          - type: string
          - type: 'null'
          title: Warning
      type: object
      required:
      - task_id
      - status
      - status_url
      title: TaskCreatedResponse
      description: Response for task creation endpoints (202 Accepted).
    ValidationSchema:
      properties:
        passed:
          type: boolean
          title: Passed
        checks:
          additionalProperties: true
          type: object
          title: Checks
          default: {}
      type: object
      required:
      - passed
      title: ValidationSchema
      description: Validation results.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TaskStatusSchema:
      properties:
        task_id:
          type: string
          title: Task Id
        status:
          type: string
          title: Status
        started_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Started At
        completed_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Completed At
        elapsed_seconds:
          anyOf:
          - type: number
          - type: 'null'
          title: Elapsed Seconds
        databases:
          additionalProperties: true
          type: object
          title: Databases
          default: {}
        current_database:
          anyOf:
          - type: string
          - type: 'null'
          title: Current Database
        current_step:
          anyOf:
          - type: string
          - type: 'null'
          title: Current Step
        log_tail:
          items:
            type: string
          type: array
          title: Log Tail
          default: []
        successful:
          anyOf:
          - type: integer
          - type: 'null'
          title: Successful
        failed:
          anyOf:
          - type: integer
          - type: 'null'
          title: Failed
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
      type: object
      required:
      - task_id
      - status
      title: TaskStatusSchema
      description: Task progress response.
    RebuildReferenceDBRequest:
      properties:
        confirm:
          type: boolean
          title: Confirm
          default: false
      type: object
      title: RebuildReferenceDBRequest
      description: Request for POST /preprocessing/rebuild-reference-db.
    TaskListResponse:
      properties:
        tasks:
          items:
            $ref: '#/components/schemas/TaskStatusSchema'
          type: array
          title: Tasks
        total:
          type: integer
          title: Total
        running:
          type: integer
          title: Running
      type: object
      required:
      - tasks
      - total
      - running
      title: TaskListResponse
      description: Response for GET /preprocessing/tasks.
    VepCacheSearchResult:
      properties:
        mode:
          type: string
          title: Mode
        query_time_ms:
          type: integer
          title: Query Time Ms
          default: 0
        status:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
        positive_hits:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Positive Hits
          default: []
        negative_hits:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Negative Hits
          default: []
        gene:
          anyOf:
          - type: string
          - type: 'null'
          title: Gene
        total_variants:
          type: integer
          title: Total Variants
          default: 0
        consequence_breakdown:
          items:
            $ref: '#/components/schemas/VepCacheConsequenceBreakdown'
          type: array
          title: Consequence Breakdown
          default: []
        sample_variants:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Sample Variants
          default: []
      type: object
      required:
      - mode
      title: VepCacheSearchResult
      description: Response for GET /preprocessing/vep-cache/search.
    SourceStatusSchema:
      properties:
        exists:
          type: boolean
          title: Exists
        path:
          type: string
          title: Path
        files_found:
          type: integer
          title: Files Found
          default: 0
        files_expected:
          type: integer
          title: Files Expected
          default: 0
        total_size_bytes:
          type: integer
          title: Total Size Bytes
          default: 0
        total_size_human:
          type: string
          title: Total Size Human
          default: 0 B
        oldest_file_modified:
          anyOf:
          - type: string
          - type: 'null'
          title: Oldest File Modified
        newest_file_modified:
          anyOf:
          - type: string
          - type: 'null'
          title: Newest File Modified
      type: object
      required:
      - exists
      - path
      title: SourceStatusSchema
      description: Source files on disk.
    ParquetStatusSchema:
      properties:
        exists:
          type: boolean
          title: Exists
        path:
          type: string
          title: Path
        partitions:
          type: integer
          title: Partitions
          default: 0
        partitions_expected:
          type: integer
          title: Partitions Expected
          default: 0
        total_size_bytes:
          type: integer
          title: Total Size Bytes
          default: 0
        total_size_human:
          type: string
          title: Total Size Human
          default: 0 B
        last_modified:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Modified
        row_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Row Count
        conversion_metadata:
          anyOf:
          - $ref: '#/components/schemas/ConversionMetadataSchema'
          - type: 'null'
      type: object
      required:
      - exists
      - path
      title: ParquetStatusSchema
      description: Parquet conversion status.
    ConversionMetadataSchema:
      properties:
        start_time:
          anyOf:
          - type: string
          - type: 'null'
          title: Start Time
        elapsed_seconds:
          anyOf:
          - type: number
          - type: 'null'
          title: Elapsed Seconds
        elapsed_human:
          anyOf:
          - type: string
          - type: 'null'
          title: Elapsed Human
        successful_chromosomes:
          anyOf:
          - type: integer
          - type: 'null'
          title: Successful Chromosomes
        failed_chromosomes:
          anyOf:
          - type: integer
          - type: 'null'
          title: Failed Chromosomes
      type: object
      title: ConversionMetadataSchema
      description: Conversion metadata summary.
    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
    ReferenceDBTableSchema:
      properties:
        loaded:
          type: boolean
          title: Loaded
        table_name:
          type: string
          title: Table Name
        row_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Row Count
        column_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Column Count
      type: object
      required:
      - loaded
      - table_name
      title: ReferenceDBTableSchema
      description: Status of a table in reference_db.duckdb.
    VepCacheDistributionEntry:
      properties:
        label:
          type: string
          title: Label
        count:
          type: integer
          title: Count
        pct:
          type: number
          title: Pct
          default: 0.0
      type: object
      required:
      - label
      - count
      title: VepCacheDistributionEntry
      description: Single row in a distribution breakdown.
    VepCacheConsequenceBreakdown:
      properties:
        consequence:
          type: string
          title: Consequence
        impact:
          type: string
          title: Impact
        count:
          type: integer
          title: Count
      type: object
      required:
      - consequence
      - impact
      - count
      title: VepCacheConsequenceBreakdown
      description: Single row in gene consequence breakdown.
    FreshnessSchema:
      properties:
        status:
          type: string
          title: Status
        message:
          type: string
          title: Message
        source_age_days:
          anyOf:
          - type: integer
          - type: 'null'
          title: Source Age Days
        parquet_age_days:
          anyOf:
          - type: integer
          - type: 'null'
          title: Parquet Age Days
        cache_ttl_days:
          anyOf:
          - type: integer
          - type: 'null'
          title: Cache Ttl Days
        is_within_ttl:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Within Ttl
        suggested_action:
          anyOf:
          - type: string
          - type: 'null'
          title: Suggested Action
      type: object
      required:
      - status
      - message
      title: FreshnessSchema
      description: Freshness assessment.
    ReferenceDBSummarySchema:
      properties:
        exists:
          type: boolean
          title: Exists
        file_path:
          type: string
          title: File Path
        file_size_bytes:
          type: integer
          title: File Size Bytes
          default: 0
        file_size_human:
          type: string
          title: File Size Human
          default: 0 B
        last_modified:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Modified
        tables:
          items:
            type: string
          type: array
          title: Tables
          default: []
        total_rows:
          type: integer
          title: Total Rows
          default: 0
      type: object
      required:
      - exists
      - file_path
      title: ReferenceDBSummarySchema
      description: Summary of reference_db.duckdb.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer