Build a Transcript CDS Boundary and Reading Frame Validator — implementation

## Build
Inspect coding sequence coordinates in NCBI Datasets gene packages to ensure intact open reading frames. Translate sequences using Biopython and output FHIR Molecular Observation records.

## User
Genomic Annotation Engineer

## Workflow
1. Extract CDS sequences and corresponding start/stop coordinates from an NCBI Datasets archive.
2. Compute reading frame integrity using Biopython Seq methods to detect internal stop codons.
3. Calculate codon usage frequencies and flag frameshift anomalies.
4. Format verified CDS status into structured FHIR Observation resources.

## Interface
Console terminal CLI with an optional single-page HTML report summarizing reading frame errors and codon metrics.

## Data
Download human gene CDS packages via NCBI Datasets CLI using the --include cds option.
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/)
Utilizes the NCBI Datasets gene package --include cds,rna option to access exact coding sequence boundaries.

## Tools
optuna, biopython, pandas.
optuna tunes parameter thresholds for codon anomaly scoring and sequence length filter boundaries.
Local Python execution environment; optional lightweight model for generating error summary messages.

## 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
- Detect sequences with lengths not divisible by 3 as frameshift anomalies.
- Identify internal premature stop codons within input CDS records.
- Generate FHIR Observation records specifying reading frame validity.

## Starter Examples
```json
[
  {
    "input": {
      "accession": "NM_001.1_cds",
      "sequence": "ATGGCCAAGGTCTGA"
    },
    "expected_output": {
      "accession": "NM_001.1_cds",
      "length_mod_3": 0,
      "internal_stops": 0,
      "valid_frame": true,
      "fhir_observation": {
        "resourceType": "Observation",
        "status": "final",
        "code": {
          "text": "Reading Frame Conformance"
        },
        "valueBoolean": true
      }
    }
  },
  {
    "input": {
      "accession": "NM_002.1_cds",
      "sequence": "ATGGCTAACTGAACCA"
    },
    "expected_output": {
      "accession": "NM_002.1_cds",
      "length_mod_3": 1,
      "internal_stops": 1,
      "valid_frame": false,
      "fhir_observation": {
        "resourceType": "Observation",
        "status": "preliminary",
        "code": {
          "text": "Reading Frame Conformance"
        },
        "valueBoolean": false
      }
    }
  }
]
```

## Safety
Focuses strictly on reading frame arithmetic and codon parsing on synthetic/mock sequences. No patient clinical impact.
Use mock external writes. Require human review before any real deployment.