Build a Gene Catalog Nomenclature Drift Detector — implementation

## Build
Evaluate gene symbol synonym catalogs from NCBI Datasets gene reports against FHIR terminology standards. Detect naming conflicts across multi-species registries and record migration actions.

## User
Genomic Terminology Curator

## Workflow
1. Extract gene symbols and synonym lists from downloaded NCBI gene metadata reports.
2. Audit extracted nomenclatures against FHIR CodeSystem and ConceptMap structures.
3. Detect ambiguous multi-symbol collisions or deprecated HGNC nomenclature strings.
4. Produce standardized FHIR ConceptMap entries detailing recommended term mappings.

## Interface
Web interface showing nomenclature conflict alerts, symbol mapping graphs, and approved synonym dictionaries.

## Data
Ingest public human gene metadata reports via NCBI Datasets command for symbols ACRV1 and A2M.
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/)
Extracts gene symbols and synonyms from NCBI Datasets gene report metadata formats.

## Tools
crewai, pydantic, duckdb.
crewai coordinates distinct curation sub-tasks including terminology validation, synonym parsing, and conflict auditing.
Hosted or local model via OpenAI-compatible endpoints with structured JSON emission capabilities.

## 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
- Extract all reported gene synonyms from NCBI metadata JSON files.
- Produce a valid FHIR ConceptMap element with equivalence mapping fields.
- Flag cases where one symbol maps to multiple distinct NCBI Gene IDs.

## Starter Examples
```json
[
  {
    "input": {
      "gene_id": "2",
      "symbol": "A2M",
      "synonyms": [
        "A2MD",
        "CPAMD5",
        "FWP007"
      ],
      "hgnc_approved": "A2M"
    },
    "expected_output": {
      "resourceType": "ConceptMap",
      "status": "active",
      "group": [
        {
          "source": "http://ncbi.nlm.nih.gov/gene",
          "target": "http://www.genenames.org",
          "element": [
            {
              "code": "A2M",
              "target": [
                {
                  "code": "HGNC:7",
                  "equivalence": "equivalent"
                }
              ]
            }
          ]
        }
      ],
      "collision_detected": false
    }
  },
  {
    "input": {
      "gene_id": "99999",
      "symbol": "OCT4",
      "synonyms": [
        "POU5F1",
        "OCT3"
      ],
      "hgnc_approved": "POU5F1"
    },
    "expected_output": {
      "resourceType": "ConceptMap",
      "status": "draft",
      "group": [
        {
          "source": "http://ncbi.nlm.nih.gov/gene",
          "target": "http://www.genenames.org",
          "element": [
            {
              "code": "OCT4",
              "target": [
                {
                  "code": "HGNC:9221",
                  "equivalence": "wider"
                }
              ]
            }
          ]
        }
      ],
      "collision_detected": true
    }
  }
]
```

## Safety
Performs lexical terminology validation only. Synthetic records used without patient identifiers or diagnostic impact.
Use mock external writes. Require human review before any real deployment.