# lily-lipton/ollama-sandbox architecture

> Architecture diagram of the GitHub repository lily-lipton/ollama-sandbox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lily-lipton/ollama-sandbox
- Repository: https://github.com/lily-lipton/ollama-sandbox

## Overview

##### Project type and purpose
- From the README (“ollama-sandbox: For fine-tuning verification of LLMs”), we infer this is a specialized tooling project (likely a CLI and/or web-based sandbox) whose primary function is to orchestrate, manage, and verify the fine-tuning process for large language models.

##### (minimal) file structure
- With only README.md present, we assume a lightweight repo that either pulls in submodules or dynamically generates its structure at run-time. The lack of nested folders suggests a modular design that may be spun up or scaffolded by commands (e.g., “init,” “train,” “eval”).
- Expect hidden folders or dynamically created directories once components are scaffolded (e.g., “data/,” “models/,” “logs/,” “src/”).

##### README for additional insights
- The README’s one-liner shows no explicit tech stack, but common LLM fine-tuning verification tools leverage Python, Docker, REST/gRPC, experiment-tracking frameworks (e.g., MLflow), and often provide both a CLI and HTTP API or simple web UI.

##### Main components
a. Sandbox Orchestrator (core CLI or API server) – coordinates all workflows
b. Dataset Manager – handles ingestion, preprocessing, versioning
c. Fine-Tuning Engine – invokes training jobs (local GPU or cloud)
d. LLM Service Connector – interface to the base/pre-trained model (local or external API)
e. Evaluation Engine – runs metrics, benchmarks, runs verification tests
f. Experiment Tracker / Metadata Store – records hyperparameters, logs, results (e.g., MLflow, SQLite, or Postgres)
g. Artifacts Storage – stores datasets, checkpoints, logs (local FS, S3, or equivalent)
h. (Optional) Web UI / Dashboard – visualizes progress, metrics, comparisons
i. (Optional) Scheduler / Worker Pool – if using asynchronous or distributed training

##### Relationships and interactions
- The UI or CLI sends commands to the Sandbox Orchestrator
- The Orchestrator calls Dataset Manager (read/write datasets → Artifacts Storage)
- The Orchestrator invokes the Fine-Tuning Engine, passing dataset pointers and hyperparameters
- The Fine-Tuning Engine pulls the base model via the LLM Service Connector, runs training, writes checkpoints back to Artifacts Storage, and logs metrics to the Experiment Tracker
- The Orchestrator triggers the Evaluation Engine once training completes; evaluation results are stored in the Experiment Tracker
- The Web UI queries the Experiment Tracker and Artifacts Storage to display experiment details

##### Architectural patterns and design principles
- Modular pipeline: each stage (data, training, evaluation) is a separate component
- Single orchestration point (the CLI/API server) to simplify coordination and error handling
- Separation of concerns: storage (data & artifacts) vs. compute (training & evaluation) vs. presentation (UI/CLI)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Interface Layer
    subgraph "Interface Layer"
        UI["Web UI / Dashboard"]:::interface
        CLI["CLI / API Server\n(Sandbox Orchestrator)"]:::interface
    end

    %% Ingestion & Preprocessing
    subgraph "Ingestion & Preprocessing"
        DM["Dataset Manager"]:::compute
    end

    %% Training Components
    subgraph "Training"
        FT["Fine-Tuning Engine"]:::compute
        LLM["LLM Service Connector"]:::external
    end

    %% Storage Layer
    subgraph "Storage Layer"
        AS[(Artifacts Storage)]:::storage
        ET[(Experiment Tracker)]:::storage
    end

    %% Evaluation Components
    subgraph "Evaluation"
        EE["Evaluation Engine"]:::compute
    end

    %% Scheduler / Worker Pool
    subgraph "Scheduler"
        Sched["Scheduler / Worker Pool"]:::compute
    end

    %% Connections
    CLI -->|"dataset request"| DM
    DM -->|"dataset pointer"| CLI

    CLI -->|"train job request"| FT
    FT -->|"load base model"| LLM
    FT -->|"checkpoint"| AS
    FT -->|"metrics"| ET

    CLI -->|"run evaluation"| EE
    AS -->|"checkpoints"| EE
    ET -->|"metrics & logs"| EE

    CLI -->|"dispatch"| Sched
    Sched -.-> FT
    Sched -.-> EE

    UI -->|"query metrics"| ET
    UI -->|"query artifacts"| AS

    %% Styles
    classDef interface fill:#FFA500,stroke:#333,stroke-width:1px
    classDef compute fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef storage fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
