# ankit-aglawe/tinyjev architecture

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

- Interactive diagram: https://gitdiagram.com/ankit-aglawe/tinyjev
- Repository: https://github.com/ankit-aglawe/tinyjev

## Overview

TinyJev is a local typed-decision inference library: callers provide state and Choice, Noul, or Score questions, and receive option probabilities and selected answers without text generation. Its main path normalizes a request, encodes model-family-specific candidate paths, runs a Qwen3 backbone, scores and calibrates logits, and formats results. The Python API and loopback HTTP endpoints share this runtime; conversion prepares compatible checkpoints. README-described capabilities are included where supported by the tree, but unsampled modules’ internal wiring is not inferred.

Main entry points: [`tinyjev/agent.py`](https://github.com/ankit-aglawe/tinyjev/blob/main/tinyjev/agent.py) (Agent API), [`tinyjev/serve.py`](https://github.com/ankit-aglawe/tinyjev/blob/main/tinyjev/serve.py) (Local HTTP server), [`tinyjev/cli.py`](https://github.com/ankit-aglawe/tinyjev/blob/main/tinyjev/cli.py) (CLI), [`tinyjev/registry.py`](https://github.com/ankit-aglawe/tinyjev/blob/main/tinyjev/registry.py) (Model registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_server["Local HTTP server<br/>[serve.py]"]
  node_cli["CLI<br/>[cli.py]"]
end

subgraph group_runtime["Decision runtime"]
  node_agent["Agent API<br/>[agent.py]"]
  node_results["Decision results<br/>[agent.py]"]
end

subgraph group_execution["Model execution"]
  node_family_factory["Family factory<br/>[__init__.py]"]
  node_marker["Marker family<br/>[marker.py]"]
  node_pointer["Pointer family<br/>[pointer.py]"]
  node_mlx["MLX backend<br/>[mlx_backend.py]"]
  node_torch["PyTorch backend<br/>[torch_backend.py]"]
end

subgraph group_models["Checkpoint lifecycle"]
  node_registry["Model registry<br/>[registry.py]"]
  node_conversion["Checkpoint conversion<br/>[convert.py]"]
end

node_python_user(("Python caller"))
node_http_client(("HTTP client"))
node_hub["Model weights"]

node_python_user -->|"calls predict"| node_agent
node_http_client -->|"sends request"| node_server
node_cli -->|"loads model"| node_registry
node_cli -->|"starts server"| node_server
node_server -->|"dispatches predict"| node_agent
node_server -->|"dispatches System One"| node_agent
node_agent -->|"creates family"| node_family_factory
node_agent -->|"selects backend"| node_mlx
node_agent -->|"selects backend"| node_torch
node_agent -->|"encodes and scores"| node_marker
node_agent -->|"encodes and scores"| node_pointer
node_agent -->|"formats probabilities"| node_results
node_registry -.->|"fetches weights"| node_hub
node_conversion -->|"converts checkpoints"| node_hub

click node_agent "https://github.com/ankit-aglawe/tinyjev/blob/main/tinyjev/agent.py"
click node_server "https://github.com/ankit-aglawe/tinyjev/blob/main/tinyjev/serve.py"
click node_cli "https://github.com/ankit-aglawe/tinyjev/blob/main/tinyjev/cli.py"
click node_registry "https://github.com/ankit-aglawe/tinyjev/blob/main/tinyjev/registry.py"
click node_conversion "https://github.com/ankit-aglawe/tinyjev/blob/main/tinyjev/convert.py"
click node_family_factory "https://github.com/ankit-aglawe/tinyjev/blob/main/tinyjev/families/__init__.py"
click node_marker "https://github.com/ankit-aglawe/tinyjev/blob/main/tinyjev/families/marker.py"
click node_pointer "https://github.com/ankit-aglawe/tinyjev/blob/main/tinyjev/families/pointer.py"
click node_mlx "https://github.com/ankit-aglawe/tinyjev/blob/main/tinyjev/backends/mlx_backend.py"
click node_torch "https://github.com/ankit-aglawe/tinyjev/blob/main/tinyjev/backends/torch_backend.py"
click node_results "https://github.com/ankit-aglawe/tinyjev/blob/main/tinyjev/agent.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_cli,node_http_client toneBlue
class node_agent,node_results toneAmber
class node_family_factory,node_marker,node_pointer,node_mlx,node_torch toneMint
class node_registry,node_conversion toneRose
class node_python_user,node_hub toneIndigo
```

## Components

### User interfaces

- [Local HTTP server](https://github.com/ankit-aglawe/tinyjev/blob/main/tinyjev/serve.py): `tinyjev/serve.py`
- [CLI](https://github.com/ankit-aglawe/tinyjev/blob/main/tinyjev/cli.py): `tinyjev/cli.py`

### Decision runtime

- [Agent API](https://github.com/ankit-aglawe/tinyjev/blob/main/tinyjev/agent.py): `tinyjev/agent.py`
- [Decision results](https://github.com/ankit-aglawe/tinyjev/blob/main/tinyjev/agent.py): `tinyjev/agent.py`

### Model execution

- [Family factory](https://github.com/ankit-aglawe/tinyjev/blob/main/tinyjev/families/__init__.py): `tinyjev/families/__init__.py`
- [Marker family](https://github.com/ankit-aglawe/tinyjev/blob/main/tinyjev/families/marker.py): `tinyjev/families/marker.py`
- [Pointer family](https://github.com/ankit-aglawe/tinyjev/blob/main/tinyjev/families/pointer.py): `tinyjev/families/pointer.py`
- [MLX backend](https://github.com/ankit-aglawe/tinyjev/blob/main/tinyjev/backends/mlx_backend.py): `tinyjev/backends/mlx_backend.py`
- [PyTorch backend](https://github.com/ankit-aglawe/tinyjev/blob/main/tinyjev/backends/torch_backend.py): `tinyjev/backends/torch_backend.py`

### Checkpoint lifecycle

- [Model registry](https://github.com/ankit-aglawe/tinyjev/blob/main/tinyjev/registry.py): `tinyjev/registry.py`
- [Checkpoint conversion](https://github.com/ankit-aglawe/tinyjev/blob/main/tinyjev/convert.py): `tinyjev/convert.py`

### Other components

- **Python caller**
- **HTTP client**
- **Model weights**

## Connections

- Python caller → Agent API: calls predict
- HTTP client → Local HTTP server: sends request
- CLI → Model registry: loads model
- CLI → Local HTTP server: starts server
- Local HTTP server → Agent API: dispatches predict
- Local HTTP server → Agent API: dispatches System One
- Agent API → Family factory: creates family
- Agent API → MLX backend: selects backend
- Agent API → PyTorch backend: selects backend
- Agent API → Marker family: encodes and scores
- Agent API → Pointer family: encodes and scores
- Agent API → Decision results: formats probabilities
- Model registry → Model weights: fetches weights
- Checkpoint conversion → Model weights: converts checkpoints