# zgsndzq/superai architecture

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

- Interactive diagram: https://gitdiagram.com/zgsndzq/superai
- Repository: https://github.com/zgsndzq/superai

## Overview

SuperAI is a Python idiom-chain model and chat application: users can train and evaluate a ternary idiom engine, play chain-prediction workflows, or chat through a router that selects idiom, calculation, or general-language experts. The graph includes the documented CLI capabilities and separates router training from interactive inference. Relationships are limited to calls shown in excerpts, source-index references, or README statements; unsampled command internals are not inferred.

Main entry points: [`cli/app.py`](https://github.com/zgsndzq/superai/blob/main/cli/app.py) (Command dispatch), [`core/moe.py`](https://github.com/zgsndzq/superai/blob/main/core/moe.py) (MoE chat and dispatch), [`cli/fused_train_cmd.py`](https://github.com/zgsndzq/superai/blob/main/cli/fused_train_cmd.py) (Router training command), [`cli/eval_cmd.py`](https://github.com/zgsndzq/superai/blob/main/cli/eval_cmd.py) (Evaluation command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and interaction"]
  node_entrypoint["Python entry<br/>[llm.py]"]
  node_cli_dispatch["Command dispatch<br/>[app.py]"]
  node_chat_cli["Base chat command<br/>[chat_cmd.py]"]
  node_fused_chat["Fused chat command<br/>[fused_chat_cmd.py]"]
  node_train_cli["Train command<br/>[train_cmd.py]"]
  node_test_cli["Test command<br/>[test_cmd.py]"]
  node_eval_cli["Evaluation command<br/>[eval_cmd.py]"]
  node_fused_train_cli["Router training command<br/>[fused_train_cmd.py]"]
end

subgraph group_chain["Idiom engine"]
  node_idiom_data["Idiom vocabulary and pairs<br/>[data.py]"]
  node_chain_model["Idiom chain model<br/>[model.py]"]
  node_ternary_layer["Ternary linear layer<br/>[ternary.py]"]
  node_chain_training["Chain training and export<br/>[trainer.py]"]
  node_chain_inference["Chain inference<br/>[infer.py]"]
end

subgraph group_routing["Router and experts"]
  node_moe["MoE chat and dispatch<br/>[moe.py]"]
  node_router["Ternary router<br/>[ternary.py]"]
  node_chain_expert["Idiom-chain expert<br/>[moe.py]"]
  node_calc_expert["Calculation expert<br/>[calc.py]"]
  node_qwen_expert["General Qwen expert<br/>[moe.py]"]
end

subgraph group_analysis["Training and evaluation"]
  node_evaluation["Model evaluation<br/>[eval_cmd.py]"]
end

node_user(("User"))
node_qwen_model["Qwen base model"]

node_user -->|"runs commands"| node_entrypoint
node_entrypoint -->|"invokes"| node_cli_dispatch
node_cli_dispatch -->|"dispatches"| node_chat_cli
node_cli_dispatch -->|"dispatches"| node_fused_chat
node_cli_dispatch -->|"dispatches"| node_train_cli
node_cli_dispatch -->|"dispatches"| node_test_cli
node_cli_dispatch -->|"dispatches"| node_eval_cli
node_cli_dispatch -->|"dispatches"| node_fused_train_cli
node_train_cli -->|"starts training"| node_chain_training
node_chain_training -->|"loads and builds pairs"| node_idiom_data
node_chain_training -->|"trains"| node_chain_model
node_chain_model -->|"uses layers"| node_ternary_layer
node_test_cli -->|"supports play workflow"| node_chain_inference
node_chain_inference -->|"loads checkpoint model"| node_chain_model
node_eval_cli -->|"builds evaluation pairs"| node_idiom_data
node_eval_cli -->|"loads and scores models"| node_chain_inference
node_eval_cli -->|"uses compression stats"| node_chain_training
node_fused_train_cli -->|"builds router samples"| node_idiom_data
node_fused_train_cli -->|"constructs MoE"| node_moe
node_fused_train_cli -->|"encodes samples"| node_qwen_model
node_fused_train_cli -->|"trains router weights"| node_router
node_fused_chat -->|"loads and chats"| node_moe
node_moe -->|"encodes and generates"| node_qwen_model
node_moe -->|"routes hidden state"| node_router
node_moe -->|"dispatches chain requests"| node_chain_expert
node_moe -->|"calls calculation helpers"| node_calc_expert
node_moe -->|"falls back to generation"| node_qwen_expert
node_chain_expert -->|"predicts valid continuations"| node_chain_inference
node_router -->|"uses ternary layer"| node_ternary_layer

click node_entrypoint "https://github.com/zgsndzq/superai/blob/main/llm.py"
click node_cli_dispatch "https://github.com/zgsndzq/superai/blob/main/cli/app.py"
click node_chat_cli "https://github.com/zgsndzq/superai/blob/main/cli/chat_cmd.py"
click node_fused_chat "https://github.com/zgsndzq/superai/blob/main/cli/fused_chat_cmd.py"
click node_train_cli "https://github.com/zgsndzq/superai/blob/main/cli/train_cmd.py"
click node_test_cli "https://github.com/zgsndzq/superai/blob/main/cli/test_cmd.py"
click node_eval_cli "https://github.com/zgsndzq/superai/blob/main/cli/eval_cmd.py"
click node_fused_train_cli "https://github.com/zgsndzq/superai/blob/main/cli/fused_train_cmd.py"
click node_idiom_data "https://github.com/zgsndzq/superai/blob/main/core/data.py"
click node_chain_model "https://github.com/zgsndzq/superai/blob/main/core/model.py"
click node_ternary_layer "https://github.com/zgsndzq/superai/blob/main/core/ternary.py"
click node_chain_training "https://github.com/zgsndzq/superai/blob/main/core/trainer.py"
click node_chain_inference "https://github.com/zgsndzq/superai/blob/main/core/infer.py"
click node_moe "https://github.com/zgsndzq/superai/blob/main/core/moe.py"
click node_router "https://github.com/zgsndzq/superai/blob/main/core/ternary.py"
click node_chain_expert "https://github.com/zgsndzq/superai/blob/main/core/moe.py"
click node_calc_expert "https://github.com/zgsndzq/superai/blob/main/core/calc.py"
click node_qwen_expert "https://github.com/zgsndzq/superai/blob/main/core/moe.py"
click node_evaluation "https://github.com/zgsndzq/superai/blob/main/cli/eval_cmd.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_entrypoint,node_cli_dispatch,node_chat_cli,node_fused_chat,node_train_cli,node_test_cli,node_eval_cli,node_fused_train_cli,node_user toneBlue
class node_idiom_data,node_chain_model,node_ternary_layer,node_chain_training,node_chain_inference toneAmber
class node_moe,node_router,node_chain_expert,node_calc_expert,node_qwen_expert toneMint
class node_evaluation toneRose
class node_qwen_model toneIndigo
```

## Components

### CLI and interaction

- [Python entry](https://github.com/zgsndzq/superai/blob/main/llm.py): `llm.py`
- [Command dispatch](https://github.com/zgsndzq/superai/blob/main/cli/app.py): `cli/app.py`
- [Base chat command](https://github.com/zgsndzq/superai/blob/main/cli/chat_cmd.py): `cli/chat_cmd.py`
- [Fused chat command](https://github.com/zgsndzq/superai/blob/main/cli/fused_chat_cmd.py): `cli/fused_chat_cmd.py`
- [Train command](https://github.com/zgsndzq/superai/blob/main/cli/train_cmd.py): `cli/train_cmd.py`
- [Test command](https://github.com/zgsndzq/superai/blob/main/cli/test_cmd.py): `cli/test_cmd.py`
- [Evaluation command](https://github.com/zgsndzq/superai/blob/main/cli/eval_cmd.py): `cli/eval_cmd.py`
- [Router training command](https://github.com/zgsndzq/superai/blob/main/cli/fused_train_cmd.py): `cli/fused_train_cmd.py`

### Idiom engine

- [Idiom vocabulary and pairs](https://github.com/zgsndzq/superai/blob/main/core/data.py): `core/data.py`
- [Idiom chain model](https://github.com/zgsndzq/superai/blob/main/core/model.py): `core/model.py`
- [Ternary linear layer](https://github.com/zgsndzq/superai/blob/main/core/ternary.py): `core/ternary.py`
- [Chain training and export](https://github.com/zgsndzq/superai/blob/main/core/trainer.py): `core/trainer.py`
- [Chain inference](https://github.com/zgsndzq/superai/blob/main/core/infer.py): `core/infer.py`

### Router and experts

- [MoE chat and dispatch](https://github.com/zgsndzq/superai/blob/main/core/moe.py): `core/moe.py`
- [Ternary router](https://github.com/zgsndzq/superai/blob/main/core/ternary.py): `core/ternary.py`
- [Idiom-chain expert](https://github.com/zgsndzq/superai/blob/main/core/moe.py): `core/moe.py`
- [Calculation expert](https://github.com/zgsndzq/superai/blob/main/core/calc.py): `core/calc.py`
- [General Qwen expert](https://github.com/zgsndzq/superai/blob/main/core/moe.py): `core/moe.py`

### Training and evaluation

- [Model evaluation](https://github.com/zgsndzq/superai/blob/main/cli/eval_cmd.py): `cli/eval_cmd.py`

### Other components

- **User**
- **Qwen base model**

## Connections

- User → Python entry: runs commands (evidence: `README.md`)
- Python entry → Command dispatch: invokes (evidence: `llm.py`)
- Command dispatch → Base chat command: dispatches (evidence: `cli/app.py`)
- Command dispatch → Fused chat command: dispatches (evidence: `cli/app.py`)
- Command dispatch → Train command: dispatches (evidence: `cli/app.py`)
- Command dispatch → Test command: dispatches (evidence: `cli/app.py`)
- Command dispatch → Evaluation command: dispatches (evidence: `cli/app.py`)
- Command dispatch → Router training command: dispatches (evidence: `cli/app.py`)
- Train command → Chain training and export: starts training (evidence: `cli/train_cmd.py`)
- Chain training and export → Idiom vocabulary and pairs: loads and builds pairs (evidence: `core/trainer.py`)
- Chain training and export → Idiom chain model: trains (evidence: `core/trainer.py`)
- Idiom chain model → Ternary linear layer: uses layers (evidence: `core/model.py`)
- Test command → Chain inference: supports play workflow (evidence: `README.md`)
- Chain inference → Idiom chain model: loads checkpoint model (evidence: `core/infer.py`)
- Evaluation command → Idiom vocabulary and pairs: builds evaluation pairs (evidence: `cli/eval_cmd.py`)
- Evaluation command → Chain inference: loads and scores models (evidence: `cli/eval_cmd.py`)
- Evaluation command → Chain training and export: uses compression stats (evidence: `cli/eval_cmd.py`)
- Router training command → Idiom vocabulary and pairs: builds router samples (evidence: `cli/fused_train_cmd.py`)
- Router training command → MoE chat and dispatch: constructs MoE (evidence: `cli/fused_train_cmd.py`)
- Router training command → Qwen base model: encodes samples (evidence: `cli/fused_train_cmd.py`)
- Router training command → Ternary router: trains router weights (evidence: `cli/fused_train_cmd.py`)
- Fused chat command → MoE chat and dispatch: loads and chats (evidence: `cli/fused_chat_cmd.py`)
- MoE chat and dispatch → Qwen base model: encodes and generates (evidence: `core/moe.py`)
- MoE chat and dispatch → Ternary router: routes hidden state (evidence: `core/moe.py`)
- MoE chat and dispatch → Idiom-chain expert: dispatches chain requests (evidence: `core/moe.py`)
- MoE chat and dispatch → Calculation expert: calls calculation helpers (evidence: `core/moe.py`)
- MoE chat and dispatch → General Qwen expert: falls back to generation (evidence: `core/moe.py`)
- Idiom-chain expert → Chain inference: predicts valid continuations (evidence: `core/moe.py`)
- Ternary router → Ternary linear layer: uses ternary layer (evidence: `core/moe.py`)