# dadiya-harsh-wappnet/sql-tool architecture

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

- Interactive diagram: https://gitdiagram.com/dadiya-harsh-wappnet/sql-tool
- Repository: https://github.com/dadiya-harsh-wappnet/sql-tool

## Overview

##### Project Type and Purpose
- This is a Python-based utility library (open-source tool) named **SQL Agent Tool**.
- Purpose: Safely connect to and execute read-only SQL queries on PostgreSQL via SQLAlchemy, with optional Groq API integration for natural-language query generation.

##### File Structure
- Top level:
- setup.py, pyproject.toml, requirements.txt – packaging and dependencies
- README.md, LICENSE, .gitignore – documentation
- sql_agent_tool/ – core library
- tests/ – pytest suite
- In `sql_agent_tool/`:
- core.py – main class (`SQLAgentTool`)
- models.py – pydantic `DatabaseConfig` model
- exceptions.py – custom error classes
- utils.py – any helper functions (e.g., env loading, parameter sanitization)
- Tests use pytest fixtures (`tests/test_postgresql.py`) and temporary tables to validate behavior.

##### Key README Insights
- Uses SQLAlchemy + psycopg2-binary for DB connection
- Pydantic for config validation
- Groq API key for optional NLP layer
- Schema reflection, safe parameter binding, and robust error handling

##### Main Components
- User Application (your code that imports/instantiates `SQLAgentTool`)
- SQLAgentTool (core component)
- DatabaseConfig (model)
- Exception Layer (custom exception classes)
- Utility Module (utils.py)
- SQLAlchemy + psycopg2-binary (library block, green)
1. User Application → DatabaseConfig: supplies connection parameters
2. DatabaseConfig → SQLAgentTool: injected at instantiation
3. SQLAgentTool → SQLAlchemy Engine: creates connection
4. SQLAgentTool → PostgreSQL:
- Schema Reflection (introspects tables)
- Query Execution (read-only SELECT with parameter binding)
5. SQLAgentTool ↔ Groq API (optional path):
- Send prompt → Groq returns generated SQL
6. SQLAgentTool → Exception Layer:
- Throws `SchemaReflectionError`, `QueryValidationError`, or `ExecutionError` on failure
7. SQLAgentTool → User Application: returns `Result` object with `.data`

##### Architectural Patterns & Principles
- Layered Design:
- Presentation Layer (User code)
- Application Layer (`SQLAgentTool`)
- Domain Layer (`DatabaseConfig`, `models.py`)
- Infrastructure Layer (SQLAlchemy + PostgreSQL, Groq API)
- Single Responsibility: each module has one concern (core logic vs. config vs. exceptions)
- Dependency Injection: `DatabaseConfig` + optional `groq_api_key` passed into `SQLAgentTool`
- Error Handling: custom exceptions for each failure domain

##### Putting It All Together
- `SQLAgentTool` in the center inside the “sql_agent_tool” boundary.
- Under it, group `DatabaseConfig`, `exceptions.py`, `utils.py`, `models.py`.

## Diagram (Mermaid)

```mermaid
flowchart TD
    UserApp["User Application"]:::internal

    subgraph "sql_agent_tool Package"
        Init["__init__.py"]:::internal
        core["SQLAgentTool"]:::internal
        dbconfig["DatabaseConfig"]:::internal
        exceptions["Exception Layer"]:::internal
        utils["Utility Module"]:::internal
    end

    sqlalchemy["SQLAlchemy + psycopg2-binary"]:::external
    postgres[(PostgreSQL Database)]:::db
    groq((Groq API Service)):::external

    UserApp -->|"supplies connection parameters"| dbconfig
    dbconfig -->|"injected"| core
    core -->|"create_engine()"| sqlalchemy
    sqlalchemy -->|"connection"| postgres
    core -->|"reflect_schema()"| postgres
    core -->|"execute_query()"| postgres
    core -->|"returns Result"| UserApp
    core -->|"throws errors"| exceptions
    core -.->|"optional"| groq
    groq -.->|"returns SQL"| core

    subgraph "Tests"
        test_core["tests/test_core.py"]:::internal
        test_pg["tests/test_postgresql.py"]:::internal
    end

    test_core --> core
    test_pg --> postgres

    subgraph "Project Root Files"
        setup["setup.py"]:::external
        pyproject["pyproject.toml"]:::external
        req["requirements.txt"]:::external
        readme["README.md"]:::external
        license["LICENSE"]:::external
        gitignore[".gitignore"]:::external
    end

    click core "https://github.com/dadiya-harsh-wappnet/sql-tool/blob/main/sql_agent_tool/core.py"
    click dbconfig "https://github.com/dadiya-harsh-wappnet/sql-tool/blob/main/sql_agent_tool/models.py"
    click exceptions "https://github.com/dadiya-harsh-wappnet/sql-tool/blob/main/sql_agent_tool/exceptions.py"
    click utils "https://github.com/dadiya-harsh-wappnet/sql-tool/blob/main/sql_agent_tool/utils.py"
    click Init "https://github.com/dadiya-harsh-wappnet/sql-tool/blob/main/sql_agent_tool/__init__.py"
    click test_core "https://github.com/dadiya-harsh-wappnet/sql-tool/blob/main/tests/test_core.py"
    click test_pg "https://github.com/dadiya-harsh-wappnet/sql-tool/blob/main/tests/test_postgresql.py"
    click setup "https://github.com/dadiya-harsh-wappnet/sql-tool/blob/main/setup.py"
    click pyproject "https://github.com/dadiya-harsh-wappnet/sql-tool/blob/main/pyproject.toml"
    click req "https://github.com/dadiya-harsh-wappnet/sql-tool/blob/main/requirements.txt"
    click readme "https://github.com/dadiya-harsh-wappnet/sql-tool/blob/main/README.md"
    click license "https://github.com/dadiya-harsh-wappnet/sql-tool/tree/main/LICENSE"
    click gitignore "https://github.com/dadiya-harsh-wappnet/sql-tool/blob/main/.gitignore"

    classDef internal fill:#add8e6,stroke:#000,stroke-width:1px
    classDef external fill:#98fb98,stroke:#000,stroke-width:1px
    classDef db fill:#ffa500,stroke:#000,stroke-width:1px
```
