# tarek-kerbedj/sql_agent architecture

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

- Interactive diagram: https://gitdiagram.com/tarek-kerbedj/sql_agent
- Repository: https://github.com/tarek-kerbedj/sql_agent

## Overview

##### Project type and purpose
- This is a Python-based, single-process “full-stack” web app built with Streamlit.
- Purpose: provide data insights via three key features—database analysis, document Q&A, and signal generation—driven by LLMs (via LangChain/AWS Bedrock) and a Cassandra backend.

##### File structure
- Top level
- insights.py – Streamlit entry point and UI layout
- requirements.txt, startup.sh – dependencies and launch script
- .github/workflows – CI/CD pipelines for Azure deployment
- .streamlit – Streamlit configuration
- components/
- database_insights.py – all Cassandra-related logic
- document_QA.py – document ingestion and Q&A
- signal_generation.py – business-logic for signal creation
- utils/
- core_funcs.py – LangChain chains and summaries
- llm_utilities.py – LLM API orchestration (prompt parsing, chain connections)
- util_funcs.py – misc. file I/O, zipping, downloads
- style.py – UI styling helpers
- other/
- cassandra/ – secure-connect bundle & tokens
- credentials/ – login CSV
- prompts/ – YAML prompt templates
- wheels/ – bundled boto3/botocore wheels for AWS Bedrock
- images/ – static assets

##### README for additional insights
- Confirms `insights.py` is the sole entry point.
- Outlines the three component modules.
- Installation and run instructions via Streamlit.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "UI Layer"
        UI["insights.py"]:::ui
        Conf1["config.toml"]:::ui
        Conf2["credentials.toml"]:::ui
    end

    subgraph "Application Logic Layer"
        DBInsight["database_insights.py"]:::logic
        DocQA["document_QA.py"]:::logic
        SignalGen["signal_generation.py"]:::logic
    end

    subgraph "Utilities Layer"
        CoreFuncs["core_funcs.py"]:::utils
        LLMUtils["llm_utilities.py"]:::utils
        UtilFuncs["util_funcs.py"]:::utils
        Style["style.py"]:::utils
    end

    subgraph "Data & External Services"
        Cassandra[(Cassandra DB)]:::data
        AWSBedrock:::external
    end

    subgraph "Config & Assets"
        SecureBundle["secure-connect-test-vector-db.zip"]:::config
        Token["roland.ferrao@forwardlane.com-token.json"]:::config
        CredentialsCSV["logins.csv"]:::config
        Prompts["prompts.yaml"]:::config
        WheelsBoto3["boto3-1.28.21-py3-none-any.whl"]:::config
        WheelsBotocore["botocore-1.31.21-py3-none-any.whl"]:::config
    end

    subgraph "CI/CD & Deployment"
        Workflow1["azure_insights-forwardlane.yml"]:::cicd
        Workflow2["main_insights-demo-st.yml"]:::cicd
        Startup["startup.sh"]:::cicd
        Req["requirements.txt"]:::cicd
        Readme["README.md"]:::cicd
    end

    %% Flows
    UI -->|"select feature"| DBInsight
    UI -->|"select feature"| DocQA
    UI -->|"select feature"| SignalGen
    DBInsight -->|"use DB connector"| CoreFuncs
    DBInsight -->|"use util funcs"| UtilFuncs
    DBInsight -->|"query"| Cassandra
    DBInsight -->|"load bundle"| SecureBundle
    DBInsight -->|"load token"| Token
    DocQA -->|"invoke LLM chain"| CoreFuncs
    DocQA -->|"invoke orchestration"| LLMUtils
    DocQA -->|"load prompts"| Prompts
    DocQA -->|"file ops"| UtilFuncs
    SignalGen -->|"invoke LLM chain"| CoreFuncs
    SignalGen -->|"invoke orchestration"| LLMUtils
    SignalGen -->|"file ops"| UtilFuncs

    CoreFuncs -->|"calls API"| AWSBedrock
    LLMUtils -->|"calls API"| AWSBedrock
    LLMUtils -->|"load wheels"| WheelsBoto3
    LLMUtils -->|"load wheels"| WheelsBotocore
    Cassandra -->|"auth via"| Token
    Cassandra -->|"config via"| SecureBundle
    UI -->|"style UI"| Style

    %% CI/CD
    Workflow1 -.->|triggers| Startup
    Workflow2 -.->|triggers| Startup
    Startup -.->|installs| Req
    Startup -.->|reads| Readme

    %% Click Events
    click UI "https://github.com/tarek-kerbedj/sql_agent/blob/main/insights.py"
    click Conf1 "https://github.com/tarek-kerbedj/sql_agent/blob/main/.streamlit/config.toml"
    click Conf2 "https://github.com/tarek-kerbedj/sql_agent/blob/main/.streamlit/credentials.toml"
    click DBInsight "https://github.com/tarek-kerbedj/sql_agent/blob/main/components/database_insights.py"
    click DocQA "https://github.com/tarek-kerbedj/sql_agent/blob/main/components/document_QA.py"
    click SignalGen "https://github.com/tarek-kerbedj/sql_agent/blob/main/components/signal_generation.py"
    click CoreFuncs "https://github.com/tarek-kerbedj/sql_agent/blob/main/utils/core_funcs.py"
    click LLMUtils "https://github.com/tarek-kerbedj/sql_agent/blob/main/utils/llm_utilities.py"
    click UtilFuncs "https://github.com/tarek-kerbedj/sql_agent/blob/main/utils/util_funcs.py"
    click Style "https://github.com/tarek-kerbedj/sql_agent/blob/main/utils/style.py"
    click SecureBundle "https://github.com/tarek-kerbedj/sql_agent/blob/main/other/cassandra/secure-connect-test-vector-db.zip"
    click Token "https://github.com/tarek-kerbedj/sql_agent/blob/main/other/cassandra/roland.ferrao@forwardlane.com-token.json"
    click CredentialsCSV "https://github.com/tarek-kerbedj/sql_agent/blob/main/other/credentials/logins.csv"
    click Prompts "https://github.com/tarek-kerbedj/sql_agent/blob/main/other/prompts/prompts.yaml"
    click WheelsBoto3 "https://github.com/tarek-kerbedj/sql_agent/blob/main/other/wheels/boto3-1.28.21-py3-none-any.whl"
    click WheelsBotocore "https://github.com/tarek-kerbedj/sql_agent/blob/main/other/wheels/botocore-1.31.21-py3-none-any.whl"
    click Workflow1 "https://github.com/tarek-kerbedj/sql_agent/blob/main/.github/workflows/azure_insights-forwardlane.yml"
    click Workflow2 "https://github.com/tarek-kerbedj/sql_agent/blob/main/.github/workflows/main_insights-demo-st.yml"
    click Startup "https://github.com/tarek-kerbedj/sql_agent/blob/main/startup.sh"
    click Req "https://github.com/tarek-kerbedj/sql_agent/blob/main/requirements.txt"
    click Readme "https://github.com/tarek-kerbedj/sql_agent/blob/main/README.md"

    %% Styles
    classDef ui fill:#9f6,stroke:#333,stroke-width:1px
    classDef logic fill:#6af,stroke:#333,stroke-width:1px
    classDef utils fill:#4eb,stroke:#333,stroke-width:1px
    classDef data fill:#fa6,stroke:#333,stroke-width:1px
    classDef external fill:#a6f,stroke:#333,stroke-width:1px,shape:cloud
    classDef config fill:#ffec8b,stroke:#333,stroke-width:1px
    classDef cicd fill:#aaa,stroke:#333,stroke-width:1px
```
