Build a Research Specimen Biorepository FHIR Resource Harmonizer — implementation

## Build
Correlate research specimen IDs against NCBI taxon catalogs and standard biospecimen collection hierarchies. Format validated research samples into FHIR Specimen and ResearchStudy entities.

## User
Biobank Translational Coordinator

## Workflow
1. Parse multi-sample specimen metadata CSV manifests exported from laboratory biobanking systems.
2. Map organism taxonomy to standard NCBI Taxonomy IDs using NCBI Datasets species metadata rules.
3. Validate container, body site, and preservation status attributes against FHIR Specimen structure rules.
4. Generate interconnected FHIR Specimen and ResearchStudy resource bundles.

## Interface
Web dashboard with file upload, validation rule editor, and JSON FHIR resource bundle visualizer.

## Data
Create synthetic biobank manifest CSV files referencing public human and murine taxon identifiers from NCBI Datasets.
Starter examples below are synthetic. They are not downloaded records.

## Source
[HL7 FHIR overview](https://hl7.org/fhir/overview.html)
Applies FHIR R5 core foundations including Specimen resource structure and resource reference composition patterns.

## Tools
pydantic-ai, fastapi, biopython.
Enforces strict type safety and schema validation across relational FHIR R5 research resource structures.
API-hosted or local lightweight model capable of resolving ambiguous biobank tissue nomenclature.

## 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
- Parses multi-sample biorepository tables and maps taxonomy to official NCBI Taxonomy IDs.
- Validates mandatory FHIR Specimen fields including status, type, and collection context.
- Produces complete FHIR R5 Bundle containing linked Specimen and ResearchStudy JSON objects.

## Starter Examples
```json
[
  {
    "input": {
      "specimen_id": "SPEC-001",
      "organism": "human",
      "tissue_type": "Peripheral blood mononuclear cells",
      "collection_method": "Venipuncture"
    },
    "expected_output": {
      "taxon_id": 9606,
      "valid": true,
      "bundle": {
        "resourceType": "Bundle",
        "type": "collection",
        "entry": [
          {
            "resource": {
              "resourceType": "Specimen",
              "id": "SPEC-001",
              "status": "available",
              "type": {
                "text": "Peripheral blood mononuclear cells"
              }
            }
          }
        ]
      }
    }
  },
  {
    "input": {
      "specimen_id": "SPEC-002",
      "organism": "unknown_isolate",
      "tissue_type": "",
      "collection_method": "Biopsy"
    },
    "expected_output": {
      "taxon_id": null,
      "valid": false,
      "errors": [
        "Missing mandatory tissue type",
        "Unrecognized organism taxon 'unknown_isolate'"
      ],
      "bundle": null
    }
  }
]
```

## Safety
Restricted to de-identified synthetic specimen manifests; no private clinical or protected health records used.
Use mock external writes. Require human review before any real deployment.