# zhangcy122/openjev architecture

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

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

## Overview

OpenJevPro is a Python decision engine for AI agents, exposing typed categorical, binary, and ordinal decisions. An agent submits context and candidates to the client, which scores choices through an inference backend and returns calibrated results with confidence and abstention information. Optional paths add deliberation and crystallization for ambiguous queries, or guarded local/cloud routing with circuit-breaker fallback. The README also documents local Laya inference and comparative evaluation; those harness capabilities are represented, while source excerpts do not establish every internal connection. Evidence is limited to the README and sampled source.

Main entry points: [`openjevpro/client.py`](https://github.com/zhangcy122/openjev/blob/main/openjevpro/client.py) (Decision Client), [`openjevpro/gateway.py`](https://github.com/zhangcy122/openjev/blob/main/openjevpro/gateway.py) (Hybrid Gateway), [`openjevpro/flywheel.py`](https://github.com/zhangcy122/openjev/blob/main/openjevpro/flywheel.py) (Flywheel Orchestrator), [`openjevpro/mock.py`](https://github.com/zhangcy122/openjev/blob/main/openjevpro/mock.py) (Offline Mock Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_decision["Decision API"]
  node_client["Decision Client<br/>[client.py]"]
  node_schemas["Typed Results<br/>[schemas.py]"]
  node_backend["Inference Backend"]
  node_calibrator["Temperature Calibration<br/>[calibrator.py]"]
  node_mock["Offline Mock Engine<br/>[mock.py]"]
end

subgraph group_flywheel["Deliberation"]
  node_flywheel["Flywheel Orchestrator<br/>[flywheel.py]"]
  node_fast["Fast Decision Engine"]
  node_reasoner["Reasoning Model"]
  node_crystallizer["Crystallization Operator<br/>[flywheel.py]"]
  node_memory[("Crystallization Store<br/>[flywheel.py]")]
end

subgraph group_hybrid["Hybrid Routing"]
  node_gateway["Hybrid Gateway<br/>[gateway.py]"]
  node_local["Local Engine"]
  node_cloud["Cloud Engine"]
  node_guard["Safety Guard<br/>[guard.py]"]
  node_breaker["Circuit Breaker<br/>[gateway.py]"]
end

subgraph group_engines["Engines And Evaluation"]
  node_harness["Evaluation Harness<br/>[harness.py]"]
  node_laya["Laya Engine<br/>[harness.py]"]
  node_laya_service["Laya Inference Service"]
end

node_agent(("AI Agent"))

node_agent -->|"submits decision"| node_client
node_client -->|"requests scores"| node_backend
node_backend -->|"returns scores"| node_client
node_client -->|"returns typed result"| node_schemas
node_client -.->|"uses offline mode"| node_mock
node_mock -->|"calibrates probabilities"| node_calibrator
node_client -->|"creates flywheel"| node_flywheel
node_flywheel -->|"evaluates fast path"| node_fast
node_flywheel -.->|"escalates ambiguity"| node_reasoner
node_flywheel -->|"distills exploration"| node_crystallizer
node_crystallizer -->|"updates criteria"| node_memory
node_flywheel -->|"merges criteria"| node_memory
node_gateway -->|"evaluates locally"| node_local
node_gateway -->|"guards probabilities"| node_guard
node_gateway -->|"checks circuit"| node_breaker
node_gateway -->|"escalates queries"| node_cloud
node_gateway -->|"falls back"| node_local
node_harness -->|"evaluates with engine"| node_laya
node_laya -->|"requests inference"| node_laya_service

click node_client "https://github.com/zhangcy122/openjev/blob/main/openjevpro/client.py"
click node_schemas "https://github.com/zhangcy122/openjev/blob/main/openjevpro/schemas.py"
click node_calibrator "https://github.com/zhangcy122/openjev/blob/main/openjevpro/calibrator.py"
click node_mock "https://github.com/zhangcy122/openjev/blob/main/openjevpro/mock.py"
click node_flywheel "https://github.com/zhangcy122/openjev/blob/main/openjevpro/flywheel.py"
click node_crystallizer "https://github.com/zhangcy122/openjev/blob/main/openjevpro/flywheel.py"
click node_memory "https://github.com/zhangcy122/openjev/blob/main/openjevpro/flywheel.py"
click node_gateway "https://github.com/zhangcy122/openjev/blob/main/openjevpro/gateway.py"
click node_guard "https://github.com/zhangcy122/openjev/blob/main/openjevpro/guard.py"
click node_breaker "https://github.com/zhangcy122/openjev/blob/main/openjevpro/gateway.py"
click node_harness "https://github.com/zhangcy122/openjev/blob/main/openjevpro/harness.py"
click node_laya "https://github.com/zhangcy122/openjev/blob/main/openjevpro/harness.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_client,node_schemas,node_backend,node_calibrator,node_mock toneBlue
class node_flywheel,node_fast,node_reasoner,node_crystallizer,node_memory toneAmber
class node_gateway,node_local,node_cloud,node_guard,node_breaker toneMint
class node_harness,node_laya,node_laya_service toneRose
class node_agent toneIndigo
```

## Components

### Decision API

- [Decision Client](https://github.com/zhangcy122/openjev/blob/main/openjevpro/client.py): `openjevpro/client.py`
- [Typed Results](https://github.com/zhangcy122/openjev/blob/main/openjevpro/schemas.py): `openjevpro/schemas.py`
- **Inference Backend**
- [Temperature Calibration](https://github.com/zhangcy122/openjev/blob/main/openjevpro/calibrator.py): `openjevpro/calibrator.py`
- [Offline Mock Engine](https://github.com/zhangcy122/openjev/blob/main/openjevpro/mock.py): `openjevpro/mock.py`

### Deliberation

- [Flywheel Orchestrator](https://github.com/zhangcy122/openjev/blob/main/openjevpro/flywheel.py): `openjevpro/flywheel.py`
- **Fast Decision Engine**
- **Reasoning Model**
- [Crystallization Operator](https://github.com/zhangcy122/openjev/blob/main/openjevpro/flywheel.py): `openjevpro/flywheel.py`
- [Crystallization Store](https://github.com/zhangcy122/openjev/blob/main/openjevpro/flywheel.py): `openjevpro/flywheel.py`

### Hybrid Routing

- [Hybrid Gateway](https://github.com/zhangcy122/openjev/blob/main/openjevpro/gateway.py): `openjevpro/gateway.py`
- **Local Engine**
- **Cloud Engine**
- [Safety Guard](https://github.com/zhangcy122/openjev/blob/main/openjevpro/guard.py): `openjevpro/guard.py`
- [Circuit Breaker](https://github.com/zhangcy122/openjev/blob/main/openjevpro/gateway.py): `openjevpro/gateway.py`

### Engines And Evaluation

- [Evaluation Harness](https://github.com/zhangcy122/openjev/blob/main/openjevpro/harness.py): `openjevpro/harness.py`
- [Laya Engine](https://github.com/zhangcy122/openjev/blob/main/openjevpro/harness.py): `openjevpro/harness.py`
- **Laya Inference Service**

### Other components

- **AI Agent**

## Connections

- AI Agent → Decision Client: submits decision
- Decision Client → Inference Backend: requests scores
- Inference Backend → Decision Client: returns scores
- Decision Client → Typed Results: returns typed result
- Decision Client → Offline Mock Engine: uses offline mode
- Offline Mock Engine → Temperature Calibration: calibrates probabilities
- Decision Client → Flywheel Orchestrator: creates flywheel
- Flywheel Orchestrator → Fast Decision Engine: evaluates fast path
- Flywheel Orchestrator → Reasoning Model: escalates ambiguity
- Flywheel Orchestrator → Crystallization Operator: distills exploration
- Crystallization Operator → Crystallization Store: updates criteria
- Flywheel Orchestrator → Crystallization Store: merges criteria
- Hybrid Gateway → Local Engine: evaluates locally
- Hybrid Gateway → Safety Guard: guards probabilities
- Hybrid Gateway → Circuit Breaker: checks circuit
- Hybrid Gateway → Cloud Engine: escalates queries
- Hybrid Gateway → Local Engine: falls back
- Evaluation Harness → Laya Engine: evaluates with engine
- Laya Engine → Laya Inference Service: requests inference