# tianyucodings/jevharness architecture

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

## Overview

JevHarness is a framework for authoring task-specific Jev decision harnesses, executing them against task observations, and optionally improving them from rewards and complete traces. The primary flow is task data and observations → validated pipeline execution and Jev judgments → task evaluation and recorded traces; optional GEPA reflection proposes and evaluates revisions, and selected pipelines can be frozen for repeatable execution. The README also documents crypto spot backtesting and paper execution. Edges use README or SOURCE INDEX evidence; unsampled subsystems are included where documented, without guessing their internal calls.

Main entry points: [`auto_jev/runtime.py`](https://github.com/tianyucodings/jevharness/blob/main/auto_jev/runtime.py) (Pipeline runtime), [`auto_jev/evolution.py`](https://github.com/tianyucodings/jevharness/blob/main/auto_jev/evolution.py) (GEPA evolution), [`auto_jev/spec.py`](https://github.com/tianyucodings/jevharness/blob/main/auto_jev/spec.py) (Pipeline specification), [`auto_jev/storage.py`](https://github.com/tianyucodings/jevharness/blob/main/auto_jev/storage.py) (Run storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Authoring and evolution"]
  node_evolution["GEPA evolution<br/>[evolution.py]"]
  node_reflection["Trace reflection<br/>[reflection.py]"]
  node_tracecodec["Trace codec<br/>[trace_codec.py]"]
end

subgraph group_execution["Harness execution"]
  node_harness["Pipeline specification<br/>[spec.py]"]
  node_expressions["Expression interpreter<br/>[spec.py]"]
  node_flow["Flow scheduler<br/>[flow.py]"]
  node_python["Sandboxed Python nodes<br/>[python_nodes.py]"]
  node_runtime["Pipeline runtime<br/>[runtime.py]"]
  node_providers["Jev transports<br/>[providers.py]"]
  node_gateway["Vercel gateway<br/>[vercel.py]"]
end

subgraph group_research["Data and evaluation"]
  node_crypto["Spot backtester<br/>[crypto.py]"]
  node_observations["Observation builder<br/>[observations.py]"]
  node_data["Market and news data<br/>[data.py]"]
  node_datasets["Dataset management<br/>[datasets.py]"]
  node_experiment["Experiment runner<br/>[experiment.py]"]
  node_paper["Paper execution<br/>[paper.py]"]
end

subgraph group_operations["Persistence and serving"]
  node_frozen["Frozen artifacts<br/>[frozen.py]"]
  node_storage[("Run storage<br/>[storage.py]")]
  node_cli["Command line<br/>[cli.py]"]
  node_server["Run server<br/>[server.py]"]
end

subgraph group_presentation["Inspection and deployment"]
  node_viewer["Archive viewer<br/>[router.mjs]"]
end

node_author(("Authoring LLM"))
node_task["Task adapter"]
node_jev(("Jev service"))
node_environment(("Task environment"))
node_exchange(("Market data services"))

node_author -->|"authors"| node_harness
node_task -->|"provides observations"| node_runtime
node_runtime -->|"returns actions"| node_task
node_task -->|"applies actions"| node_environment
node_environment -.->|"provides rewards"| node_evolution
node_environment -.->|"provides traces"| node_reflection
node_harness -->|"defines expressions"| node_expressions
node_harness -->|"compiles flow"| node_flow
node_harness -->|"validates nodes"| node_python
node_runtime -->|"validates spec"| node_harness
node_runtime -->|"schedules nodes"| node_flow
node_runtime -->|"executes nodes"| node_python
node_runtime -.->|"requests judgments"| node_providers
node_providers -.->|"sends requests"| node_jev
node_providers -->|"uses transport"| node_gateway
node_gateway -->|"calls gateway"| node_jev
node_evolution -->|"evaluates candidates"| node_runtime
node_evolution -->|"requests proposals"| node_reflection
node_reflection -->|"uses provider"| node_providers
node_reflection -->|"encodes traces"| node_tracecodec
node_evolution -->|"records search"| node_storage
node_crypto -->|"runs pipeline"| node_runtime
node_crypto -->|"builds inputs"| node_observations
node_data -->|"fetches market data"| node_exchange
node_experiment -->|"runs search"| node_evolution
node_experiment -->|"records runs"| node_storage
node_datasets -->|"uses data fetchers"| node_data
node_datasets -->|"stores datasets"| node_storage
node_paper -->|"fetches inputs"| node_data
node_paper -->|"uses backtest logic"| node_crypto
node_paper -.->|"executes decisions"| node_runtime
node_frozen -->|"validates specification"| node_harness
node_frozen -->|"binds contract"| node_observations
node_cli -->|"starts experiments"| node_experiment
node_cli -->|"starts evolution"| node_evolution
node_cli -.->|"manages datasets"| node_datasets
node_cli -->|"freezes pipelines"| node_frozen
node_cli -->|"reads and writes"| node_storage
node_server -->|"serves run data"| node_storage
node_viewer -.->|"reads archives"| node_storage

click node_harness "https://github.com/tianyucodings/jevharness/blob/main/auto_jev/spec.py"
click node_expressions "https://github.com/tianyucodings/jevharness/blob/main/auto_jev/spec.py"
click node_flow "https://github.com/tianyucodings/jevharness/blob/main/auto_jev/flow.py"
click node_python "https://github.com/tianyucodings/jevharness/blob/main/auto_jev/python_nodes.py"
click node_runtime "https://github.com/tianyucodings/jevharness/blob/main/auto_jev/runtime.py"
click node_providers "https://github.com/tianyucodings/jevharness/blob/main/auto_jev/providers.py"
click node_gateway "https://github.com/tianyucodings/jevharness/blob/main/auto_jev/vercel.py"
click node_evolution "https://github.com/tianyucodings/jevharness/blob/main/auto_jev/evolution.py"
click node_reflection "https://github.com/tianyucodings/jevharness/blob/main/auto_jev/reflection.py"
click node_tracecodec "https://github.com/tianyucodings/jevharness/blob/main/auto_jev/trace_codec.py"
click node_crypto "https://github.com/tianyucodings/jevharness/blob/main/auto_jev/crypto.py"
click node_observations "https://github.com/tianyucodings/jevharness/blob/main/auto_jev/observations.py"
click node_data "https://github.com/tianyucodings/jevharness/blob/main/auto_jev/data.py"
click node_datasets "https://github.com/tianyucodings/jevharness/blob/main/auto_jev/datasets.py"
click node_experiment "https://github.com/tianyucodings/jevharness/blob/main/auto_jev/experiment.py"
click node_paper "https://github.com/tianyucodings/jevharness/blob/main/auto_jev/paper.py"
click node_frozen "https://github.com/tianyucodings/jevharness/blob/main/auto_jev/frozen.py"
click node_storage "https://github.com/tianyucodings/jevharness/blob/main/auto_jev/storage.py"
click node_cli "https://github.com/tianyucodings/jevharness/blob/main/auto_jev/cli.py"
click node_server "https://github.com/tianyucodings/jevharness/blob/main/auto_jev/server.py"
click node_viewer "https://github.com/tianyucodings/jevharness/blob/main/website/worker/router.mjs"

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_evolution,node_reflection,node_tracecodec toneBlue
class node_harness,node_expressions,node_flow,node_python,node_runtime,node_providers,node_gateway toneAmber
class node_crypto,node_observations,node_data,node_datasets,node_experiment,node_paper toneMint
class node_frozen,node_storage,node_cli,node_server,node_task,node_environment toneRose
class node_viewer,node_author,node_jev,node_exchange toneIndigo
```

## Components

### Authoring and evolution

- [GEPA evolution](https://github.com/tianyucodings/jevharness/blob/main/auto_jev/evolution.py): `auto_jev/evolution.py`
- [Trace reflection](https://github.com/tianyucodings/jevharness/blob/main/auto_jev/reflection.py): `auto_jev/reflection.py`
- [Trace codec](https://github.com/tianyucodings/jevharness/blob/main/auto_jev/trace_codec.py): `auto_jev/trace_codec.py`

### Harness execution

- [Pipeline specification](https://github.com/tianyucodings/jevharness/blob/main/auto_jev/spec.py): `auto_jev/spec.py`
- [Expression interpreter](https://github.com/tianyucodings/jevharness/blob/main/auto_jev/spec.py): `auto_jev/spec.py`
- [Flow scheduler](https://github.com/tianyucodings/jevharness/blob/main/auto_jev/flow.py): `auto_jev/flow.py`
- [Sandboxed Python nodes](https://github.com/tianyucodings/jevharness/blob/main/auto_jev/python_nodes.py): `auto_jev/python_nodes.py`
- [Pipeline runtime](https://github.com/tianyucodings/jevharness/blob/main/auto_jev/runtime.py): `auto_jev/runtime.py`
- [Jev transports](https://github.com/tianyucodings/jevharness/blob/main/auto_jev/providers.py): `auto_jev/providers.py`
- [Vercel gateway](https://github.com/tianyucodings/jevharness/blob/main/auto_jev/vercel.py): `auto_jev/vercel.py`

### Data and evaluation

- [Spot backtester](https://github.com/tianyucodings/jevharness/blob/main/auto_jev/crypto.py): `auto_jev/crypto.py`
- [Observation builder](https://github.com/tianyucodings/jevharness/blob/main/auto_jev/observations.py): `auto_jev/observations.py`
- [Market and news data](https://github.com/tianyucodings/jevharness/blob/main/auto_jev/data.py): `auto_jev/data.py`
- [Dataset management](https://github.com/tianyucodings/jevharness/blob/main/auto_jev/datasets.py): `auto_jev/datasets.py`
- [Experiment runner](https://github.com/tianyucodings/jevharness/blob/main/auto_jev/experiment.py): `auto_jev/experiment.py`
- [Paper execution](https://github.com/tianyucodings/jevharness/blob/main/auto_jev/paper.py): `auto_jev/paper.py`

### Persistence and serving

- [Frozen artifacts](https://github.com/tianyucodings/jevharness/blob/main/auto_jev/frozen.py): `auto_jev/frozen.py`
- [Run storage](https://github.com/tianyucodings/jevharness/blob/main/auto_jev/storage.py): `auto_jev/storage.py`
- [Command line](https://github.com/tianyucodings/jevharness/blob/main/auto_jev/cli.py): `auto_jev/cli.py`
- [Run server](https://github.com/tianyucodings/jevharness/blob/main/auto_jev/server.py): `auto_jev/server.py`

### Inspection and deployment

- [Archive viewer](https://github.com/tianyucodings/jevharness/blob/main/website/worker/router.mjs): `website/worker/router.mjs`

### Other components

- **Authoring LLM**
- **Task adapter**
- **Jev service**
- **Task environment**
- **Market data services**

## Connections

- Authoring LLM → Pipeline specification: authors (evidence: `README.md`)
- Task adapter → Pipeline runtime: provides observations (evidence: `README.md`)
- Pipeline runtime → Task adapter: returns actions (evidence: `README.md`)
- Task adapter → Task environment: applies actions (evidence: `README.md`)
- Task environment → GEPA evolution: provides rewards (evidence: `README.md`)
- Task environment → Trace reflection: provides traces (evidence: `README.md`)
- Pipeline specification → Expression interpreter: defines expressions (evidence: `auto_jev/spec.py`)
- Pipeline specification → Flow scheduler: compiles flow (evidence: `auto_jev/spec.py`)
- Pipeline specification → Sandboxed Python nodes: validates nodes (evidence: `auto_jev/spec.py`)
- Pipeline runtime → Pipeline specification: validates spec (evidence: `auto_jev/runtime.py`)
- Pipeline runtime → Flow scheduler: schedules nodes (evidence: `auto_jev/runtime.py`)
- Pipeline runtime → Sandboxed Python nodes: executes nodes (evidence: `auto_jev/runtime.py`)
- Pipeline runtime → Jev transports: requests judgments
- Jev transports → Jev service: sends requests (evidence: `auto_jev/providers.py`)
- Jev transports → Vercel gateway: uses transport (evidence: `auto_jev/providers.py`)
- Vercel gateway → Jev service: calls gateway (evidence: `auto_jev/vercel.py`)
- GEPA evolution → Pipeline runtime: evaluates candidates (evidence: `auto_jev/evolution.py`)
- GEPA evolution → Trace reflection: requests proposals (evidence: `auto_jev/evolution.py`)
- Trace reflection → Jev transports: uses provider (evidence: `auto_jev/reflection.py`)
- Trace reflection → Trace codec: encodes traces (evidence: `auto_jev/reflection.py`)
- GEPA evolution → Run storage: records search (evidence: `auto_jev/evolution.py`)
- Spot backtester → Pipeline runtime: runs pipeline (evidence: `auto_jev/crypto.py`)
- Spot backtester → Observation builder: builds inputs (evidence: `auto_jev/crypto.py`)
- Market and news data → Market data services: fetches market data (evidence: `auto_jev/data.py`)
- Experiment runner → GEPA evolution: runs search (evidence: `auto_jev/experiment.py`)
- Experiment runner → Run storage: records runs (evidence: `auto_jev/experiment.py`)
- Dataset management → Market and news data: uses data fetchers (evidence: `auto_jev/datasets.py`)
- Dataset management → Run storage: stores datasets (evidence: `auto_jev/datasets.py`)
- Paper execution → Market and news data: fetches inputs (evidence: `auto_jev/paper.py`)
- Paper execution → Spot backtester: uses backtest logic (evidence: `auto_jev/paper.py`)
- Paper execution → Pipeline runtime: executes decisions (evidence: `auto_jev/paper.py`)
- Frozen artifacts → Pipeline specification: validates specification (evidence: `auto_jev/frozen.py`)
- Frozen artifacts → Observation builder: binds contract (evidence: `auto_jev/frozen.py`)
- Command line → Experiment runner: starts experiments (evidence: `auto_jev/cli.py`)
- Command line → GEPA evolution: starts evolution (evidence: `auto_jev/cli.py`)
- Command line → Dataset management: manages datasets
- Command line → Frozen artifacts: freezes pipelines (evidence: `auto_jev/cli.py`)
- Command line → Run storage: reads and writes (evidence: `auto_jev/cli.py`)
- Run server → Run storage: serves run data (evidence: `auto_jev/server.py`)
- Archive viewer → Run storage: reads archives