# startluxlabs/startlux-decision architecture

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

- Interactive diagram: https://gitdiagram.com/startluxlabs/startlux-decision
- Repository: https://github.com/startluxlabs/startlux-decision

## Overview

StartLux-Decision is a family of typed decision models that returns option probabilities in one forward pass, exposed through a TypeSafe-compatible inference API. The main runtime flow is a client request to the server, question conversion and prompt rendering, model inference, then probability readout. The repository also includes Apple Silicon and int8 inference paths, benchmark and Decision Index evaluation, and LoRA fine-tuning with calibration. Demo harnesses illustrate computer-use and chess clients. Unsampled demo internals and several backend details are represented only where the README or source index documents them.

Main entry points: [`startlux_decision/model.py`](https://github.com/startluxlabs/startlux-decision/blob/main/startlux_decision/model.py) (Decision Engine), [`startlux_decision/jevfmt.py`](https://github.com/startluxlabs/startlux-decision/blob/main/startlux_decision/jevfmt.py) (Typed Format), [`startlux_decision/server.py`](https://github.com/startluxlabs/startlux-decision/blob/main/startlux_decision/server.py) (HTTP Server), [`startlux_decision/mlx_model.py`](https://github.com/startluxlabs/startlux-decision/blob/main/startlux_decision/mlx_model.py) (MLX Backend)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Serving and Format"]
  node_server["HTTP Server<br/>[server.py]"]
  node_typedfmt["Typed Format<br/>[jevfmt.py]"]
end

subgraph group_runtime["Inference Runtime"]
  node_decision["Decision Engine<br/>[model.py]"]
  node_torchmodel["Torch Backend<br/>[model.py]"]
  node_mlx["MLX Backend<br/>[mlx_model.py]"]
  node_int8["MLX Int8<br/>[mlx_int8.py]"]
end

subgraph group_eval["Evaluation"]
  node_indexengine["Index Engine"]
  node_suiteeval["Benchmark Suites<br/>[suites.py]"]
  node_typedeval["Typed Decisions<br/>[typed_decisions.py]"]
  node_batcheval["Index Batching<br/>[batched.py]"]
  node_mergeeval["Index Results<br/>[merge.py]"]
end

subgraph group_training["Model Adaptation"]
  node_finetune["LoRA Fine-tuning<br/>[finetune_lora.py]"]
  node_calibrate["Temperature Calibration<br/>[calibrate.py]"]
end

subgraph group_demos["Demonstrations"]
  node_computer["Computer-use Demo"]
  node_chess["Chess Demo"]
end

node_client(("Decision Client"))
node_service(("Inference Service"))

node_client -->|"submits decisions"| node_server
node_server -->|"dispatches requests"| node_decision
node_server -->|"selects backend"| node_mlx
node_decision -->|"renders questions"| node_typedfmt
node_decision -->|"runs inference"| node_torchmodel
node_mlx -->|"extends inference"| node_decision
node_mlx -->|"renders questions"| node_typedfmt
node_mlx -->|"converts projections"| node_int8
node_server -->|"serves responses"| node_service
node_indexengine -->|"calls decisions"| node_decision
node_suiteeval -->|"predicts in process"| node_decision
node_suiteeval -->|"normalizes answers"| node_typedfmt
node_typedeval -->|"requests predictions"| node_service
node_batcheval -.->|"runs batched evaluation"| node_decision
node_mergeeval -.->|"merges results"| node_batcheval
node_finetune -->|"renders training rows"| node_typedfmt
node_finetune -->|"loads base model"| node_torchmodel
node_calibrate -->|"measures logits"| node_decision
node_calibrate -->|"builds calibration rows"| node_typedfmt
node_computer -->|"sends decisions"| node_service
node_chess -->|"requests moves"| node_service

click node_server "https://github.com/startluxlabs/startlux-decision/blob/main/startlux_decision/server.py"
click node_typedfmt "https://github.com/startluxlabs/startlux-decision/blob/main/startlux_decision/jevfmt.py"
click node_decision "https://github.com/startluxlabs/startlux-decision/blob/main/startlux_decision/model.py"
click node_torchmodel "https://github.com/startluxlabs/startlux-decision/blob/main/startlux_decision/model.py"
click node_mlx "https://github.com/startluxlabs/startlux-decision/blob/main/startlux_decision/mlx_model.py"
click node_int8 "https://github.com/startluxlabs/startlux-decision/blob/main/startlux_decision/mlx_int8.py"
click node_indexengine "https://github.com/startluxlabs/startlux-decision/blob/main/eval/di/startlux_decision_engine.py"
click node_suiteeval "https://github.com/startluxlabs/startlux-decision/blob/main/eval/suites.py"
click node_typedeval "https://github.com/startluxlabs/startlux-decision/blob/main/eval/typed_decisions.py"
click node_batcheval "https://github.com/startluxlabs/startlux-decision/blob/main/eval/di/batched.py"
click node_mergeeval "https://github.com/startluxlabs/startlux-decision/blob/main/eval/di/merge.py"
click node_finetune "https://github.com/startluxlabs/startlux-decision/blob/main/finetune/finetune_lora.py"
click node_calibrate "https://github.com/startluxlabs/startlux-decision/blob/main/finetune/calibrate.py"
click node_computer "https://github.com/startluxlabs/startlux-decision/tree/main/demos/computer_use"
click node_chess "https://github.com/startluxlabs/startlux-decision/tree/main/demos/chess"

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_typedfmt,node_client toneBlue
class node_decision,node_torchmodel,node_mlx,node_int8 toneAmber
class node_indexengine,node_suiteeval,node_typedeval,node_batcheval,node_mergeeval toneMint
class node_finetune,node_calibrate toneRose
class node_computer,node_chess,node_service toneIndigo
```

## Components

### Serving and Format

- [HTTP Server](https://github.com/startluxlabs/startlux-decision/blob/main/startlux_decision/server.py): `startlux_decision/server.py`
- [Typed Format](https://github.com/startluxlabs/startlux-decision/blob/main/startlux_decision/jevfmt.py): `startlux_decision/jevfmt.py`

### Inference Runtime

- [Decision Engine](https://github.com/startluxlabs/startlux-decision/blob/main/startlux_decision/model.py): `startlux_decision/model.py`
- [Torch Backend](https://github.com/startluxlabs/startlux-decision/blob/main/startlux_decision/model.py): `startlux_decision/model.py`
- [MLX Backend](https://github.com/startluxlabs/startlux-decision/blob/main/startlux_decision/mlx_model.py): `startlux_decision/mlx_model.py`
- [MLX Int8](https://github.com/startluxlabs/startlux-decision/blob/main/startlux_decision/mlx_int8.py): `startlux_decision/mlx_int8.py`

### Evaluation

- [Index Engine](https://github.com/startluxlabs/startlux-decision/blob/main/eval/di/startlux_decision_engine.py): `eval/di/startlux_decision_engine.py`
- [Benchmark Suites](https://github.com/startluxlabs/startlux-decision/blob/main/eval/suites.py): `eval/suites.py`
- [Typed Decisions](https://github.com/startluxlabs/startlux-decision/blob/main/eval/typed_decisions.py): `eval/typed_decisions.py`
- [Index Batching](https://github.com/startluxlabs/startlux-decision/blob/main/eval/di/batched.py): `eval/di/batched.py`
- [Index Results](https://github.com/startluxlabs/startlux-decision/blob/main/eval/di/merge.py): `eval/di/merge.py`

### Model Adaptation

- [LoRA Fine-tuning](https://github.com/startluxlabs/startlux-decision/blob/main/finetune/finetune_lora.py): `finetune/finetune_lora.py`
- [Temperature Calibration](https://github.com/startluxlabs/startlux-decision/blob/main/finetune/calibrate.py): `finetune/calibrate.py`

### Demonstrations

- [Computer-use Demo](https://github.com/startluxlabs/startlux-decision/tree/main/demos/computer_use): `demos/computer_use`
- [Chess Demo](https://github.com/startluxlabs/startlux-decision/tree/main/demos/chess): `demos/chess`

### Other components

- **Decision Client**
- **Inference Service**

## Connections

- Decision Client → HTTP Server: submits decisions (evidence: `README.md`)
- HTTP Server → Decision Engine: dispatches requests (evidence: `startlux_decision/server.py`)
- HTTP Server → MLX Backend: selects backend (evidence: `startlux_decision/server.py`)
- Decision Engine → Typed Format: renders questions (evidence: `startlux_decision/model.py`)
- Decision Engine → Torch Backend: runs inference (evidence: `startlux_decision/model.py`)
- MLX Backend → Decision Engine: extends inference (evidence: `startlux_decision/mlx_model.py`)
- MLX Backend → Typed Format: renders questions (evidence: `startlux_decision/mlx_model.py`)
- MLX Backend → MLX Int8: converts projections (evidence: `startlux_decision/mlx_model.py`)
- HTTP Server → Inference Service: serves responses (evidence: `startlux_decision/server.py`)
- Index Engine → Decision Engine: calls decisions (evidence: `eval/di/startlux_decision_engine.py`)
- Benchmark Suites → Decision Engine: predicts in process (evidence: `eval/suites.py`)
- Benchmark Suites → Typed Format: normalizes answers (evidence: `eval/suites.py`)
- Typed Decisions → Inference Service: requests predictions (evidence: `eval/typed_decisions.py`)
- Index Batching → Decision Engine: runs batched evaluation
- Index Results → Index Batching: merges results
- LoRA Fine-tuning → Typed Format: renders training rows (evidence: `finetune/finetune_lora.py`)
- LoRA Fine-tuning → Torch Backend: loads base model (evidence: `finetune/finetune_lora.py`)
- Temperature Calibration → Decision Engine: measures logits (evidence: `finetune/calibrate.py`)
- Temperature Calibration → Typed Format: builds calibration rows (evidence: `finetune/calibrate.py`)
- Computer-use Demo → Inference Service: sends decisions (evidence: `README.md`)
- Chess Demo → Inference Service: requests moves (evidence: `README.md`)