# y1ssh/s-agents-practice architecture

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

- Interactive diagram: https://gitdiagram.com/y1ssh/s-agents-practice
- Repository: https://github.com/y1ssh/s-agents-practice

## Overview

##### Project Type and Purpose
- This is a prompt-driven “AI Agents Cookbook” repository whose primary focus is on self-contained AI agents.
- The provided “Sql Agent” folder is one agent implementation: it accepts a CSV upload, turns natural-language questions into SQL via an LLM, executes the SQL, and returns results (including visualizations).

##### File Structure
- Top level:
- README.md – main project overview (“Agents Cookbook”)
- “Sql Agent” directory – one agent’s code and recipe
- Sql Agent folder:
- PROMPT.md – the full LLM prompt (the “recipe”) used to generate the agent
- README.md – agent-specific setup & usage
- requirements.txt – Python dependencies (LLM SDK, pandas, SQL engine, web framework)
- src/
– app.py – web or CLI entry point (API server)
– agent.py – orchestration logic (builds prompt, calls LLM, parses SQL)
– config.py – API keys, model settings, execution parameters

##### README for Additional Insights
- Agents are run locally by navigating into the agent subfolder.
- Each agent follows the same pattern: a single prompt, a small codebase, and a standard interface.
- The SQL Agent specifically uses an LLM to translate NL → SQL, runs queries against an in-memory or file-backed database (e.g., sqlite/pandas), and returns text + charts.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Repository Documentation
    READMERoot["Project Overview<br>(README.md)"]:::doc
    AgentDoc["Agent Docs<br>(Sql Agent/README.md)"]:::doc
    Requirements["Dependencies<br>(requirements.txt)"]:::doc

    subgraph "SQL Agent Container"
        direction TB
        UI["User Interface<br>(CLI / HTTP Client)"]
        APIServer["API Server<br>(src/app.py)<br>FastAPI"]:::internal
        AgentEngine["Agent Engine<br>(src/agent.py)"]:::internal
        Config["Configuration Module<br>(src/config.py)"]:::internal
        PromptRepo["Prompt Repository<br>(PROMPT.md)"]:::doc
        DataStore["Data Layer<br>(CSV / SQLite)"]:::data
        SQLEngine["SQL Execution Engine<br>(pandas / sqlite)"]:::internal
        Viz["Visualization Module<br>(matplotlib / seaborn)"]:::internal
        ExtLLM["External LLM Service<br>(OpenAI API)"]:::external
    end

    %% Data Flow
    UI -->|"upload CSV & question"| APIServer
    APIServer -->|"Invoke agent"| AgentEngine
    AgentEngine -->|"Load prompt template"| PromptRepo
    AgentEngine -->|"Generate SQL query"| ExtLLM
    ExtLLM -->|"Return SQL & explanation"| AgentEngine
    AgentEngine -->|"Execute SQL"| SQLEngine
    SQLEngine -->|"Return result set"| AgentEngine
    AgentEngine -->|"Render charts"| Viz
    AgentEngine -->|"Package JSON & images"| APIServer
    APIServer -->|"Return response"| UI

    %% Configuration
    Config -->|"Provide model & DB settings"| AgentEngine
    Config -->|"Provide server config"| APIServer

    %% Click Events
    click APIServer "https://github.com/y1ssh/s-agents-practice/blob/main/Sql Agent/src/app.py"
    click AgentEngine "https://github.com/y1ssh/s-agents-practice/blob/main/Sql Agent/src/agent.py"
    click Config "https://github.com/y1ssh/s-agents-practice/blob/main/Sql Agent/src/config.py"
    click PromptRepo "https://github.com/y1ssh/s-agents-practice/blob/main/Sql Agent/PROMPT.md"
    click READMERoot "https://github.com/y1ssh/s-agents-practice/blob/main/README.md"
    click AgentDoc "https://github.com/y1ssh/s-agents-practice/blob/main/Sql Agent/README.md"
    click Requirements "https://github.com/y1ssh/s-agents-practice/blob/main/Sql Agent/requirements.txt"

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#0366d6,color:#000
    classDef data fill:#DFFFE0,stroke:#22863a,color:#000
    classDef external fill:#FFE0B2,stroke:#d93f0b,color:#000
    classDef doc fill:#FFF5B2,stroke:#dbab09,color:#000
```
