# malevrigns/agent-jev architecture

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

- Interactive diagram: https://gitdiagram.com/malevrigns/agent-jev
- Repository: https://github.com/malevrigns/agent-jev

## Overview

AgentJev is a zero-decoding decision model: callers provide a state and typed questions, and receive probability distributions over supplied candidates. Its main workflow runs through the HTTP service, which validates and prepares requests, encodes candidate paths with shared-prefix inference, scores them, and formats answers. The repository also contains a distinct, gated tool-routing path and data/training code. Some implementation excerpts are partial, so links between unsampled components are limited to documented or directly evidenced behavior.

Main entry points: [`jev_service/engine.py`](https://github.com/malevrigns/agent-jev/blob/main/jev_service/engine.py) (Decision engine), [`agentjev/train.py`](https://github.com/malevrigns/agent-jev/blob/main/agentjev/train.py) (Training pipeline), [`agentjev/model.py`](https://github.com/malevrigns/agent-jev/blob/main/agentjev/model.py) (Decision model), [`jev_service/server.py`](https://github.com/malevrigns/agent-jev/blob/main/jev_service/server.py) (HTTP service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_serving["Decision serving"]
  node_server["HTTP service<br/>[server.py]"]
  node_engine["Decision engine<br/>[engine.py]"]
  node_contract["Request contract<br/>[contract.py]"]
  node_prefix["Prefix encoder<br/>[prefix.py]"]
  node_model["Decision model<br/>[model.py]"]
  node_weights["Model checkpoint"]
end

subgraph group_routing["Tool routing"]
  node_routing_data["Routing data conversion<br/>[routing_data.py]"]
  node_routing_semantics["Route semantics<br/>[routing.py]"]
  node_router["Gated action router<br/>[routing_runtime.py]"]
end

subgraph group_training["Model training"]
  node_decision_data["Decision data<br/>[data.py]"]
  node_synthetic_data["Synthetic data<br/>[synth.py]"]
  node_training["Training pipeline<br/>[train.py]"]
  node_losses["Training losses<br/>[losses.py]"]
  node_typed_eval["Typed evaluation<br/>[experiment.py]"]
end

subgraph group_clients["Product clients"]
  node_client["Python client<br/>[agentjev_client.py]"]
  node_hook["Pre-tool safety hook<br/>[agentjev_hook.py]"]
end

node_agent(("Decision caller"))
node_hook_actor(("Claude Code"))

node_agent -->|"submits decisions"| node_client
node_client -->|"POST evaluate"| node_server
node_hook_actor -->|"provides tool action"| node_hook
node_hook -->|"requests risk assessment"| node_server
node_server -->|"dispatches evaluation"| node_engine
node_engine -->|"prepares requests"| node_contract
node_engine -->|"encodes paths"| node_prefix
node_prefix -->|"encodes candidates"| node_model
node_engine -->|"scores vectors"| node_model
node_engine -->|"formats answers"| node_contract
node_engine -->|"loads checkpoint"| node_weights
node_routing_data -->|"uses route labels"| node_routing_semantics
node_router -->|"uses compact state"| node_routing_semantics
node_router -.->|"loads routing weights"| node_weights
node_decision_data -->|"supplies examples"| node_training
node_synthetic_data -->|"supplies examples"| node_training
node_training -->|"computes objectives"| node_losses
node_training -->|"updates parameters"| node_model
node_typed_eval -->|"evaluates predictions"| node_model

click node_server "https://github.com/malevrigns/agent-jev/blob/main/jev_service/server.py"
click node_engine "https://github.com/malevrigns/agent-jev/blob/main/jev_service/engine.py"
click node_contract "https://github.com/malevrigns/agent-jev/blob/main/jev_service/contract.py"
click node_prefix "https://github.com/malevrigns/agent-jev/blob/main/jev_service/prefix.py"
click node_model "https://github.com/malevrigns/agent-jev/blob/main/agentjev/model.py"
click node_client "https://github.com/malevrigns/agent-jev/blob/main/agentjev_client.py"
click node_hook "https://github.com/malevrigns/agent-jev/blob/main/agentjev_hook.py"
click node_routing_data "https://github.com/malevrigns/agent-jev/blob/main/agentjev/routing_data.py"
click node_routing_semantics "https://github.com/malevrigns/agent-jev/blob/main/agentjev/routing.py"
click node_router "https://github.com/malevrigns/agent-jev/blob/main/agentjev/routing_runtime.py"
click node_decision_data "https://github.com/malevrigns/agent-jev/blob/main/agentjev/data.py"
click node_synthetic_data "https://github.com/malevrigns/agent-jev/blob/main/agentjev/synth.py"
click node_training "https://github.com/malevrigns/agent-jev/blob/main/agentjev/train.py"
click node_losses "https://github.com/malevrigns/agent-jev/blob/main/agentjev/losses.py"
click node_typed_eval "https://github.com/malevrigns/agent-jev/blob/main/typed_decisions/experiment.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_server,node_engine,node_contract,node_prefix,node_model,node_weights toneBlue
class node_routing_data,node_routing_semantics,node_router toneAmber
class node_decision_data,node_synthetic_data,node_training,node_losses,node_typed_eval toneMint
class node_client,node_hook toneRose
class node_agent,node_hook_actor toneIndigo
```

## Components

### Decision serving

- [HTTP service](https://github.com/malevrigns/agent-jev/blob/main/jev_service/server.py): `jev_service/server.py`
- [Decision engine](https://github.com/malevrigns/agent-jev/blob/main/jev_service/engine.py): `jev_service/engine.py`
- [Request contract](https://github.com/malevrigns/agent-jev/blob/main/jev_service/contract.py): `jev_service/contract.py`
- [Prefix encoder](https://github.com/malevrigns/agent-jev/blob/main/jev_service/prefix.py): `jev_service/prefix.py`
- [Decision model](https://github.com/malevrigns/agent-jev/blob/main/agentjev/model.py): `agentjev/model.py`
- **Model checkpoint**

### Tool routing

- [Routing data conversion](https://github.com/malevrigns/agent-jev/blob/main/agentjev/routing_data.py): `agentjev/routing_data.py`
- [Route semantics](https://github.com/malevrigns/agent-jev/blob/main/agentjev/routing.py): `agentjev/routing.py`
- [Gated action router](https://github.com/malevrigns/agent-jev/blob/main/agentjev/routing_runtime.py): `agentjev/routing_runtime.py`

### Model training

- [Decision data](https://github.com/malevrigns/agent-jev/blob/main/agentjev/data.py): `agentjev/data.py`
- [Synthetic data](https://github.com/malevrigns/agent-jev/blob/main/agentjev/synth.py): `agentjev/synth.py`
- [Training pipeline](https://github.com/malevrigns/agent-jev/blob/main/agentjev/train.py): `agentjev/train.py`
- [Training losses](https://github.com/malevrigns/agent-jev/blob/main/agentjev/losses.py): `agentjev/losses.py`
- [Typed evaluation](https://github.com/malevrigns/agent-jev/blob/main/typed_decisions/experiment.py): `typed_decisions/experiment.py`

### Product clients

- [Python client](https://github.com/malevrigns/agent-jev/blob/main/agentjev_client.py): `agentjev_client.py`
- [Pre-tool safety hook](https://github.com/malevrigns/agent-jev/blob/main/agentjev_hook.py): `agentjev_hook.py`

### Other components

- **Decision caller**
- **Claude Code**

## Connections

- Decision caller → Python client: submits decisions
- Python client → HTTP service: POST evaluate
- Claude Code → Pre-tool safety hook: provides tool action
- Pre-tool safety hook → HTTP service: requests risk assessment
- HTTP service → Decision engine: dispatches evaluation
- Decision engine → Request contract: prepares requests
- Decision engine → Prefix encoder: encodes paths
- Prefix encoder → Decision model: encodes candidates
- Decision engine → Decision model: scores vectors
- Decision engine → Request contract: formats answers
- Decision engine → Model checkpoint: loads checkpoint
- Routing data conversion → Route semantics: uses route labels
- Gated action router → Route semantics: uses compact state
- Gated action router → Model checkpoint: loads routing weights
- Decision data → Training pipeline: supplies examples
- Synthetic data → Training pipeline: supplies examples
- Training pipeline → Training losses: computes objectives
- Training pipeline → Decision model: updates parameters
- Typed evaluation → Decision model: evaluates predictions