An end-to-end retail analytics platform combining ML models, intelligent agents, and an interactive dashboard to give supermarket managers actionable insights on customers, inventory, profit, and product recommendations.

• Overview
• Architecture
• Project Structure
• Models
• Agents
• Dashboard
• Installation
• Usage
• Data Flow
• Configuration
• Dependencies

Supermarket AI is built around three core pillars: https://automart-ai-q53a5utpzascgl8rpolcmw.streamlit.app/

CSV Files
  supermarket_dummy_data.csv ──→ utils/preprocessing.py ──→ Enriched DataFrame
  transaction_dataset.csv    ──→ models/apriori_model.py ──→ Association Rules

Enriched DataFrame
  ├──→ models/kmeans_model.py    ──→ Customer Clusters
  │      └──→ agents/customer_agent.py   ──→ High/Low Value + Insights
  │
  ├──→ models/lstm_pytorch.py    ──→ Next-Day Sales Prediction
  │
  ├──→ agents/inventory_agent.py ──→ Demand / Stock / Festival Insights
  │
  └──→ agents/profit_agent.py    ──→ Profit / Loss Analysis

Association Rules
  └──→ agents/recommendation_agent.py ──→ Product Bundle Suggestions

All Agent Outputs
  ├──→ app/dashboard.py   (Streamlit UI)
  └──→ main.py            (CLI output)

supermarket-ai/
│
├── data/
│   ├── supermarket_dummy_data.csv   # Main sales dataset
│   └── transaction_dataset.csv      # Transaction records for basket analysis
│
├── utils/
│   └── preprocessing.py             # Data loading & feature engineering pipeline
│
├── models/
│   ├── kmeans_model.py              # Customer segmentation (K-Means)
│   ├── apriori_model.py             # Product recommendations (Apriori)
│   └── lstm_pytorch.py              # Sales forecasting (LSTM)
│
├── agents/
│   ├── customer_agent.py            # Customer value segmentation + insights
│   ├── inventory_agent.py           # Demand, stock, and festival tracking
│   ├── profit_agent.py              # Product and store-level profit analysis
│   └── recommendation_agent.py      # Cross-sell and bundling opportunities
│
├── app/
│   └── dashboard.py                 # Streamlit web dashboard
│
├── main.py                          # CLI entry point
└── requirements.txt                 # Python dependencies

Groups customers into Low / Medium / High Value segments based on purchase behaviour.

Pipeline: Aggregate by Customer ID → Normalize with StandardScaler → Apply KMeans(n_clusters=3) → Rank by profit

Answers the question: "If a customer buys Product A, how likely are they to buy Product B?"

Pipeline: Load transaction_dataset.csv → Build basket matrix → Run Apriori (min_support=0.01) → Generate rules (min_lift=1) → Sort by lift

Predicts next-day total sales quantity using a recurrent neural network trained on historical daily sales.

Model Architecture:

Input: [batch, 7 days, 1 feature]
  → LSTM(input_size=1, hidden_size=50, batch_first=True)
  → Linear(50 → 1)
Output: Predicted next-day quantity (single float)

Pipeline: Aggregate daily sales → Create 7-day sliding window sequences → Train for 10 epochs (MSELoss + Adam) → Predict from last 7 days

Each agent exposes a single *_agent_summary() master function used by both the dashboard and CLI. Models are pure ML; agents add the business interpretation on top.

Segments customers and generates marketing strategies. Uses Google Gemini via LangChain if GEMINI_API_KEY is set, otherwise falls back to rule-based logic:

• Profit > 500 → Offer loyalty rewards
• Profit < 200 → Provide discounts
• Otherwise → Target with promotions

Tracks product demand, flags low-stock items, calculates restock quantities, and surfaces festival-driven demand spikes.

Restock Formula:

If Quantity_Sold < 100:  restock = 150 - Quantity_Sold
Else:                    restock = 0   (no action needed)

Analyses profitability at the product level and store level. Identifies top performers and products running at a loss.

Uses the Apriori model to surface product bundling and cross-sell opportunities. Reads from transaction_dataset.csv.

Launch the interactive Streamlit dashboard:

streamlit run app/dashboard.py

Page 1 — Sales & Inventory

• Sales trend line chart
• One-click LSTM next-day sales prediction
• Top profitable products bar chart
• Low-stock alerts and restock suggestions
• Festival demand highlights

Page 2 — Customers & Recommendations

• Interactive customer segmentation table
• High-value and low-value customer breakdowns
• AI-powered marketing insights
• Top product association rules

1. Clone the repository

git clone https://github.com/your-username/supermarket-ai.git
cd supermarket-ai

2. Create a virtual environment (recommended)

python -m venv venv
source venv/bin/activate        # macOS/Linux
venv\Scripts\activate           # Windows

3. Install dependencies (CPU-only for deployment)

Local (Windows/macOS/Linux):

pip install -r requirements.txt

Streamlit Cloud (Deploy Ready):

Platform auto-installs from files:
- packages.txt: empty (no apt deps)
- requirements-pytorch.txt: torch/torchvision/torchaudio (CPU auto-select)
- requirements.txt: standard deps (streamlit etc.)

No manual pip; push to GitHub → deploy succeeds without --index-url or apt errors.

Compatible with CPU-only environments like Streamlit Cloud.

4. (Optional) Set your Google Gemini API key for AI-powered insights

export GEMINI_API_KEY="your-api-key-here"   # macOS/Linux
set GEMINI_API_KEY=your-api-key-here        # Windows

streamlit run app/dashboard.py

python main.py

The CLI runner executes every pipeline step in order and prints results to the terminal. Each step is wrapped in try/except so a single failure won't crash the entire run.

The preprocessing module is called once at startup — both main.py and dashboard.py pass the same enriched DataFrame to every downstream component, avoiding duplicate file reads.

The system works out of the box without any configuration. The only optional setting is:

• Single preprocessing call — preprocess_data() runs once; the enriched DataFrame is passed to every component.
• Agent pattern — Each agent exposes one *_summary() master function, keeping the dashboard and CLI interfaces clean.
• Graceful AI fallback — The Customer Agent tries Google Gemini first but always falls back to rule-based insights, so the system works without any API key.
• Models vs. Agents separation — Models are pure ML (no business logic). Agents add the business interpretation on top of model outputs.
• Error isolation — Every step in main.py is wrapped in try/except so a single model failure doesn't crash the entire pipeline.

Built with ❤️ using Python, PyTorch, and Streamlit