# xiaooolong/vev architecture

> Architecture diagram of the GitHub repository xiaooolong/vev, 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/xiaooolong/vev
- Repository: https://github.com/xiaooolong/vev

## Overview

Vev is a self-hosted, Jev-compatible decision model: callers submit text or JSON state, optionally containing images, and receive probabilities over defined answers. The serving path accepts requests, renders state and questions, and scores answer tokens with a checkpoint; it can also be invoked offline through the model engine. The repository additionally contains data preparation, fine-tuning, and benchmark evaluation workflows. Major documented capabilities include image judgments, batched questions, and evaluation of accuracy and calibration. Some data and evaluation subsystems are represented by their enclosing directories because their individual implementations were not sampled.

Main entry points: [`vev/model.py`](https://github.com/xiaooolong/vev/blob/main/vev/model.py) (Checkpoint engine), [`data/build.py`](https://github.com/xiaooolong/vev/blob/main/data/build.py) (Dataset builder), [`train/data.py`](https://github.com/xiaooolong/vev/blob/main/train/data.py) (Training rows), [`vev/serve.py`](https://github.com/xiaooolong/vev/blob/main/vev/serve.py) (HTTP service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_serving["Inference and serving"]
  node_http["HTTP service<br/>[serve.py]"]
  node_state["State parsing<br/>[state.py]"]
  node_readout["Answer readout<br/>[readout.py]"]
  node_checkpoint["Checkpoint engine<br/>[model.py]"]
end

subgraph group_data["Training data"]
  node_converters["Dataset converters"]
  node_source_helpers["Source helpers<br/>[_common.py]"]
  node_builder["Dataset builder<br/>[build.py]"]
  node_augmentation["Record augmentation<br/>[augment.py]"]
  node_splitting["Dataset splitting<br/>[split.py]"]
  node_records[("Build records")]
end

subgraph group_training["Model training"]
  node_training_rows["Training rows<br/>[data.py]"]
  node_trainer["Fine-tuning<br/>[train.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_eval_dataset_helpers["Benchmark converters<br/>[_common.py]"]
  node_eval_datasets["Evaluation datasets"]
  node_eval_runner["Evaluation runner<br/>[run.py]"]
  node_eval_client["Evaluation client<br/>[client.py]"]
  node_metrics["Metrics<br/>[metrics.py]"]
end

node_caller(("API caller"))
node_weights[("Model weights")]
node_offline(("Offline caller"))
node_external_service(("Decision service"))

node_caller -->|"sends request"| node_http
node_http -->|"parses state"| node_state
node_http -->|"scores request"| node_checkpoint
node_checkpoint -->|"renders state"| node_state
node_checkpoint -->|"uses readout"| node_readout
node_readout -->|"uses segments"| node_state
node_checkpoint -.->|"loads checkpoint"| node_weights
node_offline -->|"runs inference"| node_checkpoint
node_converters -->|"uses helpers"| node_source_helpers
node_source_helpers -->|"imports helpers"| node_eval_dataset_helpers
node_source_helpers -.->|"feeds build"| node_builder
node_builder -->|"imports augmentation"| node_augmentation
node_builder -->|"imports splitting"| node_splitting
node_builder -.->|"writes records"| node_records
node_training_rows -->|"reads build data"| node_records
node_training_rows -->|"applies augmentation"| node_augmentation
node_training_rows -->|"renders rows"| node_checkpoint
node_trainer -->|"loads rows"| node_training_rows
node_trainer -->|"trains model"| node_checkpoint
node_eval_datasets -->|"uses helpers"| node_eval_dataset_helpers
node_caller -->|"runs evaluation"| node_eval_runner
node_eval_runner -->|"uses client"| node_eval_client
node_eval_runner -->|"computes metrics"| node_metrics
node_eval_client -->|"posts requests"| node_external_service

click node_http "https://github.com/xiaooolong/vev/blob/main/vev/serve.py"
click node_state "https://github.com/xiaooolong/vev/blob/main/vev/state.py"
click node_readout "https://github.com/xiaooolong/vev/blob/main/vev/readout.py"
click node_checkpoint "https://github.com/xiaooolong/vev/blob/main/vev/model.py"
click node_converters "https://github.com/xiaooolong/vev/tree/main/data/sources"
click node_source_helpers "https://github.com/xiaooolong/vev/blob/main/data/sources/_common.py"
click node_eval_dataset_helpers "https://github.com/xiaooolong/vev/blob/main/evals/datasets/_common.py"
click node_builder "https://github.com/xiaooolong/vev/blob/main/data/build.py"
click node_augmentation "https://github.com/xiaooolong/vev/blob/main/data/augment.py"
click node_splitting "https://github.com/xiaooolong/vev/blob/main/data/split.py"
click node_records "https://github.com/xiaooolong/vev/tree/main/data"
click node_training_rows "https://github.com/xiaooolong/vev/blob/main/train/data.py"
click node_trainer "https://github.com/xiaooolong/vev/blob/main/train/train.py"
click node_eval_datasets "https://github.com/xiaooolong/vev/tree/main/evals/datasets"
click node_eval_runner "https://github.com/xiaooolong/vev/blob/main/evals/run.py"
click node_eval_client "https://github.com/xiaooolong/vev/blob/main/evals/client.py"
click node_metrics "https://github.com/xiaooolong/vev/blob/main/evals/metrics.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_http,node_state,node_readout,node_checkpoint toneBlue
class node_converters,node_source_helpers,node_builder,node_augmentation,node_splitting,node_records,node_weights toneAmber
class node_training_rows,node_trainer,node_caller toneMint
class node_eval_dataset_helpers,node_eval_datasets,node_eval_runner,node_eval_client,node_metrics toneRose
class node_offline,node_external_service toneIndigo
```

## Components

### Inference and serving

- [HTTP service](https://github.com/xiaooolong/vev/blob/main/vev/serve.py): `vev/serve.py`
- [State parsing](https://github.com/xiaooolong/vev/blob/main/vev/state.py): `vev/state.py`
- [Answer readout](https://github.com/xiaooolong/vev/blob/main/vev/readout.py): `vev/readout.py`
- [Checkpoint engine](https://github.com/xiaooolong/vev/blob/main/vev/model.py): `vev/model.py`

### Training data

- [Dataset converters](https://github.com/xiaooolong/vev/tree/main/data/sources): `data/sources`
- [Source helpers](https://github.com/xiaooolong/vev/blob/main/data/sources/_common.py): `data/sources/_common.py`
- [Dataset builder](https://github.com/xiaooolong/vev/blob/main/data/build.py): `data/build.py`
- [Record augmentation](https://github.com/xiaooolong/vev/blob/main/data/augment.py): `data/augment.py`
- [Dataset splitting](https://github.com/xiaooolong/vev/blob/main/data/split.py): `data/split.py`
- [Build records](https://github.com/xiaooolong/vev/tree/main/data): `data`

### Model training

- [Training rows](https://github.com/xiaooolong/vev/blob/main/train/data.py): `train/data.py`
- [Fine-tuning](https://github.com/xiaooolong/vev/blob/main/train/train.py): `train/train.py`

### Evaluation

- [Benchmark converters](https://github.com/xiaooolong/vev/blob/main/evals/datasets/_common.py): `evals/datasets/_common.py`
- [Evaluation datasets](https://github.com/xiaooolong/vev/tree/main/evals/datasets): `evals/datasets`
- [Evaluation runner](https://github.com/xiaooolong/vev/blob/main/evals/run.py): `evals/run.py`
- [Evaluation client](https://github.com/xiaooolong/vev/blob/main/evals/client.py): `evals/client.py`
- [Metrics](https://github.com/xiaooolong/vev/blob/main/evals/metrics.py): `evals/metrics.py`

### Other components

- **API caller**
- **Model weights**
- **Offline caller**
- **Decision service**

## Connections

- API caller → HTTP service: sends request (evidence: `README.md`)
- HTTP service → State parsing: parses state (evidence: `vev/serve.py`)
- HTTP service → Checkpoint engine: scores request (evidence: `vev/serve.py`)
- Checkpoint engine → State parsing: renders state (evidence: `vev/model.py`)
- Checkpoint engine → Answer readout: uses readout (evidence: `vev/model.py`)
- Answer readout → State parsing: uses segments (evidence: `vev/readout.py`)
- Checkpoint engine → Model weights: loads checkpoint
- Offline caller → Checkpoint engine: runs inference (evidence: `README.md`)
- Dataset converters → Source helpers: uses helpers (evidence: `data/sources/text_amazon_reviews_multi_en.py`)
- Source helpers → Benchmark converters: imports helpers (evidence: `data/sources/_common.py`)
- Source helpers → Dataset builder: feeds build
- Dataset builder → Record augmentation: imports augmentation (evidence: `data/build.py`)
- Dataset builder → Dataset splitting: imports splitting (evidence: `data/build.py`)
- Dataset builder → Build records: writes records (evidence: `data/build.py`)
- Training rows → Build records: reads build data (evidence: `train/data.py`)
- Training rows → Record augmentation: applies augmentation (evidence: `train/data.py`)
- Training rows → Checkpoint engine: renders rows (evidence: `train/data.py`)
- Fine-tuning → Training rows: loads rows (evidence: `train/train.py`)
- Fine-tuning → Checkpoint engine: trains model (evidence: `train/train.py`)
- Evaluation datasets → Benchmark converters: uses helpers (evidence: `evals/datasets/image_policy_mod.py`)
- API caller → Evaluation runner: runs evaluation (evidence: `README.md`)
- Evaluation runner → Evaluation client: uses client (evidence: `evals/run.py`)
- Evaluation runner → Metrics: computes metrics (evidence: `evals/run.py`)
- Evaluation client → Decision service: posts requests (evidence: `evals/client.py`)
