# akshayrohilla-ai/ai-vm-analytics-assistant architecture

> Architecture diagram of the GitHub repository akshayrohilla-ai/ai-vm-analytics-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akshayrohilla-ai/ai-vm-analytics-assistant
- Repository: https://github.com/akshayrohilla-ai/ai-vm-analytics-assistant

## Overview

1. **Overall shape**
   - This is a small, Python-based AI assistant with a **single-user interactive front end** and a **server-side query pipeline** that turns natural language into SQL and runs it against PostgreSQL.
   - The repository is organized more like an application prototype than a multi-service system.

2. **Primary entry point**
   - `app.py` is the main runtime entry point called out by the README.
   - It likely hosts the **Streamlit chat UI**, handles user input, and displays the generated answer/results.

3. **Query orchestration layer**
   - `sql_assistant.py` appears to contain the main assistant logic: prompt construction, LLM invocation, SQL generation, validation/guardrails, and retry handling.
   - This is the central coordination layer between the UI, the model, and the database.

4. **Database access layer**
   - `sql_assistant_db.py` is the persistence/infrastructure boundary.
   - It likely encapsulates PostgreSQL connection details and query execution so the assistant logic does not talk to the database directly.
   - The README indicates the data is primarily a **single table** (`vm_data`), which simplifies the schema boundary.

5. **LLM / model dependency**
   - The assistant uses **Ollama** with the **Phi3** local model for natural-language-to-SQL generation.
   - This is an external runtime dependency, but it is local/on-machine rather than a cloud API, which affects deployment and latency.

6. **End-to-end data flow**
   - The main flow is: **user question in Streamlit → assistant builds prompt/context → LLM generates SQL → validation/guardrails check the SQL → PostgreSQL executes the query → results are returned to the UI**.
   - The architecture is therefore a classic **chat-to-query execution pipeline** with a feedback loop for fixing bad SQL.

7. **Guardrails and retry boundary**
   - A key architectural feature is the **SQL validation layer** before execution.
   - The README explicitly mentions protection against invalid or hallucinated queries plus an automatic retry mechanism, so the assistant likely has a “generate → validate → repair” loop rather than trusting the first model output.

8. **Schema and domain assumptions**
   - The system is built around **VM analytics**: counts, CPU usage, memory, location-based filters, and similar operational questions.
   - This means the prompt and validation logic are probably tuned to a constrained domain vocabulary and column mapping, not generic SQL over arbitrary schemas.

9. **Alternative / experimental app path**
   - `rag_app.py` suggests an alternate implementation or experiment, likely a **RAG-enhanced** version of the assistant.
   - In architecture terms, treat this as a parallel UI/flow variant rather than the core path unless you confirm it is used by `app.py`.

10. **Support files and artifacts**
   - `data.txt`, `output.txt`, and `test.py` look like supporting artifacts for sample data, captured output, or local testing.
   - `main.py` may be a secondary launcher or development entry point, but the README points to `app.py` as the canonical run target.

11. **Operational boundaries**
   - The main external boundary is the **PostgreSQL database**; the main AI boundary is **Ollama/Phi3**.
   - Everything else is local Python code, so the architecture is mostly a thin application layer around those two dependencies.

12. **What to diagram**
   - For an accurate architecture diagram, draw:
     - a **Streamlit UI** front end,
     - a **query assistant/orchestration component**,
     - an **LLM service via Ollama**,
     - a **SQL validation/retry step**,
     - a **PostgreSQL database** with `vm_data`,
     - and a return path for formatted results back to the UI.

Main entry points: [`sql_assistant.py`](https://github.com/akshayrohilla-ai/ai-vm-analytics-assistant/blob/main/sql_assistant.py) (Assistant), [`sql_assistant_db.py`](https://github.com/akshayrohilla-ai/ai-vm-analytics-assistant/blob/main/sql_assistant_db.py) (DB layer), [`app.py`](https://github.com/akshayrohilla-ai/ai-vm-analytics-assistant/blob/main/app.py) (app.py), [`main.py`](https://github.com/akshayrohilla-ai/ai-vm-analytics-assistant/blob/main/main.py) (main.py)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI"]
  node_app_py["app.py<br/>entrypoint<br/>[app.py]"]
  node_streamlit_ui(("Chat UI<br/>streamlit front end"))
  node_main_py["main.py<br/>launcher<br/>[main.py]"]
  node_test_harness["test.py<br/>dev harness<br/>[test.py]"]
end

subgraph group_core["Core"]
  node_assistant_core["Assistant<br/>orchestrator<br/>[sql_assistant.py]"]
  node_prompt_builder["Prompting<br/>context builder"]
  node_sql_generator{{"SQL gen<br/>llm query synthesis"}}
  node_sql_guardrails(("Guardrails<br/>sql validation"))
  node_result_formatter["Formatter<br/>response shaping"]
end

subgraph group_data["Data"]
  node_db_layer["DB layer<br/>postgres access"]
  node_vm_data[("vm_data<br/>domain table")]
  node_sample_data["Samples<br/>support artifact<br/>[data.txt]"]
  node_sample_output["Output<br/>support artifact<br/>[output.txt]"]
end

subgraph group_external["External"]
  node_ollama_phi3{{"Ollama Phi3<br/>local llm"}}
  node_postgresql[("PostgreSQL<br/>database runtime")]
end

subgraph group_alt["Alt flow"]
  node_rag_app_py["rag_app.py<br/>alt entrypoint<br/>[rag_app.py]"]
end

node_app_py -->|"hosts"| node_streamlit_ui
node_streamlit_ui -->|"asks"| node_assistant_core
node_assistant_core -->|"builds"| node_prompt_builder
node_prompt_builder -->|"prompts"| node_ollama_phi3
node_ollama_phi3 -->|"returns SQL"| node_sql_generator
node_sql_generator -->|"checks"| node_sql_guardrails
node_sql_guardrails -.->|"repair loop"| node_assistant_core
node_sql_guardrails -->|"executes"| node_db_layer
node_db_layer -->|"connects"| node_postgresql
node_postgresql -->|"queries"| node_vm_data
node_db_layer -->|"returns rows"| node_assistant_core
node_assistant_core -->|"formats"| node_result_formatter
node_result_formatter -->|"renders"| node_streamlit_ui
node_rag_app_py -.->|"alternative flow"| node_assistant_core
node_main_py -.->|"launches"| node_assistant_core
node_test_harness -.->|"exercises"| node_assistant_core
node_sample_data -.->|"informs"| node_prompt_builder
node_sample_output -.->|"illustrates"| node_result_formatter

click node_app_py "https://github.com/akshayrohilla-ai/ai-vm-analytics-assistant/blob/main/app.py"
click node_rag_app_py "https://github.com/akshayrohilla-ai/ai-vm-analytics-assistant/blob/main/rag_app.py"
click node_main_py "https://github.com/akshayrohilla-ai/ai-vm-analytics-assistant/blob/main/main.py"
click node_assistant_core "https://github.com/akshayrohilla-ai/ai-vm-analytics-assistant/blob/main/sql_assistant.py"
click node_db_layer "https://github.com/akshayrohilla-ai/ai-vm-analytics-assistant/blob/main/sql_assistant_db.py"
click node_sample_data "https://github.com/akshayrohilla-ai/ai-vm-analytics-assistant/blob/main/data.txt"
click node_sample_output "https://github.com/akshayrohilla-ai/ai-vm-analytics-assistant/blob/main/output.txt"
click node_test_harness "https://github.com/akshayrohilla-ai/ai-vm-analytics-assistant/blob/main/test.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_py,node_streamlit_ui,node_main_py,node_test_harness toneBlue
class node_assistant_core,node_prompt_builder,node_sql_generator,node_sql_guardrails,node_result_formatter toneAmber
class node_db_layer,node_vm_data,node_sample_data,node_sample_output toneMint
class node_ollama_phi3,node_postgresql toneRose
class node_rag_app_py toneIndigo
```

## Components

### UI

User-facing interactive entry points

- [app.py](https://github.com/akshayrohilla-ai/ai-vm-analytics-assistant/blob/main/app.py): entrypoint · Main Streamlit runtime entry point · `app.py`
- **Chat UI**: streamlit front end · Single-user interactive interface for questions and answers
- [main.py](https://github.com/akshayrohilla-ai/ai-vm-analytics-assistant/blob/main/main.py): launcher · Secondary launcher or development entry point · `main.py`
- [test.py](https://github.com/akshayrohilla-ai/ai-vm-analytics-assistant/blob/main/test.py): dev harness · Local script for exercising the assistant · `test.py`

### Core

Assistant orchestration and execution logic

- [Assistant](https://github.com/akshayrohilla-ai/ai-vm-analytics-assistant/blob/main/sql_assistant.py): orchestrator · Coordinates prompt building, SQL generation, validation, and retries · `sql_assistant.py`
- **Prompting**: context builder · Builds domain context and instructions for the model
- **SQL gen**: llm query synthesis · Turns natural language into candidate SQL
- **Guardrails**: sql validation · Checks generated SQL and triggers repair or retry when needed
- **Formatter**: response shaping · Formats query results for the UI

### Data

Persistent data access and domain schema

- [DB layer](https://github.com/akshayrohilla-ai/ai-vm-analytics-assistant/blob/main/sql_assistant_db.py): postgres access · Encapsulates connection and query execution · `sql_assistant_db.py`
- **vm_data**: domain table · Primary PostgreSQL table for VM analytics
- [Samples](https://github.com/akshayrohilla-ai/ai-vm-analytics-assistant/blob/main/data.txt): support artifact · Local example or captured data used for development · `data.txt`
- [Output](https://github.com/akshayrohilla-ai/ai-vm-analytics-assistant/blob/main/output.txt): support artifact · Local captured output or example responses · `output.txt`

### External

Local model and database dependencies

- **Ollama Phi3**: local llm · Local model used for natural-language-to-SQL generation
- **PostgreSQL**: database runtime · External database engine that executes SQL

### Alt flow

Experimental or secondary app path

- [rag_app.py](https://github.com/akshayrohilla-ai/ai-vm-analytics-assistant/blob/main/rag_app.py): alt entrypoint · Alternative or experimental assistant app path · `rag_app.py`

## Connections

- app.py → Chat UI: hosts · Runs the interactive chat interface
- Chat UI → Assistant: asks · User questions are passed into the assistant pipeline
- Assistant → Prompting: builds · Creates schema-aware instructions and context
- Prompting → Ollama Phi3: prompts · Sends the constructed prompt to the local model
- Ollama Phi3 → SQL gen: returns SQL · Model output is treated as a candidate query
- SQL gen → Guardrails: checks · Candidate SQL is validated before execution
- Guardrails → Assistant: repair loop · Invalid SQL can be sent back for regeneration or retry
- Guardrails → DB layer: executes · Validated SQL is handed to the database access layer
- DB layer → PostgreSQL: connects · Uses PostgreSQL as the execution engine
- PostgreSQL → vm_data: queries · Primary table queried for VM analytics
- DB layer → Assistant: returns rows · Query results come back to the assistant orchestration
- Assistant → Formatter: formats · Shapes results into a user-friendly answer
- Formatter → Chat UI: renders · Formatted answer is displayed in the chat UI
- rag_app.py → Assistant: alternative flow · Secondary app path likely reuses or adapts the core assistant
- main.py → Assistant: launches · Possible secondary entry point into the same backend flow
- test.py → Assistant: exercises · Local script for testing assistant behavior
- Samples → Prompting: informs · Example data may support development or prompt tuning
- Output → Formatter: illustrates · Captured output may inform response formatting
