Skip to content

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository
BranchesTags

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

InsightFlow Banner
Python FastAPI Streamlit OpenAI Plotly Pandas



🔮 InsightFlow

AI-Powered Sales Analytics Assistant

Natural language querying. Automated insights. Interactive visualizations.


📋 Table of Contents

🎯 Overview

InsightFlow is an intelligent analytics platform that transforms how businesses interact with sales data. Built with FastAPI, Streamlit, OpenAI, and Plotly, it enables users to upload CSV datasets and query them using natural language — receiving AI-generated insights, automated KPI calculations, interactive visualizations, and trend analysis in seconds.

No SQL. No complex queries. Just ask.

What It Does

Capability Description
Natural Language Queries Ask questions like "What were top selling products last quarter?" and get AI-powered answers
Automated KPI Generation Auto-computes revenue, orders, AOV, growth rate, and more from any sales CSV
Interactive Visualizations Generates Plotly charts: line, bar, pie, scatter, heatmap, histogram
Trend Analysis Identifies trends, seasonality, and growth patterns over time
AI-Powered Insights OpenAI generates summaries, narratives, and actionable recommendations
CSV Data Ingestion Simple drag-and-drop upload with auto-detection of column types

✨ Key Features

🤖 AI Analytics Assistant

  • Natural language querying powered by OpenAI GPT-4o
  • Context-aware responses using dataset metadata
  • Automated insight generation with confidence scoring
  • Business narrative generation for KPIs and trends

📊 Smart Dashboard

  • Auto-generated KPI cards with key metrics
  • Revenue trend visualization with time-series analysis
  • Product performance comparisons
  • Customer segmentation breakdowns

💬 Conversational Interface

  • Chat-based interaction with AI
  • Persistent conversation history
  • Quick question suggestions
  • Chart recommendations from AI

📈 Advanced Visualizations

  • Bar Charts — Top products, customers, categories
  • Line Charts — Revenue trends over time
  • Pie/Donut Charts — Market share distribution
  • Scatter Plots — Correlation analysis
  • Heatmaps — Correlation matrices
  • Histograms — Distribution analysis

🔧 Data Processing

  • Automatic column type detection
  • Data cleaning and optimization
  • Structured query execution (filter, group, aggregate)
  • Statistical summary generation
  • Trend and seasonality detection

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Streamlit UI                         │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐   │
│  │Dashboard │ │ AI Chat  │ │ Trends   │ │  Data Explorer│   │
│  │ (KPIs)   │ │(ChatGPT) │ │(Analysis)│ │ (Filtering)   │   │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └──────┬───────┘   │
│       └─────────────┴────────────┴────────────────┘          │
└───────────────────────────┬─────────────────────────────────┘
                            │ HTTP/REST
┌───────────────────────────┴─────────────────────────────────┐
│                      FastAPI Backend                        │
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌─────────────────┐   │
│  │ Data Router  │  │Insights Router│  │Health Endpoint   │   │
│  │              │  │              │  │                  │   │
│  │ • Upload     │  │ • Ask AI     │  │ • /health        │   │
│  │ • Preview    │  │ • Generate   │  │ • /              │   │
│  │ • Summary    │  │ • Summarize  │  │                  │   │
│  │ • KPIs       │  │ • Narrate    │  │                  │   │
│  │ • Query      │  │ • Suggest    │  │                  │   │
│  │ • Trends     │  │              │  │                  │   │
│  │ • Charts     │  │              │  │                  │   │
│  └──────┬───────┘  └──────┬───────┘  └─────────────────┘   │
│         │                  │                                │
│  ┌──────▼───────┐  ┌──────▼───────┐  ┌─────────────────┐   │
│  │Data Service  │  │  AI Service  │  │ Viz Service      │   │
│  │              │  │              │  │                  │   │
│  │ • Pandas     │  │ • OpenAI API │  │ • Plotly Charts  │   │
│  │ • Cleaning   │  │ • NL Query   │  │ • Theme Engine   │   │
│  │ • Analytics  │  │ • Summaries  │  │ • KPI Cards      │   │
│  │ • Filtering  │  │ • Insights   │  │ • Suggestions    │   │
│  └──────────────┘  └──────────────┘  └─────────────────┘   │
└─────────────────────────────────────────────────────────────┘

📸 Screenshots

Dashboard View

Dashboard Preview



AI Chat Interface

AI Chat Preview

🚀 Quick Start

Prerequisites

  • Python 3.10+
  • OpenAI API key

Option 1: Automated Setup (Recommended)

# 1. Clone the repository
git clone https://github.com/yourusername/insightflow.git
cd insightflow

# 2. Copy environment file
cp .env.example .env
# Edit .env and add your OPENAI_API_KEY

# 3. Start everything (Unix/Linux/macOS)
chmod +x start.sh
./start.sh all

# Or on Windows
start.bat all

Access the app:

Option 2: Manual Setup

# 1. Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 2. Install dependencies
pip install -r requirements.txt

# 3. Configure environment
cp .env.example .env
# Edit .env and add your OPENAI_API_KEY

# 4. Start API server
python run.py api

# 5. In another terminal, start Streamlit
python run.py ui

🔧 Installation

System Requirements

Component Requirement
Python 3.10 or higher
RAM 4GB minimum, 8GB recommended
Disk 500MB for installation
Network Internet (for OpenAI API)

Step-by-Step

1. Clone Repository

git clone https://github.com/yourusername/insightflow.git
cd insightflow

2. Create Virtual Environment

# macOS/Linux
python3 -m venv venv
source venv/bin/activate

# Windows
python -m venv venv
venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

4. Configure Environment

cp .env.example .env

Edit .env and set your OpenAI API Key:

OPENAI_API_KEY=sk-your-api-key-here

5. Launch Application

# Start both API and UI
python run.py all

⚙️ Configuration

Environment Variables

Variable Required Default Description
OPENAI_API_KEY Yes — Your OpenAI API key
OPENAI_MODEL No gpt-4o OpenAI model to use
API_HOST No 0.0.0.0 FastAPI host address
API_PORT No 8000 FastAPI port
STREAMLIT_PORT No 8501 Streamlit port
API_BASE_URL No http://localhost:8000 URL for Streamlit to connect to API
MAX_UPLOAD_SIZE_MB No 50 Maximum CSV upload size
API_DEBUG No true Enable FastAPI debug mode

OpenAI API Key

Get your API key from OpenAI Platform

📖 API Documentation

Interactive Docs

Once the API is running, access interactive documentation:

Core Endpoints

Data Management

Method Endpoint Description
POST /api/v1/data/upload Upload CSV file
GET /api/v1/data/datasets List all datasets
GET /api/v1/data/datasets/{id} Get dataset info
DELETE /api/v1/data/datasets/{id} Delete dataset
GET /api/v1/data/datasets/{id}/preview Preview data
GET /api/v1/data/datasets/{id}/summary Statistical summary
GET /api/v1/data/datasets/{id}/kpis Compute KPIs
GET /api/v1/data/datasets/{id}/trends Trend analysis
POST /api/v1/data/datasets/{id}/query Execute query
POST /api/v1/data/datasets/{id}/chart Generate chart

AI Insights

Method Endpoint Description
POST /api/v1/insights/ask Ask natural language question
POST /api/v1/insights/generate Generate AI insight
GET /api/v1/insights/datasets/{id}/summary Summarize dataset
GET /api/v1/insights/datasets/{id}/kpi-narrative KPI narrative
POST /api/v1/insights/suggest-charts Suggest visualizations

Health

Method Endpoint Description
GET / Root info
GET /health Health check

Example: Upload CSV

curl -X POST "http://localhost:8000/api/v1/data/upload" \
  -F "file=@sales_data.csv"

Response:

{
  "dataset_id": "a1b2c3d4",
  "message": "File uploaded successfully",
  "info": {
    "filename": "sales_data.csv",
    "rows": 5000,
    "columns": 12,
    "column_names": ["order_id", "date", "customer", ...],
    "memory_usage_mb": 2.3
  }
}

Example: Ask AI Question

curl -X POST "http://localhost:8000/api/v1/insights/ask" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the top 5 products by revenue?",
    "dataset_id": "a1b2c3d4"
  }'

Response:

{
  "answer": "The top 5 products by revenue are: 1. Laptop Elite X1 ($892K), 2. Monitor 4K HDR ($456K), 3. Smart Watch Ultra ($398K), ...",
  "confidence": 0.90,
  "suggested_charts": [...]
}

Example: Get KPIs

curl "http://localhost:8000/api/v1/data/datasets/a1b2c3d4/kpis"

Response:

{
  "total_revenue": 6946664.03,
  "total_orders": 38492,
  "average_order_value": 180.47,
  "unique_customers": 25,
  "top_product": "Laptop Elite X1",
  "top_product_revenue": 892345.00,
  "growth_rate": 12.5
}

📘 Usage Guide

1. Upload Your Data

  1. Open the Streamlit UI at http://localhost:8501
  2. Drag and drop your CSV file in the sidebar, or click "Load Sample Data"
  3. The system auto-detects columns and computes statistics

Expected CSV Format:

order_id,order_date,customer_name,product_name,category,quantity,unit_price,revenue,region
ORD-001,2024-01-15,Acme Corp,Laptop Elite X1,Computers,5,1499.00,7495.00,North America

Auto-detected columns:

  • revenue, sales, amount → Revenue metrics
  • product, item, sku → Product identifiers
  • customer, client → Customer identifiers
  • date, timestamp → Time-series analysis
  • quantity, qty → Order volume

2. Explore the Dashboard

After uploading, the Dashboard tab shows:

  • 6 KPI Cards — Total Revenue, Orders, AOV, Customers, Top Product, Growth
  • Revenue Chart — Time-series trend visualization
  • Product Breakdown — Top performers by category
  • Customer Analysis — Top customers by revenue

3. Chat with AI

Switch to the AI Chat tab:

  1. Type natural language questions
  2. Get AI-generated insights with context
  3. View suggested charts based on your question

Example questions:

  • "What are the top selling products?"
  • "Show me revenue trends over time"
  • "Which region has the highest sales?"
  • "What is the average order value?"
  • "Identify any sales anomalies"

4. Analyze Trends

In the Trends tab:

  1. Select a numeric metric (e.g., revenue)
  2. Choose time period (Daily, Weekly, Monthly, Quarterly)
  3. View trend direction, change percentage, and historical data

5. Explore Data

The Explore tab provides:

  • Interactive data filtering
  • Summary statistics
  • Correlation matrix heatmap
  • Custom chart builder

📁 Project Structure

insightflow/
├── app/                          # FastAPI Backend
│   ├── __init__.py
│   ├── main.py                   # FastAPI app entry point
│   ├── models/
│   │   ├── __init__.py
│   │   └── schemas.py            # Pydantic models (DTOs)
│   ├── routers/
│   │   ├── __init__.py
│   │   ├── data.py               # Data management endpoints
│   │   └── insights.py           # AI insight endpoints
│   ├── services/
│   │   ├── __init__.py
│   │   ├── data_service.py       # Data processing (Pandas)
│   │   ├── ai_service.py         # OpenAI integration
│   │   └── visualization.py      # Plotly chart generation
│   └── utils/
│       ├── __init__.py
│       └── helpers.py            # Utility functions
│
├── streamlit_app/                # Streamlit Frontend
│   ├── __init__.py
│   └── app.py                    # Main Streamlit application
│
├── data/
│   └── sample_sales.csv          # Sample dataset (4,000+ records)
│
├── assets/
│   ├── banner.png                # Project banner
│   ├── dashboard-preview.jpg     # Dashboard screenshot
│   └── chat-preview.jpg          # Chat interface screenshot
│
├── requirements.txt              # Python dependencies
├── .env.example                  # Environment template
├── .gitignore                    # Git ignore rules
├── run.py                        # Python launcher
├── start.sh                      # Unix startup script
├── start.bat                     # Windows startup script
└── README.md                     # This file

🛠️ Technology Stack

Backend

Technology Version Purpose
Python 3.10+ Core language
FastAPI 0.115+ Web framework
Uvicorn 0.32+ ASGI server
Pandas 2.2+ Data processing
NumPy 2.1+ Numerical computing
OpenAI 1.55+ AI/LLM integration
Pydantic 2.10+ Data validation

Frontend

Technology Version Purpose
Streamlit 1.40+ UI framework
Plotly 5.24+ Interactive charts

DevOps

Technology Purpose
python-dotenv Environment management
pytest Testing

⚡ Performance

Metric Value
CSV Upload (10K rows) ~200ms
KPI Computation ~50ms
AI Insight Generation ~2-3s (depends on OpenAI)
Chart Generation ~100ms
Trend Analysis ~150ms
Concurrent Users 50+ (Streamlit limitation)

Optimization Notes

  • In-memory data store (no database needed for prototyping)
  • Pandas vectorized operations for analytics
  • Async FastAPI endpoints for non-blocking I/O
  • Plotly JSON serialization for efficient chart transfer

🗺️ Roadmap

Phase 1: Foundation ✅

  • FastAPI backend with CSV upload
  • KPI auto-generation
  • Basic visualizations (bar, line, pie)
  • OpenAI integration for Q&A
  • Streamlit dashboard

Phase 2: Enhancement

  • User authentication & sessions
  • Persistent database (PostgreSQL)
  • Advanced filtering & segmentation
  • Report export (PDF, Excel)
  • Multi-dataset comparison
  • Custom dashboard builder

Phase 3: Enterprise

  • Real-time data streaming
  • Scheduled report automation
  • Team collaboration features
  • Advanced AI models (fine-tuned)
  • REST API rate limiting & caching
  • Docker containerization
  • Cloud deployment templates (AWS/GCP/Azure)

🤝 Contributing

We welcome contributions! Here's how:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing)
  5. Open a Pull Request

Development Setup

# Clone your fork
git clone https://github.com/YOUR_USERNAME/insightflow.git
cd insightflow

# Create dev environment
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Run in development mode
python run.py all

Code Style

  • Follow PEP 8 for Python code
  • Use type hints where possible
  • Add docstrings to functions and classes
  • Keep functions focused and modular

📝 License

This project is licensed under the MIT License.

MIT License

Copyright (c) 2025 InsightFlow

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

🙏 Acknowledgments

  • FastAPI — Amazing Python web framework
  • Streamlit — Effortless data app creation
  • OpenAI — Powerful AI capabilities
  • Plotly — Beautiful interactive visualizations
  • Pandas — The backbone of data science

Made with ❤️ and 🤖

Report Bug · Request Feature

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages