# sakanaai/text-to-lora architecture

> Architecture diagram of the GitHub repository sakanaai/text-to-lora, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sakanaai/text-to-lora
- Repository: https://github.com/sakanaai/text-to-lora

## Overview

##### Project Type & Purpose
- This is a research‐focused Python tool (“Text-to-LoRA”) for instantly adapting large language models via LoRA adapters.
- It provides both a CLI (scripts/) and a local Web UI (webui/app.py) to:
- Train new LoRA adapters via SFT or reconstruction
- Generate LoRA adapters from natural‐language task descriptions
- Evaluate adapters on benchmark tasks

##### High-Level Components
a. User Interfaces
- CLI Scripts (scripts/*.py, .sh): generate_lora.py, run_eval.py, train_* scripts, watcher.py
- Web UI (webui/app.py)
b. Core Libraries
- fishfarm (src/fishfarm/fishfarm): model abstractions (vLLM, LangChain), task loading, logging, chat_templates API
- hyper_llm_modulator (src/hyper_llm_modulator): LoRA mixing, SFT trainer, reconstruction trainer, evaluation hooks
c. Data & Config
- chat_templates/ (Jinja2 templates per base model)
- configs/*.yaml (hyperparams for reconstruction, tasks lists)
- tasks/*.yaml (metadata describing each evaluation dataset)
d. External Dependencies
- HuggingFace Hub (model and checkpoint downloads)
- vLLM & PyTorch/CUDA on GPUs
- `uv` for environment & task orchestration

##### Core Workflows & Interactions
a. LoRA Generation (CLI or Web UI)
1. UI → calls fishfarm.chat_templates to render a prompt from a natural‐language task description
2. Pass prompt to hyper_llm_modulator.hyper_modulator
3. Load base model (via model_loading), apply hyper‐network to generate LoRA weights
4. Write LoRA adapter files to local folder (trained_t2l/...)
5. Return file paths / UI response
b. SFT & Reconstruction Training
1. scripts/train_t2l_*.sh → invokes Python entrypoint (train_custom_sft.py or train_hyper_recon.py)
2. Data: loads many baseline LoRA adapters (oracle) or task descriptions + embeddings
3. Trainer uses hyper_llm_modulator.sft_trainer or recon_trainer → checkpoint LoRA models
4. watcher.py observes checkpoint directory → triggers evaluation
c. Evaluation
- scripts/run_eval.py / eval_* scripts read LoRA directories + tasks metadata → compute metrics → save results

##### Architectural Patterns & Design Principles
- Modular layering:
- UI layer (CLI/Web)
- Core library layer (fishfarm + hyper_llm_modulator)
- Data/config layer (YAML, templates, tasks)
- Plugin‐style tasks: tasks/*.yaml drive all evaluations uniformly
- Observer pattern in watcher.py for asynchronous validation
- Separation of concerns: model I/O, training logic, prompt rendering, and orchestration live in distinct modules

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces
    subgraph "User Interface Layer"
        CLI{CLI Scripts}:::ui
        WebUI{Browser/UI}:::ui
    end

    %% Core Libraries
    subgraph "Core Library Layer"
        FFF["fishfarm Core"]:::code
        HLM["hyper_llm_modulator"]:::code
    end

    %% Data & Config
    subgraph "Data & Configuration Layer"
        CT[(chat_templates)]:::data
        CFG[(configs/*.yaml)]:::data
        TM[(tasks metadata)]:::data
        ART[(LoRA Artifacts & Checkpoints)]:::data
        RES[(Evaluation Results)]:::data
    end

    %% External Dependencies
    subgraph "External Services"
        HF((HuggingFace Hub)):::external
        GPU((GPU Compute / vLLM & PyTorch)):::external
        UV((uv Orchestration)):::external
    end

    %% Workflows
    CLI -->|"render prompt"| FFF
    WebUI -->|"render prompt"| FFF
    FFF -->|"prompt→hyper_modulator"| HLM
    HLM -->|"download model"| HF
    HLM -->|"inference & LoRA mixing"| GPU
    HLM -->|"write .pt files"| ART
    FFF -->|"load templates"| CT
    FFF -->|"load tasks"| TM
    HLM -->|"load configs"| CFG
    ART -->|"trigger watcher"| CLI
    subgraph "Watcher & Evaluation Loop"
        WAT{"watcher.py"}:::code
        EVAL{"run_eval.py / eval_*"}:::code
        WAT -->|"detect checkpoint"| EVAL
        EVAL -->|"compute metrics"| RES
    end
    UV -->|"orchestrates tasks"| CLI

    %% Click Events
    click CLI "https://github.com/sakanaai/text-to-lora/blob/main/scripts/generate_lora.py"
    click CLI "https://github.com/sakanaai/text-to-lora/blob/main/scripts/run_eval.py"
    click CLI "https://github.com/sakanaai/text-to-lora/blob/main/scripts/train_custom_sft.py"
    click CLI "https://github.com/sakanaai/text-to-lora/blob/main/scripts/train_hyper_recon.py"
    click CLI "https://github.com/sakanaai/text-to-lora/blob/main/scripts/train_lora_baselines.py"
    click CLI "https://github.com/sakanaai/text-to-lora/blob/main/scripts/train_lora_baselines.sh"
    click CLI "https://github.com/sakanaai/text-to-lora/blob/main/scripts/train_mt_lora_baselines.sh"
    click CLI "https://github.com/sakanaai/text-to-lora/blob/main/scripts/train_t2l_gemma.sh"
    click CLI "https://github.com/sakanaai/text-to-lora/blob/main/scripts/train_t2l_llama.sh"
    click CLI "https://github.com/sakanaai/text-to-lora/blob/main/scripts/train_t2l_mistral.sh"
    click CLI "https://github.com/sakanaai/text-to-lora/blob/main/scripts/train_hyperdecoders_mistral.sh"
    click CLI "https://github.com/sakanaai/text-to-lora/blob/main/scripts/eval_hyperdecoders_checkpoint.py"
    click CLI "https://github.com/sakanaai/text-to-lora/blob/main/scripts/eval_hypermod_checkpoint.py"
    click CLI "https://github.com/sakanaai/text-to-lora/blob/main/scripts/eval_base_models.sh"
    click WAT "https://github.com/sakanaai/text-to-lora/blob/main/watcher.py"
    click WebUI "https://github.com/sakanaai/text-to-lora/blob/main/webui/app.py"
    click FFF "https://github.com/sakanaai/text-to-lora/blob/main/src/fishfarm/fishfarm/__init__.py"
    click FFF "https://github.com/sakanaai/text-to-lora/blob/main/src/fishfarm/fishfarm/chat_templates.py"
    click FFF "https://github.com/sakanaai/text-to-lora/blob/main/src/fishfarm/fishfarm/logging.py"
    click FFF "https://github.com/sakanaai/text-to-lora/blob/main/src/fishfarm/fishfarm/models/base.py"
    click FFF "https://github.com/sakanaai/text-to-lora/blob/main/src/fishfarm/fishfarm/models/langchain_model.py"
    click FFF "https://github.com/sakanaai/text-to-lora/blob/main/src/fishfarm/fishfarm/models/vllm_model.py"
    click FFF "https://github.com/sakanaai/text-to-lora/blob/main/src/fishfarm/fishfarm/models/tokenization_utils.py"
    click FFF "https://github.com/sakanaai/text-to-lora/blob/main/src/fishfarm/fishfarm/tasks/__init__.py"
    click FFF "https://github.com/sakanaai/text-to-lora/blob/main/src/fishfarm/fishfarm/version.py"
    click HLM "https://github.com/sakanaai/text-to-lora/blob/main/src/hyper_llm_modulator/hyper_modulator.py"
    click HLM "https://github.com/sakanaai/text-to-lora/blob/main/src/hyper_llm_modulator/lora_mixing.py"
    click HLM "https://github.com/sakanaai/text-to-lora/blob/main/src/hyper_llm_modulator/sft_trainer.py"
    click HLM "https://github.com/sakanaai/text-to-lora/blob/main/src/hyper_llm_modulator/recon_trainer.py"
    click HLM "https://github.com/sakanaai/text-to-lora/blob/main/src/hyper_llm_modulator/hooks.py"
    click HLM "https://github.com/sakanaai/text-to-lora/blob/main/src/hyper_llm_modulator/vllm_eval.py"
    click HLM "https://github.com/sakanaai/text-to-lora/blob/main/src/hyper_llm_modulator/data.py"
    click HLM "https://github.com/sakanaai/text-to-lora/blob/main/src/hyper_llm_modulator/res_aggregator.py"
    click HLM "https://github.com/sakanaai/text-to-lora/blob/main/src/hyper_llm_modulator/configs.py"
    click HLM "https://github.com/sakanaai/text-to-lora/tree/main/src/hyper_llm_modulator/utils/"

    %% Styles
    classDef ui fill:#8FBC8F,stroke:#333,stroke-width:1px
    classDef code fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef data fill:#FFD700,stroke:#333,stroke-width:1px
    classDef external fill:#DDA0DD,stroke:#333,stroke-width:1px
```
