# dhnihaoya/evspark architecture

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

- Interactive diagram: https://gitdiagram.com/dhnihaoya/evspark
- Repository: https://github.com/dhnihaoya/evspark

## Overview

EvSpark is a Python library and research workflow for lossless speculative DNA generation with Evo2. The main user path validates a DNA prompt, loads an Evo2 target and drafter checkpoint, drafts token blocks, verifies them against target probabilities, and returns generated sequence and metrics; README documents greedy identity with native decoding. Supporting branches cover drafter-data preparation and distillation, plus a regulatory-DNA design workflow. State-slice rollback supports hybrid-model verification. Some subsystem links rely on the README or SOURCE INDEX references; unsampled implementation details are not inferred.

Main entry points: [`scripts/regulatory_design/run.py`](https://github.com/dhnihaoya/evspark/blob/main/scripts/regulatory_design/run.py) (Design runner), [`evspark/api.py`](https://github.com/dhnihaoya/evspark/blob/main/evspark/api.py) (Public API), [`evspark/specdec/block/loop.py`](https://github.com/dhnihaoya/evspark/blob/main/evspark/specdec/block/loop.py) (Speculative loop), [`evspark/train/data.py`](https://github.com/dhnihaoya/evspark/blob/main/evspark/train/data.py) (Training windows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Generation runtime"]
  node_api["Public API<br/>[api.py]"]
  node_checkpoint["Checkpoint resolver<br/>[checkpoints.py]"]
  node_loop["Speculative loop<br/>[loop.py]"]
  node_draft["Neural drafter adapter<br/>[neural_draft.py]"]
  node_verify["Block verifier<br/>[verifier.py]"]
  node_driver["Block forward driver<br/>[driver.py]"]
  node_state["State slice rollback<br/>[slice.py]"]
  node_result["Generated sequence<br/>[api.py]"]
end

subgraph group_drafting["Drafting methods"]
  node_markov["Markov drafting<br/>[markov.py]"]
  node_lookup["Prompt lookup<br/>[lookup.py]"]
end

subgraph group_training["Drafter training"]
  node_drafter_model["Distilled drafter model<br/>[drafter.py]"]
  node_genome["Genome parsing<br/>[genome.py]"]
  node_data["Training windows<br/>[data.py]"]
  node_corpora["Training corpora<br/>[corpora.py]"]
  node_distill["Online distillation<br/>[distill.py]"]
end

subgraph group_design["Regulatory design"]
  node_prepare["Design preparation<br/>[prepare.py]"]
  node_protocol["Design protocol<br/>[protocol.py]"]
  node_design_run["Design runner<br/>[run.py]"]
  node_generation["Sequence generation<br/>[generation.py]"]
  node_scoring["Candidate scoring<br/>[scoring.py]"]
  node_report["Design reporting<br/>[report.py]"]
end

node_caller(("Library user"))
node_hub["Model checkpoint hubs"]
node_target["Evo2 target"]

node_caller -->|"calls"| node_api
node_api -->|"resolves checkpoint"| node_checkpoint
node_checkpoint -->|"downloads from"| node_hub
node_api -->|"loads Evo2"| node_target
node_api -->|"loads drafter"| node_draft
node_api -->|"starts generation"| node_loop
node_loop -->|"requests proposals"| node_draft
node_loop -->|"verifies target block"| node_driver
node_loop -->|"checks proposals"| node_verify
node_driver -.->|"runs block forward"| node_target
node_driver -->|"uses state slices"| node_state
node_draft -->|"adapts model"| node_drafter_model
node_loop -->|"returns tokens"| node_result
node_caller -.->|"can use"| node_markov
node_caller -.->|"can use"| node_lookup
node_corpora -->|"uses loaders"| node_data
node_data -->|"cleans sequences"| node_genome
node_data -->|"uses transitions"| node_markov
node_distill -->|"consumes windows"| node_data
node_distill -->|"trains drafter"| node_drafter_model
node_distill -->|"evaluates baseline"| node_markov
node_caller -->|"runs design workflow"| node_design_run
node_design_run -->|"calls preparation"| node_prepare
node_design_run -->|"uses protocol"| node_protocol
node_design_run -->|"calls generation"| node_generation
node_design_run -->|"calls scoring"| node_scoring
node_report -->|"reports results"| node_design_run
node_report -->|"uses protocol"| node_protocol

click node_api "https://github.com/dhnihaoya/evspark/blob/main/evspark/api.py"
click node_checkpoint "https://github.com/dhnihaoya/evspark/blob/main/evspark/checkpoints.py"
click node_loop "https://github.com/dhnihaoya/evspark/blob/main/evspark/specdec/block/loop.py"
click node_draft "https://github.com/dhnihaoya/evspark/blob/main/evspark/specdec/block/neural_draft.py"
click node_drafter_model "https://github.com/dhnihaoya/evspark/blob/main/evspark/train/drafter.py"
click node_verify "https://github.com/dhnihaoya/evspark/blob/main/evspark/specdec/verifier.py"
click node_driver "https://github.com/dhnihaoya/evspark/blob/main/evspark/specdec/block/driver.py"
click node_state "https://github.com/dhnihaoya/evspark/blob/main/evspark/specdec/block/slice.py"
click node_result "https://github.com/dhnihaoya/evspark/blob/main/evspark/api.py"
click node_markov "https://github.com/dhnihaoya/evspark/blob/main/evspark/specdec/markov.py"
click node_lookup "https://github.com/dhnihaoya/evspark/blob/main/evspark/specdec/lookup.py"
click node_genome "https://github.com/dhnihaoya/evspark/blob/main/evspark/specdec/genome.py"
click node_data "https://github.com/dhnihaoya/evspark/blob/main/evspark/train/data.py"
click node_corpora "https://github.com/dhnihaoya/evspark/blob/main/evspark/train/corpora.py"
click node_distill "https://github.com/dhnihaoya/evspark/blob/main/evspark/train/distill.py"
click node_prepare "https://github.com/dhnihaoya/evspark/blob/main/scripts/regulatory_design/prepare.py"
click node_protocol "https://github.com/dhnihaoya/evspark/blob/main/scripts/regulatory_design/protocol.py"
click node_design_run "https://github.com/dhnihaoya/evspark/blob/main/scripts/regulatory_design/run.py"
click node_generation "https://github.com/dhnihaoya/evspark/blob/main/scripts/regulatory_design/generation.py"
click node_scoring "https://github.com/dhnihaoya/evspark/blob/main/scripts/regulatory_design/scoring.py"
click node_report "https://github.com/dhnihaoya/evspark/blob/main/scripts/regulatory_design/report.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_api,node_checkpoint,node_loop,node_draft,node_verify,node_driver,node_state,node_result,node_caller toneBlue
class node_markov,node_lookup toneAmber
class node_drafter_model,node_genome,node_data,node_corpora,node_distill toneMint
class node_prepare,node_protocol,node_design_run,node_generation,node_scoring,node_report toneRose
class node_hub,node_target toneIndigo
```

## Components

### Generation runtime

- [Public API](https://github.com/dhnihaoya/evspark/blob/main/evspark/api.py): `evspark/api.py`
- [Checkpoint resolver](https://github.com/dhnihaoya/evspark/blob/main/evspark/checkpoints.py): `evspark/checkpoints.py`
- [Speculative loop](https://github.com/dhnihaoya/evspark/blob/main/evspark/specdec/block/loop.py): `evspark/specdec/block/loop.py`
- [Neural drafter adapter](https://github.com/dhnihaoya/evspark/blob/main/evspark/specdec/block/neural_draft.py): `evspark/specdec/block/neural_draft.py`
- [Block verifier](https://github.com/dhnihaoya/evspark/blob/main/evspark/specdec/verifier.py): `evspark/specdec/verifier.py`
- [Block forward driver](https://github.com/dhnihaoya/evspark/blob/main/evspark/specdec/block/driver.py): `evspark/specdec/block/driver.py`
- [State slice rollback](https://github.com/dhnihaoya/evspark/blob/main/evspark/specdec/block/slice.py): `evspark/specdec/block/slice.py`
- [Generated sequence](https://github.com/dhnihaoya/evspark/blob/main/evspark/api.py): `evspark/api.py`

### Drafting methods

- [Markov drafting](https://github.com/dhnihaoya/evspark/blob/main/evspark/specdec/markov.py): `evspark/specdec/markov.py`
- [Prompt lookup](https://github.com/dhnihaoya/evspark/blob/main/evspark/specdec/lookup.py): `evspark/specdec/lookup.py`

### Drafter training

- [Distilled drafter model](https://github.com/dhnihaoya/evspark/blob/main/evspark/train/drafter.py): `evspark/train/drafter.py`
- [Genome parsing](https://github.com/dhnihaoya/evspark/blob/main/evspark/specdec/genome.py): `evspark/specdec/genome.py`
- [Training windows](https://github.com/dhnihaoya/evspark/blob/main/evspark/train/data.py): `evspark/train/data.py`
- [Training corpora](https://github.com/dhnihaoya/evspark/blob/main/evspark/train/corpora.py): `evspark/train/corpora.py`
- [Online distillation](https://github.com/dhnihaoya/evspark/blob/main/evspark/train/distill.py): `evspark/train/distill.py`

### Regulatory design

- [Design preparation](https://github.com/dhnihaoya/evspark/blob/main/scripts/regulatory_design/prepare.py): `scripts/regulatory_design/prepare.py`
- [Design protocol](https://github.com/dhnihaoya/evspark/blob/main/scripts/regulatory_design/protocol.py): `scripts/regulatory_design/protocol.py`
- [Design runner](https://github.com/dhnihaoya/evspark/blob/main/scripts/regulatory_design/run.py): `scripts/regulatory_design/run.py`
- [Sequence generation](https://github.com/dhnihaoya/evspark/blob/main/scripts/regulatory_design/generation.py): `scripts/regulatory_design/generation.py`
- [Candidate scoring](https://github.com/dhnihaoya/evspark/blob/main/scripts/regulatory_design/scoring.py): `scripts/regulatory_design/scoring.py`
- [Design reporting](https://github.com/dhnihaoya/evspark/blob/main/scripts/regulatory_design/report.py): `scripts/regulatory_design/report.py`

### Other components

- **Library user**
- **Model checkpoint hubs**
- **Evo2 target**

## Connections

- Library user → Public API: calls
- Public API → Checkpoint resolver: resolves checkpoint (evidence: `evspark/api.py`)
- Checkpoint resolver → Model checkpoint hubs: downloads from (evidence: `evspark/checkpoints.py`)
- Public API → Evo2 target: loads Evo2 (evidence: `evspark/api.py`)
- Public API → Neural drafter adapter: loads drafter (evidence: `evspark/api.py`)
- Public API → Speculative loop: starts generation (evidence: `evspark/api.py`)
- Speculative loop → Neural drafter adapter: requests proposals (evidence: `evspark/specdec/block/loop.py`)
- Speculative loop → Block forward driver: verifies target block (evidence: `evspark/specdec/block/loop.py`)
- Speculative loop → Block verifier: checks proposals (evidence: `evspark/specdec/block/loop.py`)
- Block forward driver → Evo2 target: runs block forward
- Block forward driver → State slice rollback: uses state slices (evidence: `evspark/specdec/block/driver.py`)
- Neural drafter adapter → Distilled drafter model: adapts model (evidence: `evspark/specdec/block/neural_draft.py`)
- Speculative loop → Generated sequence: returns tokens (evidence: `evspark/api.py`)
- Library user → Markov drafting: can use
- Library user → Prompt lookup: can use
- Training corpora → Training windows: uses loaders (evidence: `evspark/train/corpora.py`)
- Training windows → Genome parsing: cleans sequences (evidence: `evspark/train/data.py`)
- Training windows → Markov drafting: uses transitions (evidence: `evspark/train/data.py`)
- Online distillation → Training windows: consumes windows (evidence: `evspark/train/distill.py`)
- Online distillation → Distilled drafter model: trains drafter (evidence: `evspark/train/distill.py`)
- Online distillation → Markov drafting: evaluates baseline (evidence: `evspark/train/distill.py`)
- Library user → Design runner: runs design workflow
- Design runner → Design preparation: calls preparation (evidence: `scripts/regulatory_design/run.py`)
- Design runner → Design protocol: uses protocol (evidence: `scripts/regulatory_design/run.py`)
- Design runner → Sequence generation: calls generation (evidence: `scripts/regulatory_design/run.py`)
- Design runner → Candidate scoring: calls scoring (evidence: `scripts/regulatory_design/run.py`)
- Design reporting → Design runner: reports results (evidence: `scripts/regulatory_design/report.py`)
- Design reporting → Design protocol: uses protocol (evidence: `scripts/regulatory_design/report.py`)
