# makazhanalpamys/soup architecture

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

- Interactive diagram: https://gitdiagram.com/makazhanalpamys/soup
- Repository: https://github.com/makazhanalpamys/soup

## Overview

Soup is a command-line LLM fine-tuning and post-training product, with a local Web UI and optional integrations. Its principal workflow is user supplies a configuration and training data, then invokes training to produce a tuned model; the repository also exposes data preparation, evaluation, serving, model management, trace ingestion, and automation capabilities. The graph includes indexed core modules and documented features. Edges are limited to relationships visible in the excerpts/index or README; unsampled wiring is not inferred.

Main entry points: [`src/soup_cli/cli.py`](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/cli.py) (Soup CLI), [`src/soup_cli/trainer/dispatch.py`](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/trainer/dispatch.py) (Trainer Runtime), [`src/soup_cli/ui/app.py`](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/ui/app.py) (Web UI), [`src/soup_cli/commands/ingest.py`](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/commands/ingest.py) (Trace Ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Entry"]
  node_cli["Soup CLI<br/>[cli.py]"]
  node_webui["Web UI<br/>[app.py]"]
  node_terminal["Terminal Helpers<br/>[terminal.py]"]
end

subgraph group_data["Data and Config"]
  node_config["Config Schema<br/>[schema.py]"]
  node_data_cmd["Data Commands<br/>[data.py]"]
  node_data_pipeline["Data Pipeline<br/>[data_pipeline.py]"]
  node_data_loader["Training Data Loader<br/>[loader.py]"]
  node_trace_ingest["Trace Ingestion<br/>[ingest.py]"]
  node_trace_parsers["Trace Parsers<br/>[ingest_sources.py]"]
  node_paths["Path Safety<br/>[paths.py]"]
end

subgraph group_training["Training Runtime"]
  node_training["Trainer Runtime<br/>[dispatch.py]"]
  node_gpu["GPU Sizing<br/>[gpu.py]"]
  node_layer_stream["Layer Streaming<br/>[layer_stream.py]"]
  node_precision["Mixed Precision<br/>[mixed_precision.py]"]
  node_quant["Quantization<br/>[quant_menu.py]"]
  node_deepspeed["DeepSpeed Support<br/>[deepspeed.py]"]
  node_mole_trainer["MoLE Trainer<br/>[mole_routing.py]"]
  node_mole_runtime["MoLE Routing<br/>[mole_routing.py]"]
  node_v028["Compatibility Features<br/>[v028_features.py]"]
end

subgraph group_operations["Model Operations"]
  node_eval["Evaluation"]
  node_serve["Model Serving<br/>[serve.py]"]
  node_registry[("Model Registry<br/>[store.py]")]
  node_autodistill["Auto-Distillation<br/>[mlx_worker.py]"]
  node_autopilot["Autopilot<br/>[autopilot.py]"]
  node_provenance["Run Provenance<br/>[run_provenance.py]"]
  node_recipe["Recipe Catalog<br/>[catalog.py]"]
  node_eval_schedule["Eval Scheduling<br/>[eval_schedule.py]"]
end

subgraph group_integrations["Extensions"]
  node_mcp["MCP Server<br/>[server.py]"]
  node_cloud["Cloud Backends"]
  node_net_guard["Network Guard<br/>[net_guard.py]"]
end

node_user(("Engineer"))

node_user -->|"runs commands"| node_cli
node_cli -->|"registers"| node_data_cmd
node_cli -->|"registers"| node_webui
node_cli -->|"registers"| node_trace_ingest
node_user -->|"configures"| node_config
node_user -->|"starts training"| node_training
node_training -->|"reads schema"| node_config
node_training -->|"uses sizing"| node_gpu
node_training -->|"uses streaming"| node_layer_stream
node_training -->|"uses precision"| node_precision
node_training -->|"uses quantization"| node_quant
node_training -->|"uses backend"| node_deepspeed
node_training -->|"records run"| node_provenance
node_mole_trainer -->|"uses routing"| node_mole_runtime
node_data_cmd -.->|"supports data work"| node_data_pipeline
node_data_cmd -.->|"validates paths"| node_paths
node_trace_ingest -->|"parses sources"| node_trace_parsers
node_trace_ingest -->|"checks containment"| node_paths
node_trace_ingest -.->|"pulls securely"| node_net_guard
node_webui -->|"loads config"| node_config
node_webui -->|"loads data"| node_data_loader
node_webui -->|"reads recipes"| node_recipe
node_webui -->|"tracks runs"| node_registry
node_cli -.->|"registers commands"| node_eval
node_cli -.->|"registers command"| node_serve
node_cli -->|"registers commands"| node_registry
node_cli -->|"registers command"| node_autopilot
node_cli -->|"registers command"| node_mcp
node_cli -.->|"offers backends"| node_cloud
node_training -->|"schedules evaluation"| node_eval_schedule
node_training -->|"uses compatibility"| node_v028

click node_cli "https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/cli.py"
click node_webui "https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/ui/app.py"
click node_config "https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/config/schema.py"
click node_data_cmd "https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/commands/data.py"
click node_data_pipeline "https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/utils/data_pipeline.py"
click node_data_loader "https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/data/loader.py"
click node_trace_ingest "https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/commands/ingest.py"
click node_trace_parsers "https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/utils/ingest_sources.py"
click node_training "https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/trainer/dispatch.py"
click node_gpu "https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/utils/gpu.py"
click node_layer_stream "https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/utils/layer_stream.py"
click node_precision "https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/utils/mixed_precision.py"
click node_quant "https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/utils/quant_menu.py"
click node_deepspeed "https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/utils/deepspeed.py"
click node_mole_trainer "https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/trainer/mole_routing.py"
click node_mole_runtime "https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/utils/mole_routing.py"
click node_eval "https://github.com/makazhanalpamys/soup/tree/main/src/soup_cli/eval"
click node_serve "https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/commands/serve.py"
click node_registry "https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/registry/store.py"
click node_autodistill "https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/autodistill/mlx_worker.py"
click node_autopilot "https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/commands/autopilot.py"
click node_provenance "https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/utils/run_provenance.py"
click node_recipe "https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/recipes/catalog.py"
click node_mcp "https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/mcp_server/server.py"
click node_cloud "https://github.com/makazhanalpamys/soup/tree/main/src/soup_cli/cloud"
click node_net_guard "https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/utils/net_guard.py"
click node_paths "https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/utils/paths.py"
click node_eval_schedule "https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/utils/eval_schedule.py"
click node_terminal "https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/utils/terminal.py"
click node_v028 "https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/utils/v028_features.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_cli,node_webui,node_terminal toneBlue
class node_config,node_data_cmd,node_data_pipeline,node_data_loader,node_trace_ingest,node_trace_parsers,node_paths toneAmber
class node_training,node_gpu,node_layer_stream,node_precision,node_quant,node_deepspeed,node_mole_trainer,node_mole_runtime,node_v028 toneMint
class node_eval,node_serve,node_registry,node_autodistill,node_autopilot,node_provenance,node_recipe,node_eval_schedule toneRose
class node_mcp,node_cloud,node_net_guard,node_user toneIndigo
```

## Components

### User Entry

- [Soup CLI](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/cli.py): `src/soup_cli/cli.py`
- [Web UI](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/ui/app.py): `src/soup_cli/ui/app.py`
- [Terminal Helpers](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/utils/terminal.py): `src/soup_cli/utils/terminal.py`

### Data and Config

- [Config Schema](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/config/schema.py): `src/soup_cli/config/schema.py`
- [Data Commands](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/commands/data.py): `src/soup_cli/commands/data.py`
- [Data Pipeline](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/utils/data_pipeline.py): `src/soup_cli/utils/data_pipeline.py`
- [Training Data Loader](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/data/loader.py): `src/soup_cli/data/loader.py`
- [Trace Ingestion](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/commands/ingest.py): `src/soup_cli/commands/ingest.py`
- [Trace Parsers](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/utils/ingest_sources.py): `src/soup_cli/utils/ingest_sources.py`
- [Path Safety](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/utils/paths.py): `src/soup_cli/utils/paths.py`

### Training Runtime

- [Trainer Runtime](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/trainer/dispatch.py): `src/soup_cli/trainer/dispatch.py`
- [GPU Sizing](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/utils/gpu.py): `src/soup_cli/utils/gpu.py`
- [Layer Streaming](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/utils/layer_stream.py): `src/soup_cli/utils/layer_stream.py`
- [Mixed Precision](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/utils/mixed_precision.py): `src/soup_cli/utils/mixed_precision.py`
- [Quantization](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/utils/quant_menu.py): `src/soup_cli/utils/quant_menu.py`
- [DeepSpeed Support](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/utils/deepspeed.py): `src/soup_cli/utils/deepspeed.py`
- [MoLE Trainer](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/trainer/mole_routing.py): `src/soup_cli/trainer/mole_routing.py`
- [MoLE Routing](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/utils/mole_routing.py): `src/soup_cli/utils/mole_routing.py`
- [Compatibility Features](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/utils/v028_features.py): `src/soup_cli/utils/v028_features.py`

### Model Operations

- [Evaluation](https://github.com/makazhanalpamys/soup/tree/main/src/soup_cli/eval): `src/soup_cli/eval`
- [Model Serving](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/commands/serve.py): `src/soup_cli/commands/serve.py`
- [Model Registry](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/registry/store.py): `src/soup_cli/registry/store.py`
- [Auto-Distillation](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/autodistill/mlx_worker.py): `src/soup_cli/autodistill/mlx_worker.py`
- [Autopilot](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/commands/autopilot.py): `src/soup_cli/commands/autopilot.py`
- [Run Provenance](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/utils/run_provenance.py): `src/soup_cli/utils/run_provenance.py`
- [Recipe Catalog](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/recipes/catalog.py): `src/soup_cli/recipes/catalog.py`
- [Eval Scheduling](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/utils/eval_schedule.py): `src/soup_cli/utils/eval_schedule.py`

### Extensions

- [MCP Server](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/mcp_server/server.py): `src/soup_cli/mcp_server/server.py`
- [Cloud Backends](https://github.com/makazhanalpamys/soup/tree/main/src/soup_cli/cloud): `src/soup_cli/cloud`
- [Network Guard](https://github.com/makazhanalpamys/soup/blob/main/src/soup_cli/utils/net_guard.py): `src/soup_cli/utils/net_guard.py`

### Other components

- **Engineer**

## Connections

- Engineer → Soup CLI: runs commands (evidence: `README.md`)
- Soup CLI → Data Commands: registers (evidence: `src/soup_cli/cli.py`)
- Soup CLI → Web UI: registers (evidence: `src/soup_cli/cli.py`)
- Soup CLI → Trace Ingestion: registers (evidence: `src/soup_cli/cli.py`)
- Engineer → Config Schema: configures (evidence: `README.md`)
- Engineer → Trainer Runtime: starts training (evidence: `README.md`)
- Trainer Runtime → Config Schema: reads schema
- Trainer Runtime → GPU Sizing: uses sizing
- Trainer Runtime → Layer Streaming: uses streaming
- Trainer Runtime → Mixed Precision: uses precision
- Trainer Runtime → Quantization: uses quantization
- Trainer Runtime → DeepSpeed Support: uses backend
- Trainer Runtime → Run Provenance: records run
- MoLE Trainer → MoLE Routing: uses routing (evidence: `src/soup_cli/trainer/mole_routing.py`)
- Data Commands → Data Pipeline: supports data work
- Data Commands → Path Safety: validates paths
- Trace Ingestion → Trace Parsers: parses sources (evidence: `src/soup_cli/commands/ingest.py`)
- Trace Ingestion → Path Safety: checks containment (evidence: `src/soup_cli/commands/ingest.py`)
- Trace Ingestion → Network Guard: pulls securely
- Web UI → Config Schema: loads config (evidence: `src/soup_cli/ui/app.py`)
- Web UI → Training Data Loader: loads data (evidence: `src/soup_cli/ui/app.py`)
- Web UI → Recipe Catalog: reads recipes (evidence: `src/soup_cli/ui/app.py`)
- Web UI → Model Registry: tracks runs (evidence: `src/soup_cli/ui/app.py`)
- Soup CLI → Evaluation: registers commands
- Soup CLI → Model Serving: registers command (evidence: `src/soup_cli/cli.py`)
- Soup CLI → Model Registry: registers commands (evidence: `src/soup_cli/cli.py`)
- Soup CLI → Autopilot: registers command (evidence: `src/soup_cli/cli.py`)
- Soup CLI → MCP Server: registers command (evidence: `src/soup_cli/cli.py`)
- Soup CLI → Cloud Backends: offers backends
- Trainer Runtime → Eval Scheduling: schedules evaluation
- Trainer Runtime → Compatibility Features: uses compatibility