Hose Supervisor - Analytics

Leia isto em Português

This project consists of a Streamlit-based web interface developed to act as the interactive front-end for the Sales Intelligence and Supply Chain Sales Supervisor and Strategist Agent hosted on Databricks.

Index

• The Problem
• Agent Architecture
  • The Gatekeeper
  • Data Specialists
  • The Strategist
• Front-End Architecture
• Persistence and History
• Project Structure
• How to Configure and Run
  • Environment Variables Configuration
  • Running via Docker (Recommended)
  • Local Execution
• Code Quality and Formatting

---

The Problem

The default Databricks agent interface (Playground) has significant UI/UX rendering limitations, especially regarding the dynamic generation of interactive charts (Plotly/ECharts) and fluid manipulation of DataFrames in agent orchestration environments (where a supervisor agent calls other agents, in my case, structured as Genies, to respond to the user).

This Streamlit application solves this restriction. The tool orchestration, data crossing, and LLM model inference remain centralized in the back-end (Databricks), while structured JSON responses are captured and processed natively in Python for clean and professional visual rendering of insights and Business Intelligence.

---

Agent Architecture

The project scope exclusively serves the "Hoses" product family. Routing follows a structured and validated pipeline.

The Gatekeeper

For any inquiry involving a specific SKU or product code, the agent first triggers the check_is_hose function. If the validation returns false, indicating the product is not in the Hoses category, the agent has the necessary autonomy and governance to immediately stop the analytical flow execution.

Data Specialists

The architecture prohibits statistical guessing, depending solely on deterministic functions based on a rigorous routing prompt:

• Volume and Margin: Responsible for the static photography of results (Gross Margin, COGS, Net Revenue). It exactly calculates customer or merchandise billing and profits in closed periods.
• Trend Analysis: The structural investigative specialist. It works by crossing specific sales time windows, calculating percentage Deltas to point out top offenders, customer churn, and major levers, focusing only on the gross sales branch.
• Inventory: Evaluates physical flow and inventory, reporting blocked, quality-controlled, or shelf-available products. Usually activated to validate rupture hypotheses in products that suffered abrupt billing drops.
• Production: Analyzes Work In Progress (WIP) on the factory floor, production delays, pending manufacturing order schedules, and temporal bottlenecks in assembly lines, answering the premise "when will the product be available?".

The Strategist

Upon obtaining all crossed data from the previous areas, the Supervisor assumes the role of Consulting Strategist. The response delivered to the user is executive, drawing smart connections (example: the sharp drop in billing in an SKU by X% occurred due to a stop and delay in Production cycles). Focused action plans are generated in a unified format in the chat body, while complementary charts illustrate the metric.

---

Front-End Architecture

• Core Framework: Streamlit for responsive request control.
• Graphics Engine: Plotly for dynamic and interactive data visualization.
• Modular Isolation: Code organized into utility packages (app/utils) and data schemas (app/schemas).
• Code Comments: All internal technical code documentation is in English to maintain international development standards.

---

Persistence and History

Unlike purely stateless systems, this project implements full persistence:

• Database: Uses PostgreSQL to store conversations.
• ORM: SQLAlchemy manages the data layer and schemas.
• Sidebar History: The sidebar menu dynamically loads past conversations from the database, allowing previous analyses to be resumed with one click.

---

Project Structure

supervisor-mangueiras/
├── app/                      # Application source code
│   ├── assets/               # Images and logos
│   ├── config/               # Database configurations (engine)
│   ├── schemas/              # Data models (SQLAlchemy)
│   ├── utils/                # Utilities (Extraction, UI, DB, Plotly)
│   └── app.py                # Streamlit entry point
├── .streamlit/               # Streamlit configurations
├── .dockerignore
├── .env                      # Environment variables (Secrets and Hosts)
├── .gitignore
├── docker-compose.yml        # Manifesto for multi-service Dockerized execution
├── Dockerfile                # OS Recipe + Framework for containerized environment
├── requirements.txt          # Execution dependencies
├── run.py                    # Auxiliary execution script
└── README.md                 # You are here

---

How to Configure and Run

Environment Variables Configuration

Create a .env file at the root of the repository containing Databricks account credentials and the Agent Endpoint source:

# Databricks
DATABRICKS_HOST=https://your-workspace.databricks.com
DATABRICKS_TOKEN=your_token
ENDPOINT_NAME=your_endpoint
CHART_DATA_JSON_FUNCTION=your_function_that_converts_data_into_json_on_databricks

# Database
POSTGRES_USER=user
POSTGRES_PASSWORD=password
POSTGRES_DB=supervisor_db
DB_HOST=postgres-db
DB_PORT=5432

Local Execution (Virtual Environment)

To run the application natively by separating all dependencies in your environment, it is recommended to use a native Python venv:

1. Create the virtual environment (venv):

python -m venv venv

2. Activate the environment:

• On Windows (Prompt/PowerShell):

  venv\Scripts\activate

• On Linux / macOS:

  source venv/bin/activate

3. Install required dependencies in the repository:

pip install -r requirements.txt

4. Start the Streamlit server:

streamlit run app.py

Running via Docker (Recommended)

The project uses docker-compose to spin up both the interface and the database in an integrated way:

1. Build the Docker image and start the services in detach mode:

docker-compose up -d --build

Access at: http://localhost:8501.

Local Execution

1. Install dependencies: pip install -r requirements.txt
2. Ensure you have a local Postgres running and adjust the .env.
3. Run via helper script:

python run.py

---

Code Quality and Formatting

Linting with Flake8

Check for code style issues:

flake8 app/

Formatting with Black

Automatically format your Python code to follow PEP 8 conventions:

black app/

To check without modifying files:

black --check app/