# asii-mov/llama-guard-output-feedback architecture

> Architecture diagram of the GitHub repository asii-mov/llama-guard-output-feedback, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/asii-mov/llama-guard-output-feedback
- Repository: https://github.com/asii-mov/llama-guard-output-feedback

## Overview

##### Project Type and Purpose
- This is a research‐oriented experiment pipeline, not a user‐facing application. Its goal is to improve the input‐filtering behavior of Meta’s Llama Guard by using output‐feedback: prompts that lead to blocked outputs become negative training examples.

##### File Structure Analysis
- Top‐level files:
- finetuning_data_formatter.py – prepares prompt examples for fine‐tuning
- research_implementation.py – core Python module orchestrating processing, training, evaluation
- research_config.json – all hyperparameters, model paths, dataset names, output directories
- run_experiment.sh – single‐entrypoint shell script that runs “process”, “train”, “evaluate” or full pipeline
- requirements.txt – Python dependencies
- README.md – project overview and usage

##### Key Insights from README
- Three distinct stages (process → train → evaluate), each driven by research_implementation.py and configured by research_config.json.
- External dependencies: Hugging Face LLMs (Mistral‐7B for generation, LlamaGuard‐7b for filtering), HF CLI for authentication, dataset (e.g. lmsys/toxic-chat).
- Intermediate and final artifacts: blocked_inputs.jsonl, fine‐tuned adapter checkpoint, evaluation metrics and logs.

a. Configuration Loader
- Reads research_config.json
b. Experiment Orchestrator
- run_experiment.sh calls research_implementation.py with the requested stage
c. Data Processing (“process” stage)
- Base LLM (Mistral‐7B) generates candidate responses
- Default Llama Guard filters outputs → yields blocked prompts → write to data/blocked_inputs/blocked_inputs.jsonl
- finetuning_data_formatter transforms JSONL into LoRA‐ready datasets
d. Model Training (“train” stage)
- LoRA fine‐tuning on “unsafe” vs “safe” examples
- Uses default Llama Guard base model → produces improved adapter at training.output_dir
e. Evaluation (“evaluate” stage)
- Loads default vs improved adapters
- Runs on test set → computes precision/recall/F1 → writes to evaluation.results_dir
f. External Services
- Hugging Face Hub (model retrieval, push/pull)
- Dataset host (e.g. lmsys/toxic-chat)

##### Relationships and Data Flow
- Data flows:
- Config → all stages
- LLM outputs → Llama Guard filter → blocked_inputs.jsonl → formatted dataset → training module → adapter
- Adapter + test data → evaluation module → metrics
- External systems are side‐connected: Hugging Face Hub, dataset registry

##### Architectural Patterns and Principles
- Modular, stage‐based pipeline
- Single source of truth for config (research_config.json)
- Clear separation of concerns: data collection, fine‐tuning, evaluation
- Reusability: formatter, implementation module, shell wrapper

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Configuration and Documentation
    Config["research_config.json"]:::config
    Req["requirements.txt"]:::config
    Readme["README.md"]:::config

    %% Experiment Orchestrator
    ExpOrch["run_experiment.sh\n(Experiment Orchestrator)"]:::config

    %% Pipeline Stages
    DataProc["Process Stage\nData Processor\n(Python: LLM + Llama Guard)"]:::processing
    BI[/blocked_inputs.jsonl/]:::artifact
    Formatter["Data Formatter\n(fin etuning_data_formatter.py)"]:::processing
    Dataset[/LoRA-ready Dataset/]:::artifact
    Trainer["Train Stage\nTraining Module\n(LoRA fine-tuning)"]:::training
    Adapter[/Adapter Checkpoint/]:::artifact
    Evaluator["Evaluate Stage\nEvaluation Module\n(Metrics)"]:::training
    Metrics[/Evaluation Metrics/]:::artifact

    %% External Services
    HF["Hugging Face Hub"]:::external
    DS["Dataset Host\n(e.g. lmsys/toxic-chat)"]:::external

    %% Connections
    Config --> ExpOrch
    Req --> ExpOrch
    Readme --> ExpOrch

    ExpOrch --> DataProc
    DataProc --> BI
    BI --> Formatter
    Formatter --> Dataset
    Dataset --> Trainer
    Trainer --> Adapter
    Adapter --> Evaluator
    Evaluator --> Metrics

    Config --> DataProc
    Config --> Formatter
    Config --> Trainer
    Config --> Evaluator

    HF -.-> DataProc
    HF -.-> Trainer
    HF -.-> Evaluator
    DS -.-> DataProc

    %% Click Events
    click Config "https://github.com/asii-mov/llama-guard-output-feedback/blob/main/research_config.json"
    click Req "https://github.com/asii-mov/llama-guard-output-feedback/blob/main/requirements.txt"
    click Readme "https://github.com/asii-mov/llama-guard-output-feedback/blob/main/README.md"
    click ExpOrch "https://github.com/asii-mov/llama-guard-output-feedback/blob/main/run_experiment.sh"
    click DataProc "https://github.com/asii-mov/llama-guard-output-feedback/blob/main/research_implementation.py"
    click Formatter "https://github.com/asii-mov/llama-guard-output-feedback/blob/main/finetuning_data_formatter.py"
    click Trainer "https://github.com/asii-mov/llama-guard-output-feedback/blob/main/research_implementation.py"
    click Evaluator "https://github.com/asii-mov/llama-guard-output-feedback/blob/main/research_implementation.py"

    %% Styles
    classDef config fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef processing fill:#FFA500,stroke:#333,stroke-width:1px
    classDef training fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef artifact fill:#FFFFE0,stroke:#333,stroke-width:1px
```
