Build the application

## Build
Inspect coding sequence coordinates across multi-transcript gene packages to identify translational frame shifts. Generate structured FHIR Observation payloads tracking open reading frame integrity.

## User
Functional Genomics Biocurator

## Workflow
1. Load CDS and protein sequences from NCBI gene packages using Biopython.
2. Translate nucleotide CDS records across all three reading frames using the standard translation table.
3. Identify reading frame alignments that produce exact peptide matches against NCBI RefSeq protein records.
4. Generate FHIR Observation resources documenting reading frame validity and detected stop anomalies.

## Interface
FastAPI backend serving JSON inspection endpoints and an HTML table displaying frame translation alignments.

## Data
Download human BRCA1 gene packages using NCBI Datasets CLI `--include cds,protein` into local sandbox folders.
Starter examples below are synthetic. They are not downloaded records.

## Source
[NCBI Datasets gene download](https://www.ncbi.nlm.nih.gov/datasets/docs/v2/how-tos/genes/download-gene-data-package/)
Processes CDS and protein sequences retrieved via NCBI Datasets `--include cds,protein` parameters.

## Tools
pydantic-ai, biopython, fastapi.
Pydantic AI guarantees type constraints and schema enforcement for complex translation and reading frame models.
Lightweight API or local model to generate structured explanations of frame-shift causes.

## Deliverables
Submit runnable source, pinned dependencies, setup commands, a working interface, example outputs, and a recorded end-to-end demo. Include tests and an action log.

## Acceptance
- Translates CDS sequences using Biopython Seq.translate and compares with target protein sequences.
- Identifies reading frame offset (frame 0, +1, or +2) matching the documented protein product.
- Outputs compliant FHIR R5 Observation records with appropriate status codes and valueCodings.

## Starter Examples
```json
[
  {
    "input": {
      "transcript_id": "NM_0001",
      "cds_seq": "ATGGCCAACGTATAG",
      "expected_protein": "MANV"
    },
    "expected_output": {
      "frame_offset": 0,
      "exact_match": true,
      "fhir_observation": {
        "resourceType": "Observation",
        "status": "final",
        "code": {
          "coding": [
            {
              "system": "http://hl7.org/fhir/sid/ncbi-gene",
              "code": "NM_0001"
            }
          ]
        },
        "valueString": "In-frame translation confirmed with matching protein accession"
      }
    }
  },
  {
    "input": {
      "transcript_id": "NM_0002",
      "cds_seq": "TGGCCAACGTATAG",
      "expected_protein": "MANV"
    },
    "expected_output": {
      "frame_offset": null,
      "exact_match": false,
      "fhir_observation": {
        "resourceType": "Observation",
        "status": "preliminary",
        "code": {
          "coding": [
            {
              "system": "http://hl7.org/fhir/sid/ncbi-gene",
              "code": "NM_0002"
            }
          ]
        },
        "valueString": "Frame shift or missing start codon: no reading frame matched MANV"
      }
    }
  }
]
```

## Safety
Uses open-access reference transcript sequences without individual patient exposure or clinical claims.
Use mock external writes. Require human review before any real deployment.