# kyegomez/open-jev architecture

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

- Interactive diagram: https://gitdiagram.com/kyegomez/open-jev
- Repository: https://github.com/kyegomez/open-jev

## Overview

Open Jev is a small PyTorch research implementation of typed, parallel decisions over structured program state, rather than a text-generating application. A caller supplies state and typed questions; Jev encodes state once, lets isolated query slots read the shared representation, and returns Noul, Choice, or Score answers. The same module exposes soft-target RLCD calibration and consistency training. The README documents structural embeddings, evidential confidence, and cacheable state encoding; sampled excerpts are partial, so uncertain internal call wiring is omitted. All runtime components reside in open_jev/main.py.

Main entry points: [`open_jev/main.py`](https://github.com/kyegomez/open-jev/blob/main/open_jev/main.py) (Jev model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_encoding["State encoding"]
  node_tokenizer["Hash tokenizer<br/>[main.py]"]
  node_state_encoder["State encoder<br/>[main.py]"]
  node_state_cache["Shared state cache<br/>[main.py]"]
  node_text_encoder["Text encoder<br/>[main.py]"]
end

subgraph group_inference["Typed inference"]
  node_jev["Jev model<br/>[main.py]"]
  node_query_slots["Query slots<br/>[main.py]"]
  node_readout["Readout blocks<br/>[main.py]"]
  node_noul_head["Noul head<br/>[main.py]"]
  node_choice_head["Choice head<br/>[main.py]"]
  node_score_head["Score head<br/>[main.py]"]
  node_confidence_head["Confidence head<br/>[main.py]"]
end

subgraph group_training["Calibration training"]
  node_rlcd_loss["RLCD loss<br/>[main.py]"]
end

node_caller(("Caller"))
node_inputs["State and questions"]
node_answers["Typed answers"]
node_targets["Soft targets"]
node_augmented_states["Augmented states"]

node_caller -->|"provides"| node_inputs
node_inputs -->|"passes"| node_jev
node_jev -->|"encodes text"| node_tokenizer
node_jev -->|"encodes state"| node_state_encoder
node_state_encoder -->|"produces cache"| node_state_cache
node_jev -->|"encodes questions"| node_text_encoder
node_jev -->|"initializes slots"| node_query_slots
node_query_slots -->|"cross-attends"| node_state_cache
node_jev -->|"updates slots"| node_readout
node_readout -->|"scores truth"| node_noul_head
node_readout -->|"scores options"| node_choice_head
node_readout -->|"scores levels"| node_score_head
node_readout -->|"estimates confidence"| node_confidence_head
node_noul_head -->|"returns probability"| node_answers
node_choice_head -->|"returns distribution"| node_answers
node_score_head -->|"returns ordinal result"| node_answers
node_confidence_head -->|"returns confidence"| node_answers
node_answers -->|"returns"| node_caller
node_caller -->|"evaluates model"| node_rlcd_loss
node_rlcd_loss -->|"queries model"| node_jev
node_caller -->|"supplies distributions"| node_targets
node_targets -->|"guides loss"| node_rlcd_loss
node_caller -->|"supplies variants"| node_augmented_states
node_augmented_states -->|"supports consistency"| node_rlcd_loss

click node_jev "https://github.com/kyegomez/open-jev/blob/main/open_jev/main.py"
click node_tokenizer "https://github.com/kyegomez/open-jev/blob/main/open_jev/main.py"
click node_state_encoder "https://github.com/kyegomez/open-jev/blob/main/open_jev/main.py"
click node_state_cache "https://github.com/kyegomez/open-jev/blob/main/open_jev/main.py"
click node_text_encoder "https://github.com/kyegomez/open-jev/blob/main/open_jev/main.py"
click node_query_slots "https://github.com/kyegomez/open-jev/blob/main/open_jev/main.py"
click node_readout "https://github.com/kyegomez/open-jev/blob/main/open_jev/main.py"
click node_noul_head "https://github.com/kyegomez/open-jev/blob/main/open_jev/main.py"
click node_choice_head "https://github.com/kyegomez/open-jev/blob/main/open_jev/main.py"
click node_score_head "https://github.com/kyegomez/open-jev/blob/main/open_jev/main.py"
click node_confidence_head "https://github.com/kyegomez/open-jev/blob/main/open_jev/main.py"
click node_rlcd_loss "https://github.com/kyegomez/open-jev/blob/main/open_jev/main.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_tokenizer,node_state_encoder,node_state_cache,node_text_encoder toneBlue
class node_jev,node_query_slots,node_readout,node_noul_head,node_choice_head,node_score_head,node_confidence_head toneAmber
class node_rlcd_loss toneMint
class node_caller,node_inputs,node_answers,node_targets,node_augmented_states toneIndigo
```

## Components

### State encoding

- [Hash tokenizer](https://github.com/kyegomez/open-jev/blob/main/open_jev/main.py): `open_jev/main.py`
- [State encoder](https://github.com/kyegomez/open-jev/blob/main/open_jev/main.py): `open_jev/main.py`
- [Shared state cache](https://github.com/kyegomez/open-jev/blob/main/open_jev/main.py): `open_jev/main.py`
- [Text encoder](https://github.com/kyegomez/open-jev/blob/main/open_jev/main.py): `open_jev/main.py`

### Typed inference

- [Jev model](https://github.com/kyegomez/open-jev/blob/main/open_jev/main.py): `open_jev/main.py`
- [Query slots](https://github.com/kyegomez/open-jev/blob/main/open_jev/main.py): `open_jev/main.py`
- [Readout blocks](https://github.com/kyegomez/open-jev/blob/main/open_jev/main.py): `open_jev/main.py`
- [Noul head](https://github.com/kyegomez/open-jev/blob/main/open_jev/main.py): `open_jev/main.py`
- [Choice head](https://github.com/kyegomez/open-jev/blob/main/open_jev/main.py): `open_jev/main.py`
- [Score head](https://github.com/kyegomez/open-jev/blob/main/open_jev/main.py): `open_jev/main.py`
- [Confidence head](https://github.com/kyegomez/open-jev/blob/main/open_jev/main.py): `open_jev/main.py`

### Calibration training

- [RLCD loss](https://github.com/kyegomez/open-jev/blob/main/open_jev/main.py): `open_jev/main.py`

### Other components

- **Caller**
- **State and questions**
- **Typed answers**
- **Soft targets**
- **Augmented states**

## Connections

- Caller → State and questions: provides
- State and questions → Jev model: passes
- Jev model → Hash tokenizer: encodes text
- Jev model → State encoder: encodes state
- State encoder → Shared state cache: produces cache
- Jev model → Text encoder: encodes questions
- Jev model → Query slots: initializes slots
- Query slots → Shared state cache: cross-attends
- Jev model → Readout blocks: updates slots
- Readout blocks → Noul head: scores truth
- Readout blocks → Choice head: scores options
- Readout blocks → Score head: scores levels
- Readout blocks → Confidence head: estimates confidence
- Noul head → Typed answers: returns probability
- Choice head → Typed answers: returns distribution
- Score head → Typed answers: returns ordinal result
- Confidence head → Typed answers: returns confidence
- Typed answers → Caller: returns
- Caller → RLCD loss: evaluates model
- RLCD loss → Jev model: queries model
- Caller → Soft targets: supplies distributions
- Soft targets → RLCD loss: guides loss
- Caller → Augmented states: supplies variants
- Augmented states → RLCD loss: supports consistency