Build an NCBI Gene Synonym Drift and Nomenclature Auditor — implementation

## Build
Track gene symbol synonyms and catalog changes from NCBI Datasets gene metadata reports. Harmonize historical aliases into canonical identifiers mapped to FHIR Terminology bindings.

## User
Bioinformatics Data Curator

## Workflow
1. Parse gene data reports extracted from NCBI Datasets JSON packages using Pydantic schemas.
2. Extract current official gene symbols, historical synonyms, and cross-referenced taxonomy tags.
3. Reconcile obsolete aliases against canonical FHIR Coding datatypes with human-readable narratives.
4. Output structured audit reports highlighting deprecated symbols and recommended canonical mappings.

## Interface
Tabular browser interface showing obsolete aliases alongside canonical FHIR ConceptMap entries.

## Data
Ingest synthetic NCBI gene-service reports representing human genes A2M and ACRV1 from local mock files.
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 NCBI Datasets symbol query pattern 'datasets download gene symbol ACRV1 A2M --taxon human' and resulting metadata reports.

## Tools
pydantic-ai, biopython, streamlit.
Enforces strict data model boundaries on multi-field NCBI metadata reports and nested FHIR terminology objects.
General purpose hosted reasoning model or local LLM via Ollama for alias disambiguation.

## 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
- Extracts all listed synonyms from NCBI gene data report JSON without data loss.
- Maps uncurated symbols to valid FHIR Coding objects including system, code, and display fields.
- Flags ambiguous historical aliases shared across multiple distinct Gene IDs.

## Starter Examples
```json
[
  {
    "input": {
      "gene_id": 2,
      "current_symbol": "A2M",
      "taxname": "Homo sapiens",
      "synonyms": [
        "A2MD",
        "CPAMD5",
        "FWP007"
      ]
    },
    "expected_output": {
      "canonical_symbol": "A2M",
      "gene_id": 2,
      "synonyms_found": 3,
      "fhir_coding": {
        "system": "https://www.ncbi.nlm.nih.gov/gene",
        "code": "2",
        "display": "A2M"
      },
      "status": "harmonized"
    }
  },
  {
    "input": {
      "gene_id": 9999,
      "current_symbol": "UNKNOWN",
      "taxname": "Homo sapiens",
      "synonyms": []
    },
    "expected_output": {
      "canonical_symbol": "UNKNOWN",
      "gene_id": 9999,
      "synonyms_found": 0,
      "fhir_coding": {
        "system": "https://www.ncbi.nlm.nih.gov/gene",
        "code": "9999",
        "display": "UNKNOWN"
      },
      "status": "unresolved_synonyms"
    }
  }
]
```

## Safety
Research data harmonization only; does not inform patient diagnostic reports or medication administration.
Use mock external writes. Require human review before any real deployment.