# sakib75x/soup architecture

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

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

## Overview

Soup is a CLI and Web UI for configuring, fine-tuning, evaluating, and serving LLMs, with data preparation, model export, and operational tooling. The documented primary workflow is to initialize a configuration, then train; the broader source tree also exposes ingestion, evaluation, deployment, recipe, and interoperability features. The graph preserves these major product areas, but many command implementations were not sampled, so their internal call paths are left unverified rather than inferred.

Main entry points: [`src/soup_cli/cli.py`](https://github.com/sakib75x/soup/blob/main/src/soup_cli/cli.py) (Soup CLI), [`src/soup_cli/ui/app.py`](https://github.com/sakib75x/soup/blob/main/src/soup_cli/ui/app.py) (Web UI), [`src/soup_cli/commands/train.py`](https://github.com/sakib75x/soup/blob/main/src/soup_cli/commands/train.py) (Training Command), [`src/soup_cli/commands/ingest.py`](https://github.com/sakib75x/soup/blob/main/src/soup_cli/commands/ingest.py) (Trace Ingest)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_cli["Soup CLI<br/>[cli.py]"]
  node_web_ui["Web UI<br/>[app.py]"]
end

subgraph group_data["Data Preparation"]
  node_data_commands["Data Commands<br/>[data.py]"]
  node_ingest_command["Trace Ingest<br/>[ingest.py]"]
  node_ingest_adapters["Trace Adapters<br/>[ingest_sources.py]"]
  node_ingest_pull["Langfuse Pull<br/>[ingest_pull.py]"]
  node_data_loader["Dataset Loader<br/>[loader.py]"]
  node_data_formats["Data Formats<br/>[formats.py]"]
end

subgraph group_training["Training Runtime"]
  node_config["Configuration<br/>[schema.py]"]
  node_train_command["Training Command<br/>[train.py]"]
  node_trainer["Trainer Dispatch<br/>[dispatch.py]"]
  node_embedding_trainer["Embedding Trainer<br/>[embedding.py]"]
  node_mole_trainer["MoLE Trainer<br/>[mole_routing.py]"]
  node_layer_stream["Layer Streaming<br/>[layer_stream.py]"]
end

subgraph group_model_ops["Model Operations"]
  node_eval["Evaluation"]
  node_recipes[("Recipe Catalog<br/>[catalog.py]")]
  node_export["Model Export<br/>[export.py]"]
end

subgraph group_integration["Serving and Integration"]
  node_serve["Model Serving<br/>[serve.py]"]
  node_mcp["MCP Server<br/>[server.py]"]
  node_webhooks["Webhook Delivery<br/>[webhooks.py]"]
end

node_user(("Engineer"))
node_langfuse(("Langfuse"))

node_user -->|"runs commands"| node_cli
node_cli -->|"dispatches"| node_train_command
node_cli -->|"dispatches"| node_data_commands
node_cli -->|"dispatches"| node_serve
node_cli -->|"dispatches"| node_export
node_user -->|"uses"| node_web_ui
node_web_ui -->|"lists templates"| node_config
node_web_ui -->|"loads datasets"| node_data_loader
node_web_ui -->|"reads recipes"| node_recipes
node_ingest_command -->|"normalizes traces"| node_ingest_adapters
node_ingest_command -->|"pulls traces"| node_ingest_pull
node_ingest_pull -->|"requests generations"| node_langfuse
node_data_loader -->|"uses formats"| node_data_formats
node_train_command -.->|"loads config"| node_config
node_train_command -.->|"loads training data"| node_data_loader
node_train_command -.->|"starts training"| node_trainer
node_trainer -.->|"selects task trainer"| node_embedding_trainer
node_trainer -.->|"selects task trainer"| node_mole_trainer
node_embedding_trainer -->|"uses streaming"| node_layer_stream
node_user -.->|"evaluates models"| node_eval
node_user -.->|"browses recipes"| node_recipes
node_user -.->|"connects tools"| node_mcp
node_ingest_command -->|"notifies optionally"| node_webhooks

click node_cli "https://github.com/sakib75x/soup/blob/main/src/soup_cli/cli.py"
click node_web_ui "https://github.com/sakib75x/soup/blob/main/src/soup_cli/ui/app.py"
click node_config "https://github.com/sakib75x/soup/blob/main/src/soup_cli/config/schema.py"
click node_data_commands "https://github.com/sakib75x/soup/blob/main/src/soup_cli/commands/data.py"
click node_ingest_command "https://github.com/sakib75x/soup/blob/main/src/soup_cli/commands/ingest.py"
click node_ingest_adapters "https://github.com/sakib75x/soup/blob/main/src/soup_cli/utils/ingest_sources.py"
click node_ingest_pull "https://github.com/sakib75x/soup/blob/main/src/soup_cli/utils/ingest_pull.py"
click node_data_loader "https://github.com/sakib75x/soup/blob/main/src/soup_cli/data/loader.py"
click node_data_formats "https://github.com/sakib75x/soup/blob/main/src/soup_cli/data/formats.py"
click node_train_command "https://github.com/sakib75x/soup/blob/main/src/soup_cli/commands/train.py"
click node_trainer "https://github.com/sakib75x/soup/blob/main/src/soup_cli/trainer/dispatch.py"
click node_embedding_trainer "https://github.com/sakib75x/soup/blob/main/src/soup_cli/trainer/embedding.py"
click node_mole_trainer "https://github.com/sakib75x/soup/blob/main/src/soup_cli/trainer/mole_routing.py"
click node_layer_stream "https://github.com/sakib75x/soup/blob/main/src/soup_cli/utils/layer_stream.py"
click node_eval "https://github.com/sakib75x/soup/tree/main/src/soup_cli/eval"
click node_recipes "https://github.com/sakib75x/soup/blob/main/src/soup_cli/recipes/catalog.py"
click node_export "https://github.com/sakib75x/soup/blob/main/src/soup_cli/commands/export.py"
click node_serve "https://github.com/sakib75x/soup/blob/main/src/soup_cli/commands/serve.py"
click node_mcp "https://github.com/sakib75x/soup/blob/main/src/soup_cli/mcp_server/server.py"
click node_webhooks "https://github.com/sakib75x/soup/blob/main/src/soup_cli/utils/webhooks.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_web_ui toneBlue
class node_data_commands,node_ingest_command,node_ingest_adapters,node_ingest_pull,node_data_loader,node_data_formats toneAmber
class node_config,node_train_command,node_trainer,node_embedding_trainer,node_mole_trainer,node_layer_stream toneMint
class node_eval,node_recipes,node_export toneRose
class node_serve,node_mcp,node_webhooks,node_user,node_langfuse toneIndigo
```

## Components

### User Interfaces

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

### Data Preparation

- [Data Commands](https://github.com/sakib75x/soup/blob/main/src/soup_cli/commands/data.py): `src/soup_cli/commands/data.py`
- [Trace Ingest](https://github.com/sakib75x/soup/blob/main/src/soup_cli/commands/ingest.py): `src/soup_cli/commands/ingest.py`
- [Trace Adapters](https://github.com/sakib75x/soup/blob/main/src/soup_cli/utils/ingest_sources.py): `src/soup_cli/utils/ingest_sources.py`
- [Langfuse Pull](https://github.com/sakib75x/soup/blob/main/src/soup_cli/utils/ingest_pull.py): `src/soup_cli/utils/ingest_pull.py`
- [Dataset Loader](https://github.com/sakib75x/soup/blob/main/src/soup_cli/data/loader.py): `src/soup_cli/data/loader.py`
- [Data Formats](https://github.com/sakib75x/soup/blob/main/src/soup_cli/data/formats.py): `src/soup_cli/data/formats.py`

### Training Runtime

- [Configuration](https://github.com/sakib75x/soup/blob/main/src/soup_cli/config/schema.py): `src/soup_cli/config/schema.py`
- [Training Command](https://github.com/sakib75x/soup/blob/main/src/soup_cli/commands/train.py): `src/soup_cli/commands/train.py`
- [Trainer Dispatch](https://github.com/sakib75x/soup/blob/main/src/soup_cli/trainer/dispatch.py): `src/soup_cli/trainer/dispatch.py`
- [Embedding Trainer](https://github.com/sakib75x/soup/blob/main/src/soup_cli/trainer/embedding.py): `src/soup_cli/trainer/embedding.py`
- [MoLE Trainer](https://github.com/sakib75x/soup/blob/main/src/soup_cli/trainer/mole_routing.py): `src/soup_cli/trainer/mole_routing.py`
- [Layer Streaming](https://github.com/sakib75x/soup/blob/main/src/soup_cli/utils/layer_stream.py): `src/soup_cli/utils/layer_stream.py`

### Model Operations

- [Evaluation](https://github.com/sakib75x/soup/tree/main/src/soup_cli/eval): `src/soup_cli/eval`
- [Recipe Catalog](https://github.com/sakib75x/soup/blob/main/src/soup_cli/recipes/catalog.py): `src/soup_cli/recipes/catalog.py`
- [Model Export](https://github.com/sakib75x/soup/blob/main/src/soup_cli/commands/export.py): `src/soup_cli/commands/export.py`

### Serving and Integration

- [Model Serving](https://github.com/sakib75x/soup/blob/main/src/soup_cli/commands/serve.py): `src/soup_cli/commands/serve.py`
- [MCP Server](https://github.com/sakib75x/soup/blob/main/src/soup_cli/mcp_server/server.py): `src/soup_cli/mcp_server/server.py`
- [Webhook Delivery](https://github.com/sakib75x/soup/blob/main/src/soup_cli/utils/webhooks.py): `src/soup_cli/utils/webhooks.py`

### Other components

- **Engineer**
- **Langfuse**

## Connections

- Engineer → Soup CLI: runs commands (evidence: `README.md`)
- Soup CLI → Training Command: dispatches (evidence: `src/soup_cli/cli.py`)
- Soup CLI → Data Commands: dispatches (evidence: `src/soup_cli/cli.py`)
- Soup CLI → Model Serving: dispatches (evidence: `src/soup_cli/cli.py`)
- Soup CLI → Model Export: dispatches (evidence: `src/soup_cli/cli.py`)
- Engineer → Web UI: uses (evidence: `README.md`)
- Web UI → Configuration: lists templates (evidence: `src/soup_cli/ui/app.py`)
- Web UI → Dataset Loader: loads datasets (evidence: `src/soup_cli/ui/app.py`)
- Web UI → Recipe Catalog: reads recipes (evidence: `src/soup_cli/ui/app.py`)
- Trace Ingest → Trace Adapters: normalizes traces (evidence: `src/soup_cli/commands/ingest.py`)
- Trace Ingest → Langfuse Pull: pulls traces (evidence: `src/soup_cli/commands/ingest.py`)
- Langfuse Pull → Langfuse: requests generations (evidence: `src/soup_cli/utils/ingest_pull.py`)
- Dataset Loader → Data Formats: uses formats (evidence: `src/soup_cli/data/loader.py`)
- Training Command → Configuration: loads config
- Training Command → Dataset Loader: loads training data
- Training Command → Trainer Dispatch: starts training
- Trainer Dispatch → Embedding Trainer: selects task trainer
- Trainer Dispatch → MoLE Trainer: selects task trainer
- Embedding Trainer → Layer Streaming: uses streaming (evidence: `src/soup_cli/trainer/embedding.py`)
- Engineer → Evaluation: evaluates models
- Engineer → Recipe Catalog: browses recipes
- Engineer → MCP Server: connects tools
- Trace Ingest → Webhook Delivery: notifies optionally (evidence: `src/soup_cli/commands/ingest.py`)
