# oruk-ai/orukeet architecture

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

- Interactive diagram: https://gitdiagram.com/oruk-ai/orukeet
- Repository: https://github.com/oruk-ai/orukeet

## Overview

Orukeet is both a multilingual speech-recognition product and a model-development repository. Its user workflow installs a verified model/runtime, loads a recording through the Python API or persistent worker, decodes it with the native recognizer, and returns text (and word timing data). The repository also contains the Gabor fitting and fine-tuning work, model export, and evaluation programs that support the released recognizer. Training and evaluation subworkflows are only partly evidenced by the supplied excerpts and index; their edges are limited accordingly.

Main entry points: [`src/orukeet/model.py`](https://github.com/oruk-ai/orukeet/blob/main/src/orukeet/model.py) (Python recognizer), [`training/librispeech_ft/train.py`](https://github.com/oruk-ai/orukeet/blob/main/training/librispeech_ft/train.py) (Model fine-tuning), [`evaluation/unseen/run.py`](https://github.com/oruk-ai/orukeet/blob/main/evaluation/unseen/run.py) (Unseen evaluation), [`src/orukeet/install.py`](https://github.com/oruk-ai/orukeet/blob/main/src/orukeet/install.py) (Runtime installer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data and training"]
  node_datasets["Prepared speech data"]
  node_data_audit["Dataset audit<br/>[audit_prepare.py]"]
  node_coverage["Unseen coverage"]
end

subgraph group_model["Model development"]
  node_gabor_fit["Gabor fitting<br/>[fit.py]"]
  node_frozen["Frozen Gabor kernels<br/>[frozen.py]"]
  node_finetune["Model fine-tuning<br/>[train.py]"]
  node_regression_train["Accent adaptation<br/>[train.py]"]
  node_selection["Checkpoint selection"]
end

subgraph group_eval["Evaluation"]
  node_asr_eval["ASR evaluation<br/>[run.py]"]
  node_unseen_eval["Unseen evaluation<br/>[run.py]"]
  node_metrics["Scoring metrics<br/>[metrics.py]"]
end

subgraph group_release["Export and release"]
  node_onnx_export["ONNX export<br/>[export_orukeet.py]"]
  node_native_export["Native export"]
end

subgraph group_runtime["Local inference"]
  node_installer["Runtime installer<br/>[install.py]"]
  node_audio["Audio preparation<br/>[audio.py]"]
  node_api["Python recognizer<br/>[model.py]"]
  node_worker["Persistent worker<br/>[worker.py]"]
  node_native_asr["Native recognizer<br/>[nvidia.py]"]
end

node_researcher(("Model developer"))
node_user(("Transcription user"))
node_recording["Audio recording"]
node_transcript["Transcript"]
node_model_host(("Hugging Face"))

node_researcher -->|"audits data"| node_data_audit
node_data_audit -->|"seals data"| node_datasets
node_researcher -.->|"fits kernels"| node_gabor_fit
node_gabor_fit -->|"provides fits"| node_frozen
node_researcher -.->|"trains model"| node_finetune
node_finetune -->|"uses kernels"| node_frozen
node_finetune -.->|"trains on"| node_datasets
node_researcher -.->|"adapts model"| node_regression_train
node_regression_train -->|"uses kernels"| node_frozen
node_researcher -.->|"selects checkpoint"| node_selection
node_coverage -.->|"prepares coverage"| node_datasets
node_researcher -.->|"evaluates models"| node_asr_eval
node_researcher -.->|"runs coverage"| node_unseen_eval
node_unseen_eval -.->|"scores results"| node_metrics
node_unseen_eval -->|"reuses sealed set"| node_coverage
node_researcher -.->|"exports model"| node_onnx_export
node_researcher -.->|"exports model"| node_native_export
node_user -->|"installs runtime"| node_installer
node_model_host -->|"serves weights"| node_installer
node_installer -->|"writes receipt"| node_user
node_user -->|"submits audio"| node_api
node_recording -->|"provides input"| node_api
node_api -.->|"prepares audio"| node_audio
node_api -.->|"uses worker"| node_worker
node_worker -->|"loads and transcribes"| node_native_asr
node_native_asr -->|"returns recognition"| node_transcript
node_api -->|"returns text"| node_transcript

click node_datasets "https://github.com/oruk-ai/orukeet/tree/main/training"
click node_data_audit "https://github.com/oruk-ai/orukeet/blob/main/training/audit_prepare.py"
click node_coverage "https://github.com/oruk-ai/orukeet/blob/main/evaluation/unseen/prepare_coverage.py"
click node_gabor_fit "https://github.com/oruk-ai/orukeet/blob/main/training/gabor_half/fit.py"
click node_frozen "https://github.com/oruk-ai/orukeet/blob/main/training/gabor_half/frozen.py"
click node_finetune "https://github.com/oruk-ai/orukeet/blob/main/training/librispeech_ft/train.py"
click node_regression_train "https://github.com/oruk-ai/orukeet/blob/main/training/regression_ft/train.py"
click node_selection "https://github.com/oruk-ai/orukeet/blob/main/training/selection/seal_confirmation.py"
click node_asr_eval "https://github.com/oruk-ai/orukeet/blob/main/evaluation/standard_asr/run.py"
click node_unseen_eval "https://github.com/oruk-ai/orukeet/blob/main/evaluation/unseen/run.py"
click node_metrics "https://github.com/oruk-ai/orukeet/blob/main/evaluation/unseen/metrics.py"
click node_onnx_export "https://github.com/oruk-ai/orukeet/blob/main/export/onnx/export_orukeet.py"
click node_native_export "https://github.com/oruk-ai/orukeet/blob/main/evaluation/export_oruk_native.py"
click node_installer "https://github.com/oruk-ai/orukeet/blob/main/src/orukeet/install.py"
click node_audio "https://github.com/oruk-ai/orukeet/blob/main/src/orukeet/audio.py"
click node_api "https://github.com/oruk-ai/orukeet/blob/main/src/orukeet/model.py"
click node_worker "https://github.com/oruk-ai/orukeet/blob/main/src/orukeet/worker.py"
click node_native_asr "https://github.com/oruk-ai/orukeet/blob/main/src/orukeet/nvidia.py"

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_datasets,node_data_audit,node_coverage,node_user toneBlue
class node_gabor_fit,node_frozen,node_finetune,node_regression_train,node_selection toneAmber
class node_asr_eval,node_unseen_eval,node_metrics toneMint
class node_onnx_export,node_native_export toneRose
class node_installer,node_audio,node_api,node_worker,node_native_asr,node_researcher,node_recording,node_transcript,node_model_host toneIndigo
```

## Components

### Data and training

- [Prepared speech data](https://github.com/oruk-ai/orukeet/tree/main/training): `training`
- [Dataset audit](https://github.com/oruk-ai/orukeet/blob/main/training/audit_prepare.py): `training/audit_prepare.py`
- [Unseen coverage](https://github.com/oruk-ai/orukeet/blob/main/evaluation/unseen/prepare_coverage.py): `evaluation/unseen/prepare_coverage.py`

### Model development

- [Gabor fitting](https://github.com/oruk-ai/orukeet/blob/main/training/gabor_half/fit.py): `training/gabor_half/fit.py`
- [Frozen Gabor kernels](https://github.com/oruk-ai/orukeet/blob/main/training/gabor_half/frozen.py): `training/gabor_half/frozen.py`
- [Model fine-tuning](https://github.com/oruk-ai/orukeet/blob/main/training/librispeech_ft/train.py): `training/librispeech_ft/train.py`
- [Accent adaptation](https://github.com/oruk-ai/orukeet/blob/main/training/regression_ft/train.py): `training/regression_ft/train.py`
- [Checkpoint selection](https://github.com/oruk-ai/orukeet/blob/main/training/selection/seal_confirmation.py): `training/selection/seal_confirmation.py`

### Evaluation

- [ASR evaluation](https://github.com/oruk-ai/orukeet/blob/main/evaluation/standard_asr/run.py): `evaluation/standard_asr/run.py`
- [Unseen evaluation](https://github.com/oruk-ai/orukeet/blob/main/evaluation/unseen/run.py): `evaluation/unseen/run.py`
- [Scoring metrics](https://github.com/oruk-ai/orukeet/blob/main/evaluation/unseen/metrics.py): `evaluation/unseen/metrics.py`

### Export and release

- [ONNX export](https://github.com/oruk-ai/orukeet/blob/main/export/onnx/export_orukeet.py): `export/onnx/export_orukeet.py`
- [Native export](https://github.com/oruk-ai/orukeet/blob/main/evaluation/export_oruk_native.py): `evaluation/export_oruk_native.py`

### Local inference

- [Runtime installer](https://github.com/oruk-ai/orukeet/blob/main/src/orukeet/install.py): `src/orukeet/install.py`
- [Audio preparation](https://github.com/oruk-ai/orukeet/blob/main/src/orukeet/audio.py): `src/orukeet/audio.py`
- [Python recognizer](https://github.com/oruk-ai/orukeet/blob/main/src/orukeet/model.py): `src/orukeet/model.py`
- [Persistent worker](https://github.com/oruk-ai/orukeet/blob/main/src/orukeet/worker.py): `src/orukeet/worker.py`
- [Native recognizer](https://github.com/oruk-ai/orukeet/blob/main/src/orukeet/nvidia.py): `src/orukeet/nvidia.py`

### Other components

- **Model developer**
- **Transcription user**
- **Audio recording**
- **Transcript**
- **Hugging Face**

## Connections

- Model developer → Dataset audit: audits data (evidence: `training/audit_prepare.py`)
- Dataset audit → Prepared speech data: seals data (evidence: `training/audit_prepare.py`)
- Model developer → Gabor fitting: fits kernels
- Gabor fitting → Frozen Gabor kernels: provides fits (evidence: `training/gabor_half/frozen.py`)
- Model developer → Model fine-tuning: trains model
- Model fine-tuning → Frozen Gabor kernels: uses kernels (evidence: `training/librispeech_ft/train.py`)
- Model fine-tuning → Prepared speech data: trains on (evidence: `training/librispeech_ft/train.py`)
- Model developer → Accent adaptation: adapts model
- Accent adaptation → Frozen Gabor kernels: uses kernels (evidence: `training/regression_ft/train.py`)
- Model developer → Checkpoint selection: selects checkpoint
- Unseen coverage → Prepared speech data: prepares coverage
- Model developer → ASR evaluation: evaluates models
- Model developer → Unseen evaluation: runs coverage
- Unseen evaluation → Scoring metrics: scores results
- Unseen evaluation → Unseen coverage: reuses sealed set
- Model developer → ONNX export: exports model
- Model developer → Native export: exports model
- Transcription user → Runtime installer: installs runtime (evidence: `README.md`)
- Hugging Face → Runtime installer: serves weights (evidence: `README.md`)
- Runtime installer → Transcription user: writes receipt (evidence: `README.md`)
- Transcription user → Python recognizer: submits audio (evidence: `README.md`)
- Audio recording → Python recognizer: provides input (evidence: `README.md`)
- Python recognizer → Audio preparation: prepares audio
- Python recognizer → Persistent worker: uses worker
- Persistent worker → Native recognizer: loads and transcribes (evidence: `src/orukeet/worker.py`)
- Native recognizer → Transcript: returns recognition (evidence: `README.md`)
- Python recognizer → Transcript: returns text (evidence: `README.md`)