# monzero/talk2table architecture

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

- Interactive diagram: https://gitdiagram.com/monzero/talk2table
- Repository: https://github.com/monzero/talk2table

## Overview

##### Project type and purpose
- This is a full-stack, modular Python application named “Talk2Table.”
- Purpose: Let end users pose natural-language questions via a Streamlit UI; route those queries through reusable agent tools and data pipelines; return tabular or analytical results.

##### File structure
Top-level entries:
- .devcontainer/ – development container config
- README.md – project overview & setup
- app.py – Streamlit front end
- main.py – optional backend runner or test harness
- data/ – raw CSV datasets and descriptors
- modules/ – core business logic
– data_preparation.py: ingest, clean, embed data
– query_processing.py: parse and route queries
– agent_tools.py: helper functions and response generators
- requirements.txt – Python dependencies

##### README for additional insights
- Modular design: three logical layers (data prep, query parser, agent tools)
- Streamlit frontend for interactive querying
- Optional use of sentence-transformers or OpenAI for embeddings/vector search
- Extensibility points clearly called out in each module

a. Main components
- User Interface (Streamlit App)
- Query Processing Module
- Data Preparation Module
- Agent Tools Module
- Data Store (CSV files under data/)
- External Services (e.g., embeddings model or OpenAI API)
- Optional Runner/Test Harness (main.py)
b. Relationships & interactions
1. Browser → Streamlit App (app.py)
2. Streamlit App → Query Processing
3. Query Processing decides:
– Does this query need vector search? → Data Preparation
– Does it require agent logic? → Agent Tools
4. Data Preparation ↔ Data Store for ingestion & embeddings
5. Data Preparation → External Embedding Service (if used)
6. Agent Tools → External APIs or internal helper functions
7. Processed result → Streamlit App → Browser
8. main.py can invoke modules directly (for testing or batch runs)
c. Architectural patterns & design principles
- Layered modular architecture
- Separation of concerns: UI, parsing, data prep, business tools
- Extensibility: plug new agents or data sources by extending modules
d. Key technologies & frameworks
- Python 3.8+
- Streamlit (UI)
- pandas, numpy (data handling)
- sentence-transformers or OpenAI (vector embeddings / LLM)
- CSV files as source of truth

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and Frontend
    Browser["Browser"] 
    UI["Streamlit App"] 

    %% Backend Modules
    main["Runner/Test Harness (main.py)"]
    qproc["Query Processing Module"]
    dprep["Data Preparation Module"]
    tools["Agent Tools Module"]
    analyzer["Dataframe Analyzer"]

    %% Data Store
    datastore[("Data Store\n(Raw CSV)")] 

    %% External Services
    ext_embed(["Embedding Service"])
    ext_llm(["LLM / OpenAI Service"])

    %% Documentation & Config
    readme["Project README.md"]
    reqs["requirements.txt"]
    mod_readme["modules/readme"]
    data_readme["data/readme"]
    devcont[".devcontainer/devcontainer.json"]

    %% Frontend to Backend Flow
    Browser -->|"HTTP Request"| UI
    UI -->|"process_query()"| qproc

    %% Query Processing Branches
    qproc -->|"needs_vector_search"| dprep
    qproc -->|"calls_agent_logic"| tools

    %% Data Preparation Flow
    dprep -->|"ingest()/clean()"| datastore
    dprep -->|"get_embeddings()"| ext_embed
    dprep -->|"use_analyzer()"| analyzer

    %% Agent Tools Flow
    tools -->|"invoke_helpers()"| analyzer
    tools -->|"call_llm()"| ext_llm

    %% Results Back to UI
    qproc -->|"return_results()"| UI
    UI -->|"render_table()"| Browser

    %% Runner/Test Harness
    main -->|"direct_call()"| qproc
    main -->|"direct_call()"| dprep
    main -->|"direct_call()"| tools

    %% Documentation & Config References
    readme --> UI
    readme --> qproc
    readme --> dprep
    readme --> tools
    reqs --> dprep
    reqs --> tools
    mod_readme --> qproc
    mod_readme --> dprep
    mod_readme --> tools
    data_readme --> datastore
    devcont --> readme

    %% Click Events
    click UI "https://github.com/monzero/talk2table/blob/main/app.py"
    click main "https://github.com/monzero/talk2table/blob/main/main.py"
    click datastore "https://github.com/monzero/talk2table/tree/main/data/"
    click qproc "https://github.com/monzero/talk2table/blob/main/modules/query_processing.py"
    click dprep "https://github.com/monzero/talk2table/blob/main/modules/data_preparation.py"
    click tools "https://github.com/monzero/talk2table/blob/main/modules/agent_tools.py"
    click analyzer "https://github.com/monzero/talk2table/blob/main/modules/dataframe_analyzer.py"
    click devcont "https://github.com/monzero/talk2table/blob/main/.devcontainer/devcontainer.json"
    click readme "https://github.com/monzero/talk2table/blob/main/README.md"
    click reqs "https://github.com/monzero/talk2table/blob/main/requirements.txt"
    click mod_readme "https://github.com/monzero/talk2table/tree/main/modules/readme"
    click data_readme "https://github.com/monzero/talk2table/tree/main/data/readme"

    %% Styling
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef logic fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef datastore fill:#FFFF99,stroke:#333,stroke-width:1px;
    classDef external fill:#FFD580,stroke:#333,stroke-width:1px;
    classDef docs fill:#D3D3D3,stroke:#333,stroke-width:1px;

    class UI frontend;
    class qproc,dprep,tools,analyzer,main logic;
    class datastore datastore;
    class ext_embed,ext_llm external;
    class readme,reqs,mod_readme,data_readme,devcont docs;
```
