# lsbnnews/panzamail architecture

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

- Interactive diagram: https://gitdiagram.com/lsbnnews/panzamail
- Repository: https://github.com/lsbnnews/panzamail

## Overview

##### Primary Components
- Data Ingestion & Preparation:
- This includes the handling of raw emails in .mbox format (expected in the “data” directory) and the “data playback” process.
- In the file tree, look at scripts like prepare_data.py/.sh, and modules under src/panza/data_preparation.
- This component parses emails, generates synthetic prompts (using a pretrained LLM to summarize emails), and produces clean JSONL outputs, as well as splits train/test datasets.

- Fine-Tuning Engine:
- Modules in src/panza/finetuning (e.g., preprocessing.py and train.py) indicate the local fine-tuning of the language model.
- The system leverages both RoSA (parameter-efficient finetuning) and, optionally, full fine-tuning. The related configuration files are under configs/finetuning.

- Core Language Model (LLM) and Prompting:
- Under src/panza/llm, there is a base module with implementations for local execution (local.py, ollama.py).
- The prompting logic and customization are found in src/panza/prompting. This is tied to creating emails that match the user’s style.
- Configurations exist for the writer and ensuring the correct LLM setup (configs/writer and subdirectories for LLM specifics).

- Retriever and RAG (Retrieval-Augmented Generation):
- The addressing of retrieval is in src/panza/retriever with modules like faiss.py to build a vector database from past emails.
- The README also explains that a few relevant emails are fetched to better contextualize outputs.

- User Interfaces & Serving:
- Panza offers several interfaces: CLI, GUI, JSON, and web interfaces. These are organized under src/panza/interface.
- On the “configs/interfaces” side, there are YAML configuration files for each interface mode.
- Additionally, the “runner” scripts under scripts (like runner.py, runner.sh) show how to launch the serving mode (especially for local or web deployment).

- Configuration & Script Management:
- A robust configuration system sits in the “configs” directory. It includes settings for base operations, data preparation, fine-tuning, interfaces, and writer configurations.
- The scripts directory contains various bash and Python scripts that orchestrate data preparation, training, and serving.

##### Depicting Relationships & Data Flow
- Data Preparation component that converts these into structured JSONL files and builds the retrieval index (using Faiss).
- Next, illustrate the Fine-Tuning engine that uses the preprocessed data (data playback pairs: synthetic instruction and real email) to fine-tune the base LLM using techniques such as RoSA.
- Then, represent the LLM with its associated Prompting system that generates email drafts.
- RAG module (interfacing with the retriever) that fetches context – relevant past emails – to inform the LLM during generation.

##### Architectural Pattern & Design Principles
- Modular Design: Each main function (data preparation, fine-tuning, retrieval, LLM inference, and interfaces) is self-contained. This separation of concerns is evident in the distinct directories.
- Local Execution: Emphasize that all processes (training, inference, retrieval) occur on-device, supporting privacy requirements.

##### Relevant Technologies & Frameworks
- Mention parameter-efficient fine-tuning (LoRA/Sparse tuning via RoSA).
- Transformation libraries (e.g., Transformers – with different model types like Mistral or LLaMA variants).
- Reference retrieval libraries like Faiss for building the vector database.
- Configuration management via YAML and orchestration via bash/Python scripts.
- Docker (Dockerfile present) which might be used for containerized deployment.

##### Final Reminders
- Be extremely detailed. Avoid oversimplification by breaking down each functional module into its subcomponents based on the directory structure (e.g., separate “interface” module elements for CLI, GUI, etc.).
- You capture dependencies (for example, how configuration files in the “configs” directory influence behavior across modules).

## Diagram (Mermaid)

```mermaid
graph TD
    R0["Raw Emails (.mbox)"]:::data

    subgraph "Data Ingestion & Preparation"
        D1["Raw Email Access (data/)"]:::data
        D2["Data Prep Scripts (prepare_data.py, prepare_data.sh)"]:::data
        D3["Data Preparation Module (src/panza/data_preparation)"]:::data
    end

    subgraph "Fine-Tuning Engine"
        F1["Finetuning Module (src/panza/finetuning)"]:::fineTune
        F2["Finetuning Configs (configs/finetuning)"]:::fineTune
    end

    subgraph "LLM & Prompting"
        L1["LLM Core (src/panza/llm)"]:::llm
        L2["Prompting Module (src/panza/prompting)"]:::llm
        L3["LLM Configs (configs/writer & writer/llm)"]:::llm
    end

    subgraph "Retriever & RAG"
        R1["Retriever Module (src/panza/retriever)"]:::retriever
        R2["Retriever Configs (configs/writer/prompting/retriever)"]:::retriever
    end

    subgraph "Serving & Interfaces"
        I1["Interface Modules (src/panza/interface)"]:::interface
        I2["Interface Configs (configs/interfaces)"]:::interface
        I3["Runner Scripts (scripts/runner.py, runner.sh)"]:::interface
    end

    subgraph "Configuration & Script Management"
        C1["Global Configurations (configs/)"]:::config
        C2["Script Management (scripts/)"]:::config
    end

    %% Data Flow Connections
    R0 -->|"ingested"| D1
    D1 -->|"parsed by"| D2
    D2 -->|"processed by"| D3

    D3 -->|"feeds data to"| F1
    D3 -->|"builds index for"| R1

    F1 -->|"trains model"| L1
    F2 -->|"configures"| F1

    R1 -->|"provides context to"| L1
    R2 -->|"configures"| R1

    L1 -->|"augmented by"| L2
    L1 -->|"serves responses to"| I1

    I3 -->|"launches"| I1

    %% Configuration Management influences
    C1 ---|"configures"| F2
    C1 ---|"configures"| L3
    C1 ---|"configures"| R2
    C1 ---|"configures"| I2

    C2 ---|"orchestrates"| D2
    C2 ---|"orchestrates"| F1
    C2 ---|"orchestrates"| I3

    %% Click Events
    click D1 "https://github.com/lsbnnews/panzamail/tree/main/data/"
    click D2 "https://github.com/lsbnnews/panzamail/blob/main/scripts/prepare_data.py"
    click D3 "https://github.com/lsbnnews/panzamail/tree/main/src/panza/data_preparation/"

    click F1 "https://github.com/lsbnnews/panzamail/tree/main/src/panza/finetuning/"
    click F2 "https://github.com/lsbnnews/panzamail/tree/main/configs/finetuning/"

    click L1 "https://github.com/lsbnnews/panzamail/tree/main/src/panza/llm/"
    click L2 "https://github.com/lsbnnews/panzamail/tree/main/src/panza/prompting/"
    click L3 "https://github.com/lsbnnews/panzamail/tree/main/configs/writer/"

    click R1 "https://github.com/lsbnnews/panzamail/tree/main/src/panza/retriever/"
    click R2 "https://github.com/lsbnnews/panzamail/tree/main/configs/writer/prompting/retriever/"

    click I1 "https://github.com/lsbnnews/panzamail/tree/main/src/panza/interface/"
    click I2 "https://github.com/lsbnnews/panzamail/tree/main/configs/interfaces/"
    click I3 "https://github.com/lsbnnews/panzamail/blob/main/scripts/runner.py"

    click C1 "https://github.com/lsbnnews/panzamail/tree/main/configs/"
    click C2 "https://github.com/lsbnnews/panzamail/tree/main/scripts/"

    %% Styles
    classDef data fill:#d1e8ff,stroke:#333,stroke-width:2px;
    classDef fineTune fill:#ffdab9,stroke:#333,stroke-width:2px;
    classDef llm fill:#d3ffd3,stroke:#333,stroke-width:2px;
    classDef retriever fill:#fff2cc,stroke:#333,stroke-width:2px;
    classDef interface fill:#fce5cd,stroke:#333,stroke-width:2px;
    classDef config fill:#d9ead3,stroke:#333,stroke-width:2px;
```
