Build a Research Study Specimen Provenance Reconciler — implementation

## Build
Correlate specimen accession identifiers from NCBI gene data packages with FHIR Specimen resources. Verify collection context and track specimen chain-of-custody in research registries.

## User
Biobank Repository Coordinator

## Workflow
1. Read specimen source tables and RefSeq accession metadata from NCBI gene packages.
2. Validate specimen attributes against FHIR Specimen and ResearchStudy resource definitions.
3. Flag records missing mandatory specimen processing timestamps or tissue source ontology codes.
4. Construct validated FHIR Specimen resource bundles with resolved provenance references.

## Interface
Browser-based audit table showing missing accession links, tissue type codes, and batch export buttons.

## Data
Generate synthetic biobank records matching NCBI Datasets gene accession formats stored as local JSON files.
Starter examples below are synthetic. They are not downloaded records.

## Source
[HL7 FHIR overview](https://hl7.org/fhir/overview.html)
Applies FHIR R5 foundation definitions for Specimen, ResearchStudy, and Provenance metadata structures.

## Tools
vercel-ai-sdk, pydantic, nextjs.
vercel-ai-sdk streams UI-driven JSON schema validation errors and provenance corrections directly to web curators.
Hosted or local model accessed via streaming HTTP API; low latency token generation for rapid UI feedback.

## 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
- Verify 100% of specimen entries against FHIR Specimen structural constraints.
- Identify and flag specimens missing SNOMED or NCIT anatomical origin codes.
- Generate valid FHIR Provenance records establishing input data package provenance.

## Starter Examples
```json
[
  {
    "input": {
      "sample_accession": "SAMN12345678",
      "gene_accession": "NM_020107.5",
      "tissue_code": "410602000",
      "tissue_display": "Liver"
    },
    "expected_output": {
      "resourceType": "Specimen",
      "id": "SAMN12345678",
      "type": {
        "coding": [
          {
            "system": "http://snomed.info/sct",
            "code": "410602000",
            "display": "Liver"
          }
        ]
      },
      "status": "available",
      "provenance_valid": true
    }
  },
  {
    "input": {
      "sample_accession": "SAMN87654321",
      "gene_accession": "NM_020107.5",
      "tissue_code": "",
      "tissue_display": "Unknown Tissue"
    },
    "expected_output": {
      "resourceType": "Specimen",
      "id": "SAMN87654321",
      "status": "unavailable",
      "provenance_valid": false,
      "validation_errors": [
        "Missing required anatomical coding"
      ]
    }
  }
]
```

## Safety
Research specimen provenance tracking utilizing de-identified accession keys without clinical diagnostic advice.
Use mock external writes. Require human review before any real deployment.