Build a Research Specimen Chain of Custody and Terminology Reconciler — implementation

## Build
Align biological specimen identifiers against NCBI gene taxons and assemble FHIR Specimen resources. Audit collection records for standard terminology conformance before registry federation.

## User
Biobank Operations Manager

## Workflow
1. Ingest biobank manifest rows cross-referenced with NCBI Datasets taxonomy IDs.
2. Verify species nomenclature against NCBI taxonomy records using Biopython Entrez parsers.
3. Map collection site and specimen handling codes into standard SNOMED research concepts.
4. Format validated records into standard FHIR R5 Specimen resource bundles.

## Interface
Multi-pane dashboard displaying specimen reconciliation grids and FHIR JSON preview panels.

## Data
Ingest public synthetic biobank manifests mapped to NCBI Datasets taxon IDs like 'human' (Taxonomy ID 9606).
Starter examples below are synthetic. They are not downloaded records.

## Source
[HL7 FHIR overview](https://hl7.org/fhir/overview.html)
Applies FHIR R5 Foundation and Specimen resource definitions with standardized terminology bindings.

## Tools
pydantic-ai, biopython, fastapi.
Pydantic AI guarantees strictly validated FHIR schema outputs conforming to specimen data contracts.
Fast cloud LLM API or local small model with JSON schema enforcement.

## 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
- Generates FHIR Specimen resources matching HL7 R5 core element requirements.
- Detects unmapped or invalid species taxonomy identifiers prior to FHIR bundle generation.
- Emits validation error diagnostics when mandatory collection body site attributes are omitted.

## Starter Examples
```json
[
  {
    "input": {
      "specimen_id": "SPEC-9912",
      "taxon_name": "human",
      "sample_type": "PBMC",
      "collection_site": "peripheral_venous_blood"
    },
    "expected_output": {
      "resourceType": "Specimen",
      "id": "SPEC-9912",
      "status": "available",
      "type": {
        "coding": [
          {
            "system": "http://snomed.info/sct",
            "code": "119297000",
            "display": "Blood specimen"
          }
        ]
      },
      "subject": {
        "identifier": {
          "system": "https://ncbi.nlm.nih.gov/taxonomy",
          "value": "9606"
        }
      }
    }
  },
  {
    "input": {
      "specimen_id": "SPEC-MISSING-SITE",
      "taxon_name": "human",
      "sample_type": "Unknown",
      "collection_site": null
    },
    "expected_output": {
      "resourceType": "OperationOutcome",
      "issue": [
        {
          "severity": "error",
          "code": "required",
          "diagnostics": "Missing mandatory collection site or sample type mapping"
        }
      ]
    }
  }
]
```

## Safety
Deidentified synthetic data only; no Protected Health Information is ingested or stored.
Use mock external writes. Require human review before any real deployment.