# pesc101/dbqr architecture

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

- Interactive diagram: https://gitdiagram.com/pesc101/dbqr
- Repository: https://github.com/pesc101/dbqr

## Overview

##### Project type and purpose
- This is an NLP/ML pipeline for question answering over databases, orchestrated via Python scripts and configurable via YAML.
- It includes: data ingestion, prompt generation, LLM inference, code execution for reasoning, result tidying, evaluation, experiment logging, and an optional Streamlit UI.

##### High-level component breakdown
A. Configuration Manager
– Files: conf/*.yaml, config.py
– Purpose: Reads model parameters, tuning settings, WandB defaults.
B. Data Layer
– Files: src/data/overview.py, src/data/read_data.py
– Purpose: Loads question-answer pairs or schemas from disk.
C. Prompt Engine
– Files: prompts/**/*.j2, prompts/sys_prompts/*.txt
– Purpose: Uses Jinja2 templates to generate tailored prompts for LLMs.
D. Inference Module
– Files: src/code/code_executor.py, src/code/tools*.txt, src/code/tools.py
– Purpose: Submits prompts to the LLM API (OpenAI/HuggingFace), optionally runs generated Python for reasoning.
E. Post-Processing
– Files: src/tidy.py, src/code/execute_tidy.py
– Purpose: Cleans up and normalizes LLM outputs.
F. Evaluation
– File: src/evaluate.py
– Purpose: Computes accuracy, metrics for QA.
G. Orchestration Entry Point
– File: main.py
– Purpose: Pulls together all stages: load config, read data, generate prompts, call inference, tidy, evaluate, log.
H. Experiment Logging
– Files: conf/wandb/defaults.yaml, implicit WandB client in code
– Purpose: Tracks runs, metrics, parameters.
I. Interactive UI (Optional)
– File: streamlit/explore.py
– Purpose: A Streamlit-based dashboard to browse examples and results.

##### Relationships & Data Flows
- main.py → Configuration Manager: fetches model and logging settings.
- main.py → Data Layer: loads dataset.
- main.py → Prompt Engine: generates instructions for each example.
- main.py → Inference Module: sends prompt to external LLM service and/or executes generated code.
- Inference Module ↔ External LLM API: network call to OpenAI/HuggingFace.
- Inference Module → Post-Processing: normalizes raw responses.
- Post-Processing → Evaluation: computes QA metrics.
- Every stage → Experiment Logging (WandB): logs inputs, outputs, metrics.
- Streamlit UI reads from outputs of Post-Processing/Evaluation for interactive exploration.

##### Architectural patterns & design principles
- Pipeline pattern: linear flow through distinct stages (ingest → infer → tidy → evaluate).
- Separation of concerns: config, data I/O, prompt templating, inference, and evaluation are modular.
- Template-driven prompt engineering: Jinja2 for reusability.
- Pluggable model backends via YAML (GPT, LLaMA).
- Optional UI layer disconnected from batch pipeline.

##### Final checklist
– A note or sidebar listing major file locations under each component.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Pipeline
    subgraph "Core Pipeline"
        direction TB
        Main["main.py"]:::core
        DataLayer["Data Layer\n(src/data/overview.py,\nsrc/data/read_data.py)"]:::core
        PromptEngine["Prompt Engine\n(prompts/*.j2,\nprompts/sys_prompts/*.txt)"]:::core
        Inference["Inference Module\n(src/code/code_executor.py,\nsrc/code/tools.py,\nsrc/code/*.txt)"]:::core
        PostProcess["Post-Processing\n(src/tidy.py,\nsrc/code/execute_tidy.py)"]:::core
        Evaluation["Evaluation\n(src/evaluate.py)"]:::core
    end

    %% Config & Logging
    subgraph "Config & Logging"
        direction TB
        ConfigManager["Configuration Manager\n(conf/*.yaml,\nconfig.py)"]:::config
        ExperimentLogging["Experiment Logging\n(conf/wandb/defaults.yaml)"]:::external
    end

    %% External Services
    subgraph "External Services"
        direction TB
        LLMAPI["LLM API\n(OpenAI/HuggingFace)"]:::external
    end

    %% UI
    subgraph "Interactive UI" 
        direction TB
        StreamlitUI["Streamlit UI\n(streamlit/explore.py)"]:::ui
    end

    %% Connections
    Main -->|"load config"| ConfigManager
    Main -->|"load data"| DataLayer
    Main -->|"generate prompts"| PromptEngine
    Main -->|"run inference"| Inference
    Inference -.->|"call LLM API"| LLMAPI
    Inference -->|"raw response"| PostProcess
    PostProcess -->|"tidied output"| Evaluation

    %% Experiment Logging links
    Main -->|"log run"| ExperimentLogging
    ConfigManager -->|"log config"| ExperimentLogging
    DataLayer -->|"log data stats"| ExperimentLogging
    PromptEngine -->|"log prompt"| ExperimentLogging
    Inference -->|"log raw"| ExperimentLogging
    PostProcess -->|"log tidy"| ExperimentLogging
    Evaluation -->|"log metrics"| ExperimentLogging

    %% UI consumption
    StreamlitUI -->|"reads tidy output"| PostProcess
    StreamlitUI -->|"reads metrics"| Evaluation

    %% Styles
    classDef core fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef config fill:#E0F8D8,stroke:#333,stroke-width:1px
    classDef external fill:#FFD8B0,stroke:#333,stroke-width:1px
    classDef ui fill:#E8D0FF,stroke:#333,stroke-width:1px

    %% Click Events
    click ConfigManager "https://github.com/pesc101/dbqr/blob/master/conf/config.yaml"
    click ConfigManager "https://github.com/pesc101/dbqr/blob/master/conf/model/gpt.yaml"
    click ConfigManager "https://github.com/pesc101/dbqr/blob/master/conf/model/gpt_big.yaml"
    click ConfigManager "https://github.com/pesc101/dbqr/blob/master/conf/model/llama.yaml"
    click ConfigManager "https://github.com/pesc101/dbqr/blob/master/conf/model/llama_big.yaml"
    click ConfigManager "https://github.com/pesc101/dbqr/blob/master/conf/tidy_model/llama.yaml"
    click ConfigManager "https://github.com/pesc101/dbqr/blob/master/conf/tidy_model/llama_big.yaml"
    click ConfigManager "https://github.com/pesc101/dbqr/blob/master/config.py"
    click DataLayer "https://github.com/pesc101/dbqr/blob/master/src/data/overview.py"
    click DataLayer "https://github.com/pesc101/dbqr/blob/master/src/data/read_data.py"
    click PromptEngine "https://github.com/pesc101/dbqr/blob/master/prompts/generate_python_code_conv.j2"
    click PromptEngine "https://github.com/pesc101/dbqr/blob/master/prompts/generate_tidy_data.j2"
    click PromptEngine "https://github.com/pesc101/dbqr/blob/master/prompts/llama3_default.j2"
    click PromptEngine "https://github.com/pesc101/dbqr/blob/master/prompts/sys_prompts/chatgpt.txt"
    click PromptEngine "https://github.com/pesc101/dbqr/blob/master/prompts/sys_prompts/chatgpt_tidy.txt"
    click PromptEngine "https://github.com/pesc101/dbqr/blob/master/prompts/sys_prompts/chatgpt_wo_few.txt"
    click PromptEngine "https://github.com/pesc101/dbqr/blob/master/prompts/sys_prompts/chatgpt_wo_tidy.txt"
    click PromptEngine "https://github.com/pesc101/dbqr/blob/master/prompts/sys_prompts/compact.txt"
    click PromptEngine "https://github.com/pesc101/dbqr/blob/master/prompts/sys_prompts/default.txt"
    click PromptEngine "https://github.com/pesc101/dbqr/blob/master/prompts/sys_prompts/pandas.txt"
    click PromptEngine "https://github.com/pesc101/dbqr/blob/master/prompts/sys_prompts/tidy.txt"
    click Inference "https://github.com/pesc101/dbqr/blob/master/src/code/code_executor.py"
    click Inference "https://github.com/pesc101/dbqr/blob/master/src/code/tools.py"
    click Inference "https://github.com/pesc101/dbqr/blob/master/src/code/functions.txt"
    click Inference "https://github.com/pesc101/dbqr/blob/master/src/code/tools_empty.txt"
    click Inference "https://github.com/pesc101/dbqr/blob/master/src/code/tools_head.py"
    click Inference "https://github.com/pesc101/dbqr/blob/master/src/code/tools_minify.txt"
    click Inference "https://github.com/pesc101/dbqr/blob/master/src/code/tools_minify_chatgpt.txt"
    click PostProcess "https://github.com/pesc101/dbqr/blob/master/src/tidy.py"
    click PostProcess "https://github.com/pesc101/dbqr/blob/master/src/code/execute_tidy.py"
    click Evaluation "https://github.com/pesc101/dbqr/blob/master/src/evaluate.py"
    click Main "https://github.com/pesc101/dbqr/blob/master/main.py"
    click ExperimentLogging "https://github.com/pesc101/dbqr/blob/master/conf/wandb/defaults.yaml"
    click StreamlitUI "https://github.com/pesc101/dbqr/blob/master/streamlit/explore.py"
```
