# teba-cs/cunei-restore architecture

> Architecture diagram of the GitHub repository teba-cs/cunei-restore, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/teba-cs/cunei-restore
- Repository: https://github.com/teba-cs/cunei-restore

## Overview

CuneiML v3 is a multimodal Cuneiform restoration and dataset project: it acquires linked tablet images, builds a validated text-and-asset dataset, trains and evaluates restoration models, and produces uncertainty-aware line and tablet restorations. The graph follows the documented and sampled workflow; several subsystem links rely on module names and documented artifacts because their implementation was not sampled.

Main entry points: [`build_parquet_v3.py`](https://github.com/teba-cs/cunei-restore/blob/main/build_parquet_v3.py) (Linked dataset), [`prepare_examples_v3.py`](https://github.com/teba-cs/cunei-restore/blob/main/prepare_examples_v3.py) (Restoration examples), [`deploy_automatic_restoration_v3.py`](https://github.com/teba-cs/cunei-restore/blob/main/deploy_automatic_restoration_v3.py) (Automatic restoration), [`download_images.py`](https://github.com/teba-cs/cunei-restore/blob/main/download_images.py) (Image downloader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_source["Cuneiform source"]
  node_audit["Source audit<br/>[audit_source_v3.py]"]
  node_download["Image downloader<br/>[download_images.py]"]
  node_assetdb[("Download state<br/>[download_images.py]")]
  node_parquet[("Linked dataset")]
  node_splits["Frozen splits"]
  node_examples[("Restoration examples")]
end

subgraph group_model["Restoration models"]
  node_visual[("Visual embeddings")]
  node_training["Model training"]
  node_search["Architecture search"]
end

subgraph group_evaluation["Evaluation"]
  node_selection["Model selection"]
  node_calibration["Confidence calibration"]
  node_lock["Final model lock"]
  node_protected["Protected evaluation"]
  node_analysis["Results analysis"]
end

subgraph group_delivery["Restoration delivery"]
  node_runtime["Restoration runtime<br/>[runtime_v3.py]"]
  node_deployment["Automatic restoration"]
  node_outputs["Line and tablet results"]
end

node_researcher(("Researcher"))
node_cdli(("CDLI image host"))

node_researcher -->|"audits source"| node_audit
node_source -->|"validates records"| node_audit
node_researcher -->|"requests assets"| node_download
node_download -->|"downloads images"| node_cdli
node_download -->|"records state"| node_assetdb
node_audit -->|"provides audited records"| node_parquet
node_assetdb -->|"supplies asset metadata"| node_parquet
node_parquet -->|"provides tablet data"| node_splits
node_parquet -->|"provides lines and assets"| node_examples
node_splits -->|"gates example creation"| node_examples
node_parquet -->|"provides images"| node_visual
node_examples -->|"provides training data"| node_training
node_visual -.->|"provides visual features"| node_training
node_examples -->|"provides search data"| node_search
node_search -->|"provides model candidates"| node_selection
node_training -->|"provides trained variants"| node_selection
node_selection -->|"provides selected variant"| node_calibration
node_calibration -->|"locks calibrated model"| node_lock
node_lock -->|"authorizes evaluation"| node_protected
node_protected -->|"provides test results"| node_analysis
node_lock -->|"selects deployment model"| node_deployment
node_examples -->|"provides genuine gaps"| node_deployment
node_deployment -->|"uses inference"| node_runtime
node_deployment -->|"writes restorations"| node_outputs
node_researcher -->|"requests restoration"| node_deployment

click node_source "https://github.com/teba-cs/cunei-restore/blob/main/CuneiMLv1.2_multimodal_dataset_v3.py"
click node_audit "https://github.com/teba-cs/cunei-restore/blob/main/audit_source_v3.py"
click node_download "https://github.com/teba-cs/cunei-restore/blob/main/download_images.py"
click node_assetdb "https://github.com/teba-cs/cunei-restore/blob/main/download_images.py"
click node_parquet "https://github.com/teba-cs/cunei-restore/blob/main/build_parquet_v3.py"
click node_splits "https://github.com/teba-cs/cunei-restore/blob/main/freeze_splits_v3.py"
click node_examples "https://github.com/teba-cs/cunei-restore/blob/main/prepare_examples_v3.py"
click node_visual "https://github.com/teba-cs/cunei-restore/blob/main/extract_visual_embeddings_v3.py"
click node_training "https://github.com/teba-cs/cunei-restore/blob/main/train_five_models_v3.py"
click node_search "https://github.com/teba-cs/cunei-restore/blob/main/train_m0_search_v3.py"
click node_selection "https://github.com/teba-cs/cunei-restore/blob/main/evaluate_selection_v3.py"
click node_calibration "https://github.com/teba-cs/cunei-restore/blob/main/predict_calibration_v3.py"
click node_lock "https://github.com/teba-cs/cunei-restore/blob/main/calibrate_and_lock_v3.py"
click node_protected "https://github.com/teba-cs/cunei-restore/blob/main/evaluate_protected_test_v3.py"
click node_analysis "https://github.com/teba-cs/cunei-restore/blob/main/analyze_and_report_v3.py"
click node_runtime "https://github.com/teba-cs/cunei-restore/blob/main/runtime_v3.py"
click node_deployment "https://github.com/teba-cs/cunei-restore/blob/main/deploy_automatic_restoration_v3.py"
click node_outputs "https://github.com/teba-cs/cunei-restore/tree/main/outputs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_source,node_audit,node_download,node_assetdb,node_parquet,node_splits,node_examples toneBlue
class node_visual,node_training,node_search toneAmber
class node_selection,node_calibration,node_lock,node_protected,node_analysis toneMint
class node_runtime,node_deployment,node_outputs toneRose
class node_researcher,node_cdli toneIndigo
```

## Components

### Data preparation

- [Cuneiform source](https://github.com/teba-cs/cunei-restore/blob/main/CuneiMLv1.2_multimodal_dataset_v3.py): `CuneiMLv1.2_multimodal_dataset_v3.py`
- [Source audit](https://github.com/teba-cs/cunei-restore/blob/main/audit_source_v3.py): `audit_source_v3.py`
- [Image downloader](https://github.com/teba-cs/cunei-restore/blob/main/download_images.py): `download_images.py`
- [Download state](https://github.com/teba-cs/cunei-restore/blob/main/download_images.py): `download_images.py`
- [Linked dataset](https://github.com/teba-cs/cunei-restore/blob/main/build_parquet_v3.py): `build_parquet_v3.py`
- [Frozen splits](https://github.com/teba-cs/cunei-restore/blob/main/freeze_splits_v3.py): `freeze_splits_v3.py`
- [Restoration examples](https://github.com/teba-cs/cunei-restore/blob/main/prepare_examples_v3.py): `prepare_examples_v3.py`

### Restoration models

- [Visual embeddings](https://github.com/teba-cs/cunei-restore/blob/main/extract_visual_embeddings_v3.py): `extract_visual_embeddings_v3.py`
- [Model training](https://github.com/teba-cs/cunei-restore/blob/main/train_five_models_v3.py): `train_five_models_v3.py`
- [Architecture search](https://github.com/teba-cs/cunei-restore/blob/main/train_m0_search_v3.py): `train_m0_search_v3.py`

### Evaluation

- [Model selection](https://github.com/teba-cs/cunei-restore/blob/main/evaluate_selection_v3.py): `evaluate_selection_v3.py`
- [Confidence calibration](https://github.com/teba-cs/cunei-restore/blob/main/predict_calibration_v3.py): `predict_calibration_v3.py`
- [Final model lock](https://github.com/teba-cs/cunei-restore/blob/main/calibrate_and_lock_v3.py): `calibrate_and_lock_v3.py`
- [Protected evaluation](https://github.com/teba-cs/cunei-restore/blob/main/evaluate_protected_test_v3.py): `evaluate_protected_test_v3.py`
- [Results analysis](https://github.com/teba-cs/cunei-restore/blob/main/analyze_and_report_v3.py): `analyze_and_report_v3.py`

### Restoration delivery

- [Restoration runtime](https://github.com/teba-cs/cunei-restore/blob/main/runtime_v3.py): `runtime_v3.py`
- [Automatic restoration](https://github.com/teba-cs/cunei-restore/blob/main/deploy_automatic_restoration_v3.py): `deploy_automatic_restoration_v3.py`
- [Line and tablet results](https://github.com/teba-cs/cunei-restore/tree/main/outputs): `outputs`

### Other components

- **Researcher**
- **CDLI image host**

## Connections

- Researcher → Source audit: audits source
- Cuneiform source → Source audit: validates records
- Researcher → Image downloader: requests assets
- Image downloader → CDLI image host: downloads images
- Image downloader → Download state: records state
- Source audit → Linked dataset: provides audited records
- Download state → Linked dataset: supplies asset metadata
- Linked dataset → Frozen splits: provides tablet data
- Linked dataset → Restoration examples: provides lines and assets
- Frozen splits → Restoration examples: gates example creation
- Linked dataset → Visual embeddings: provides images
- Restoration examples → Model training: provides training data
- Visual embeddings → Model training: provides visual features
- Restoration examples → Architecture search: provides search data
- Architecture search → Model selection: provides model candidates
- Model training → Model selection: provides trained variants
- Model selection → Confidence calibration: provides selected variant
- Confidence calibration → Final model lock: locks calibrated model
- Final model lock → Protected evaluation: authorizes evaluation
- Protected evaluation → Results analysis: provides test results
- Final model lock → Automatic restoration: selects deployment model
- Restoration examples → Automatic restoration: provides genuine gaps
- Automatic restoration → Restoration runtime: uses inference
- Automatic restoration → Line and tablet results: writes restorations
- Researcher → Automatic restoration: requests restoration