# gitchw/lct architecture

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

## Overview

Jev-LCT is a low-latency System-One decision engine: clients submit choice, noul, or score questions; the API delegates inference to a recurrent transformer, which returns decisions with trajectory-derived confidence. Training and evaluation support the model lifecycle, while the Snake showcase exercises decisions in a real-time game loop. README capabilities include adaptive early exit, calibration, Jev-compatible serving, benchmarks, and Snake analysis. Some internal wiring and the browser dashboard are not visible in the sampled source, so uncertain links are omitted.

Main entry points: [`lct/inference/engine.py`](https://github.com/gitchw/lct/blob/master/lct/inference/engine.py) (Inference Engine), [`snake/server.py`](https://github.com/gitchw/lct/blob/master/snake/server.py) (Game API Server), [`snake/client.py`](https://github.com/gitchw/lct/blob/master/snake/client.py) (Game Runner), [`lct/api/server.py`](https://github.com/gitchw/lct/blob/master/lct/api/server.py) (Jev REST API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_serving["Decision Serving"]
  node_sdk["Python SDK<br/>[client.py]"]
  node_api["Jev REST API<br/>[server.py]"]
  node_schema["Request Schemas<br/>[schema.py]"]
  node_cli["Inference CLI<br/>[cli.py]"]
end

subgraph group_inference["Recurrent Inference"]
  node_engine["Inference Engine<br/>[engine.py]"]
  node_transformer["Looped Transformer"]
  node_exit["Adaptive Early Exit<br/>[early_exit.py]"]
  node_readout["Candidate Readout<br/>[readout.py]"]
  node_trajectory["Confidence Trajectory<br/>[trajectory.py]"]
  node_calibration["Confidence Mapping<br/>[mapper.py]"]
  node_metrics["Calibration Metrics<br/>[metrics.py]"]
end

subgraph group_learning["Training Evaluation"]
  node_trainer["Model Trainer<br/>[trainer.py]"]
  node_losses["Training Losses<br/>[losses.py]"]
  node_benchmarks["Benchmark Data<br/>[benchmarks.py]"]
  node_evaluator["Benchmark Evaluator<br/>[evaluator.py]"]
  node_visualizer["Results Visualizer<br/>[visualizer.py]"]
end

subgraph group_snake["Snake Showcase"]
  node_snake_client["Game Runner<br/>[client.py]"]
  node_snake_engine["Game Rules<br/>[engine.py]"]
  node_analysis["Spatial Analysis<br/>[analysis.py]"]
  node_prompt["Decision Prompt<br/>[prompt.py]"]
  node_registry["Model Adapter<br/>[models_adapter.py]"]
  node_snake_api["Game API Server<br/>[server.py]"]
  node_terminal["Terminal UI<br/>[ui_terminal.py]"]
end

node_user(("Decision Client"))

node_user -->|"submits query"| node_sdk
node_sdk -->|"sends HTTP request"| node_api
node_api -->|"validates payload"| node_schema
node_api -->|"dispatches inference"| node_engine
node_cli -->|"runs inference"| node_engine
node_engine -->|"runs recurrent model"| node_transformer
node_engine -->|"checks loop exit"| node_exit
node_engine -->|"selects candidate readout"| node_readout
node_engine -->|"maps confidence"| node_calibration
node_transformer -->|"records loop dynamics"| node_trajectory
node_calibration -->|"evaluates calibration"| node_metrics
node_trainer -->|"computes training loss"| node_losses
node_trainer -->|"trains model"| node_transformer
node_benchmarks -->|"supplies benchmark data"| node_evaluator
node_evaluator -->|"evaluates predictions"| node_engine
node_evaluator -->|"provides results"| node_visualizer
node_snake_client -->|"advances game"| node_snake_engine
node_snake_client -->|"analyzes game state"| node_analysis
node_snake_client -->|"requests move"| node_snake_api
node_snake_api -->|"analyzes game state"| node_analysis
node_snake_api -->|"builds decision prompt"| node_prompt
node_snake_api -->|"selects decision model"| node_registry
node_registry -->|"runs LCT inference"| node_engine
node_terminal -->|"runs game client"| node_snake_client

click node_sdk "https://github.com/gitchw/lct/blob/master/lct/api/client.py"
click node_api "https://github.com/gitchw/lct/blob/master/lct/api/server.py"
click node_schema "https://github.com/gitchw/lct/blob/master/lct/api/schema.py"
click node_cli "https://github.com/gitchw/lct/blob/master/lct/cli.py"
click node_engine "https://github.com/gitchw/lct/blob/master/lct/inference/engine.py"
click node_transformer "https://github.com/gitchw/lct/blob/master/lct/modeling/looped_transformer.py"
click node_exit "https://github.com/gitchw/lct/blob/master/lct/modeling/early_exit.py"
click node_readout "https://github.com/gitchw/lct/blob/master/lct/modeling/readout.py"
click node_trajectory "https://github.com/gitchw/lct/blob/master/lct/modeling/trajectory.py"
click node_calibration "https://github.com/gitchw/lct/blob/master/lct/calibration/mapper.py"
click node_metrics "https://github.com/gitchw/lct/blob/master/lct/calibration/metrics.py"
click node_trainer "https://github.com/gitchw/lct/blob/master/lct/training/trainer.py"
click node_losses "https://github.com/gitchw/lct/blob/master/lct/training/losses.py"
click node_benchmarks "https://github.com/gitchw/lct/blob/master/lct/data/benchmarks.py"
click node_evaluator "https://github.com/gitchw/lct/blob/master/lct/evaluation/evaluator.py"
click node_visualizer "https://github.com/gitchw/lct/blob/master/lct/evaluation/visualizer.py"
click node_snake_client "https://github.com/gitchw/lct/blob/master/snake/client.py"
click node_snake_engine "https://github.com/gitchw/lct/blob/master/snake/engine.py"
click node_analysis "https://github.com/gitchw/lct/blob/master/snake/analysis.py"
click node_prompt "https://github.com/gitchw/lct/blob/master/snake/prompt.py"
click node_registry "https://github.com/gitchw/lct/blob/master/snake/models_adapter.py"
click node_snake_api "https://github.com/gitchw/lct/blob/master/snake/server.py"
click node_terminal "https://github.com/gitchw/lct/blob/master/snake/ui_terminal.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_sdk,node_api,node_schema,node_cli,node_user toneBlue
class node_engine,node_transformer,node_exit,node_readout,node_trajectory,node_calibration,node_metrics toneAmber
class node_trainer,node_losses,node_benchmarks,node_evaluator,node_visualizer toneMint
class node_snake_client,node_snake_engine,node_analysis,node_prompt,node_registry,node_snake_api,node_terminal toneRose
```

## Components

### Decision Serving

- [Python SDK](https://github.com/gitchw/lct/blob/master/lct/api/client.py): `lct/api/client.py`
- [Jev REST API](https://github.com/gitchw/lct/blob/master/lct/api/server.py): `lct/api/server.py`
- [Request Schemas](https://github.com/gitchw/lct/blob/master/lct/api/schema.py): `lct/api/schema.py`
- [Inference CLI](https://github.com/gitchw/lct/blob/master/lct/cli.py): `lct/cli.py`

### Recurrent Inference

- [Inference Engine](https://github.com/gitchw/lct/blob/master/lct/inference/engine.py): `lct/inference/engine.py`
- [Looped Transformer](https://github.com/gitchw/lct/blob/master/lct/modeling/looped_transformer.py): `lct/modeling/looped_transformer.py`
- [Adaptive Early Exit](https://github.com/gitchw/lct/blob/master/lct/modeling/early_exit.py): `lct/modeling/early_exit.py`
- [Candidate Readout](https://github.com/gitchw/lct/blob/master/lct/modeling/readout.py): `lct/modeling/readout.py`
- [Confidence Trajectory](https://github.com/gitchw/lct/blob/master/lct/modeling/trajectory.py): `lct/modeling/trajectory.py`
- [Confidence Mapping](https://github.com/gitchw/lct/blob/master/lct/calibration/mapper.py): `lct/calibration/mapper.py`
- [Calibration Metrics](https://github.com/gitchw/lct/blob/master/lct/calibration/metrics.py): `lct/calibration/metrics.py`

### Training Evaluation

- [Model Trainer](https://github.com/gitchw/lct/blob/master/lct/training/trainer.py): `lct/training/trainer.py`
- [Training Losses](https://github.com/gitchw/lct/blob/master/lct/training/losses.py): `lct/training/losses.py`
- [Benchmark Data](https://github.com/gitchw/lct/blob/master/lct/data/benchmarks.py): `lct/data/benchmarks.py`
- [Benchmark Evaluator](https://github.com/gitchw/lct/blob/master/lct/evaluation/evaluator.py): `lct/evaluation/evaluator.py`
- [Results Visualizer](https://github.com/gitchw/lct/blob/master/lct/evaluation/visualizer.py): `lct/evaluation/visualizer.py`

### Snake Showcase

- [Game Runner](https://github.com/gitchw/lct/blob/master/snake/client.py): `snake/client.py`
- [Game Rules](https://github.com/gitchw/lct/blob/master/snake/engine.py): `snake/engine.py`
- [Spatial Analysis](https://github.com/gitchw/lct/blob/master/snake/analysis.py): `snake/analysis.py`
- [Decision Prompt](https://github.com/gitchw/lct/blob/master/snake/prompt.py): `snake/prompt.py`
- [Model Adapter](https://github.com/gitchw/lct/blob/master/snake/models_adapter.py): `snake/models_adapter.py`
- [Game API Server](https://github.com/gitchw/lct/blob/master/snake/server.py): `snake/server.py`
- [Terminal UI](https://github.com/gitchw/lct/blob/master/snake/ui_terminal.py): `snake/ui_terminal.py`

### Other components

- **Decision Client**

## Connections

- Decision Client → Python SDK: submits query
- Python SDK → Jev REST API: sends HTTP request
- Jev REST API → Request Schemas: validates payload
- Jev REST API → Inference Engine: dispatches inference
- Inference CLI → Inference Engine: runs inference
- Inference Engine → Looped Transformer: runs recurrent model
- Inference Engine → Adaptive Early Exit: checks loop exit
- Inference Engine → Candidate Readout: selects candidate readout
- Inference Engine → Confidence Mapping: maps confidence
- Looped Transformer → Confidence Trajectory: records loop dynamics
- Confidence Mapping → Calibration Metrics: evaluates calibration
- Model Trainer → Training Losses: computes training loss
- Model Trainer → Looped Transformer: trains model
- Benchmark Data → Benchmark Evaluator: supplies benchmark data
- Benchmark Evaluator → Inference Engine: evaluates predictions
- Benchmark Evaluator → Results Visualizer: provides results
- Game Runner → Game Rules: advances game
- Game Runner → Spatial Analysis: analyzes game state
- Game Runner → Game API Server: requests move
- Game API Server → Spatial Analysis: analyzes game state
- Game API Server → Decision Prompt: builds decision prompt
- Game API Server → Model Adapter: selects decision model
- Model Adapter → Inference Engine: runs LCT inference
- Terminal UI → Game Runner: runs game client