# gpt-agi/openjev architecture

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

- Interactive diagram: https://gitdiagram.com/gpt-agi/openjev
- Repository: https://github.com/gpt-agi/openjev

## Overview

OpenJev is a Python System One decision engine with a terminal REPL: a user supplies state and typed questions, selects a backend, and receives label probabilities, typed answers, confidence, and latency. The supported runtime path is REPL/CLI → shared decision orchestration → backend scoring → typed answer construction → REPL rendering. The README also documents SDK-compatible request/response schemas and live experiments against the official Jev API; no serving implementation appears in the supplied tree. Edges reflect excerpted calls or README claims; unsampled capabilities are not linked to guessed implementations.

Main entry points: [`src/openjev/cli/main.py`](https://github.com/gpt-agi/openjev/blob/main/src/openjev/cli/main.py) (REPL and CLI), [`src/openjev/backends/base.py`](https://github.com/gpt-agi/openjev/blob/main/src/openjev/backends/base.py) (Decision orchestrator), [`src/openjev/backends/__init__.py`](https://github.com/gpt-agi/openjev/blob/main/src/openjev/backends/__init__.py) (Backend selection), [`scripts/experiments.py`](https://github.com/gpt-agi/openjev/blob/main/scripts/experiments.py) (Live experiment harness)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Terminal interface"]
  node_repl["REPL and CLI<br/>[main.py]"]
  node_renderer["Result renderer<br/>[render.py]"]
end

subgraph group_decision["Decision core"]
  node_primitives["Typed schemas<br/>[primitives.py]"]
  node_orchestrator["Decision orchestrator<br/>[base.py]"]
end

subgraph group_backends["Scoring backends"]
  node_hf["Transformers backend<br/>[hf.py]"]
  node_mock["Mock backend<br/>[mock.py]"]
  node_registry["Backend selection<br/>[__init__.py]"]
end

subgraph group_research["Reference experiments"]
  node_experiments["Live experiment harness<br/>[experiments.py]"]
  node_charts["Experiment charts<br/>[experiments.py]"]
end

node_user(("Developer"))
node_model["Hugging Face model"]
node_reference_api["Official Jev API"]
node_answers["Typed decisions"]

node_user -->|"enters requests"| node_repl
node_repl -->|"builds requests"| node_primitives
node_repl -->|"selects backend"| node_registry
node_repl -->|"submits request"| node_orchestrator
node_orchestrator -->|"builds answers"| node_primitives
node_orchestrator -->|"scores labels"| node_hf
node_orchestrator -->|"scores labels"| node_mock
node_hf -->|"reads logits"| node_model
node_registry -->|"creates backend"| node_hf
node_registry -->|"creates backend"| node_mock
node_repl -->|"renders response"| node_renderer
node_renderer -->|"displays probabilities"| node_answers
node_user -->|"runs experiments"| node_experiments
node_experiments -->|"requests decisions"| node_reference_api
node_experiments -->|"produces charts"| node_charts

click node_repl "https://github.com/gpt-agi/openjev/blob/main/src/openjev/cli/main.py"
click node_renderer "https://github.com/gpt-agi/openjev/blob/main/src/openjev/cli/render.py"
click node_primitives "https://github.com/gpt-agi/openjev/blob/main/src/openjev/core/primitives.py"
click node_orchestrator "https://github.com/gpt-agi/openjev/blob/main/src/openjev/backends/base.py"
click node_hf "https://github.com/gpt-agi/openjev/blob/main/src/openjev/backends/hf.py"
click node_mock "https://github.com/gpt-agi/openjev/blob/main/src/openjev/backends/mock.py"
click node_registry "https://github.com/gpt-agi/openjev/blob/main/src/openjev/backends/__init__.py"
click node_experiments "https://github.com/gpt-agi/openjev/blob/main/scripts/experiments.py"
click node_charts "https://github.com/gpt-agi/openjev/blob/main/scripts/experiments.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_repl,node_renderer toneBlue
class node_primitives,node_orchestrator toneAmber
class node_hf,node_mock,node_registry,node_reference_api toneMint
class node_experiments,node_charts toneRose
class node_user,node_model,node_answers toneIndigo
```

## Components

### Terminal interface

- [REPL and CLI](https://github.com/gpt-agi/openjev/blob/main/src/openjev/cli/main.py): `src/openjev/cli/main.py`
- [Result renderer](https://github.com/gpt-agi/openjev/blob/main/src/openjev/cli/render.py): `src/openjev/cli/render.py`

### Decision core

- [Typed schemas](https://github.com/gpt-agi/openjev/blob/main/src/openjev/core/primitives.py): `src/openjev/core/primitives.py`
- [Decision orchestrator](https://github.com/gpt-agi/openjev/blob/main/src/openjev/backends/base.py): `src/openjev/backends/base.py`

### Scoring backends

- [Transformers backend](https://github.com/gpt-agi/openjev/blob/main/src/openjev/backends/hf.py): `src/openjev/backends/hf.py`
- [Mock backend](https://github.com/gpt-agi/openjev/blob/main/src/openjev/backends/mock.py): `src/openjev/backends/mock.py`
- [Backend selection](https://github.com/gpt-agi/openjev/blob/main/src/openjev/backends/__init__.py): `src/openjev/backends/__init__.py`

### Reference experiments

- [Live experiment harness](https://github.com/gpt-agi/openjev/blob/main/scripts/experiments.py): `scripts/experiments.py`
- [Experiment charts](https://github.com/gpt-agi/openjev/blob/main/scripts/experiments.py): `scripts/experiments.py`

### Other components

- **Developer**
- **Hugging Face model**
- **Official Jev API**
- **Typed decisions**

## Connections

- Developer → REPL and CLI: enters requests (evidence: `README.md`)
- REPL and CLI → Typed schemas: builds requests (evidence: `src/openjev/cli/main.py`)
- REPL and CLI → Backend selection: selects backend (evidence: `src/openjev/cli/main.py`)
- REPL and CLI → Decision orchestrator: submits request (evidence: `src/openjev/cli/main.py`)
- Decision orchestrator → Typed schemas: builds answers (evidence: `src/openjev/backends/base.py`)
- Decision orchestrator → Transformers backend: scores labels (evidence: `src/openjev/backends/hf.py`)
- Decision orchestrator → Mock backend: scores labels (evidence: `src/openjev/backends/mock.py`)
- Transformers backend → Hugging Face model: reads logits (evidence: `src/openjev/backends/hf.py`)
- Backend selection → Transformers backend: creates backend (evidence: `src/openjev/backends/__init__.py`)
- Backend selection → Mock backend: creates backend (evidence: `src/openjev/backends/__init__.py`)
- REPL and CLI → Result renderer: renders response (evidence: `src/openjev/cli/main.py`)
- Result renderer → Typed decisions: displays probabilities (evidence: `src/openjev/cli/render.py`)
- Developer → Live experiment harness: runs experiments (evidence: `README.md`)
- Live experiment harness → Official Jev API: requests decisions (evidence: `scripts/experiments.py`)
- Live experiment harness → Experiment charts: produces charts (evidence: `scripts/experiments.py`)
