feat: Migrate to HuggingFace Spaces for 16GB free RAM

.spacesrc

@@ -0,0 +1,8 @@
+sdk: docker
+sdk_version: "3.12"
+app_file: src/api/app.py
+app_port: 7860
+emoji: 🤖
+colorFrom: blue
+colorTo: purple
+pinned: false

DEPLOYMENT_HUGGINGFACE.md

@@ -0,0 +1,204 @@
+# Deploying to HuggingFace Spaces 🤗
+
+This guide shows how to deploy the DevSprint Data Science Agent to HuggingFace Spaces with **16GB RAM for free** - perfect for memory-intensive data science workloads.
+
+## Why HuggingFace Spaces?
+
+- ✅ **16GB RAM** (vs Render's 512MB free tier)
+- ✅ **Completely free** for public Spaces
+- ✅ **Perfect for ML/AI demos**
+- ✅ **Persistent storage** for uploaded files
+- ✅ **Auto-restart** on crashes
+- ✅ **Built-in secrets management**
+
+## Prerequisites
+
+1. **HuggingFace Account**: Sign up at https://huggingface.co/join
+2. **Google Gemini API Key**: Get from https://aistudio.google.com/app/apikey
+3. **Git**: Installed locally
+
+## Quick Deployment
+
+### Step 1: Create a New Space
+
+1. Go to https://huggingface.co/new-space
+2. Fill in details:
+   - **Owner**: Your username
+   - **Space name**: `devs-print-data-science-agent` (or any name)
+   - **License**: MIT
+   - **Select the Space SDK**: Docker
+   - **Visibility**: Public (for free 16GB RAM)
+
+3. Click **Create Space**
+
+### Step 2: Set Up Repository
+
+After creating the Space, HuggingFace will show you a Git repository URL like:
+```
+https://huggingface.co/spaces/YOUR_USERNAME/devs-print-data-science-agent
+```
+
+### Step 3: Prepare Files
+
+**IMPORTANT**: Rename `Dockerfile.spaces` to `Dockerfile` and `README_SPACES.md` to `README.md` before pushing:
+
+```powershell
+# Backup original files
+Copy-Item Dockerfile Dockerfile.render
+Copy-Item README.md README_original.md
+
+# Use HuggingFace versions
+Copy-Item Dockerfile.spaces Dockerfile -Force
+Copy-Item README_SPACES.md README.md -Force
+```
+
+### Step 4: Push to HuggingFace
+
+```powershell
+# Add HuggingFace remote
+git remote add huggingface https://huggingface.co/spaces/YOUR_USERNAME/devs-print-data-science-agent
+
+# Push to HuggingFace
+git push huggingface main
+```
+
+**Note**: Use your HuggingFace username and access token (not password) for authentication.
+- Get access token: https://huggingface.co/settings/tokens
+
+### Step 5: Configure Secrets
+
+1. Go to your Space: `https://huggingface.co/spaces/YOUR_USERNAME/devs-print-data-science-agent`
+2. Click **Settings** tab
+3. Scroll to **Repository secrets**
+4. Click **New secret**
+5. Add:
+   - **Name**: `GEMINI_API_KEY`
+   - **Value**: Your Google Gemini API key
+6. Click **Save**
+
+### Step 6: Wait for Build
+
+HuggingFace will automatically:
+1. Build your Docker container (5-10 minutes)
+2. Deploy to 16GB RAM instance
+3. Show build logs in the **Logs** tab
+4. Start your app on port 7860
+
+Once deployed, your Space will be live at:
+```
+https://YOUR_USERNAME-devs-print-data-science-agent.hf.space
+```
+
+## Dockerfile Changes for Spaces
+
+The `Dockerfile.spaces` includes these HuggingFace-specific optimizations:
+
+1. **Port 7860**: HuggingFace Spaces standard port
+   ```dockerfile
+   ENV PORT=7860
+   EXPOSE 7860
+   CMD ["uvicorn", "src.api.app:app", "--host", "0.0.0.0", "--port", "7860"]
+   ```
+
+2. **Non-root user**: Security requirement
+   ```dockerfile
+   RUN useradd -m -u 1000 user
+   USER user
+   WORKDIR /home/user/app
+   ```
+
+3. **User-writable directories**: For uploads and outputs
+   ```dockerfile
+   ENV OUTPUT_DIR=/home/user/app/outputs
+   ENV CACHE_DB_PATH=/home/user/app/cache_db/cache.db
+   ```
+
+## README Metadata
+
+The `README_SPACES.md` includes YAML frontmatter required by HuggingFace:
+
+```yaml
+---
+title: DevSprint Data Science Agent
+emoji: 🤖
+colorFrom: blue
+colorTo: purple
+sdk: docker
+pinned: false
+license: mit
+app_port: 7860
+---
+```
+
+## Troubleshooting
+
+### Build Fails
+
+- Check **Logs** tab for errors
+- Common issue: Missing dependencies in `requirements.txt`
+- Solution: Add any missing packages and push again
+
+### App Crashes on Startup
+
+- Check if `GEMINI_API_KEY` is set in Repository secrets
+- Verify port 7860 is exposed in Dockerfile
+- Check logs for Python import errors
+
+### Memory Issues
+
+- HuggingFace Spaces provides 16GB RAM
+- Your memory optimization (sampling to 50k rows) will work great here
+- For even larger datasets (>100MB), consider increasing sample size in [src/tools/eda_reports.py](src/tools/eda_reports.py)
+
+### File Uploads Not Persisting
+
+- Files in `/home/user/app/outputs` persist between restarts
+- Temp files in `/tmp` are ephemeral (cleared on restart)
+- For production, consider using HuggingFace Datasets or external storage
+
+## Updating Your Space
+
+To push updates:
+
+```powershell
+# Make your changes locally
+git add .
+git commit -m "Your update message"
+
+# Push to both GitHub and HuggingFace
+git push origin main
+git push huggingface main
+```
+
+HuggingFace will automatically rebuild and redeploy.
+
+## Comparison: Render vs HuggingFace Spaces
+
+| Feature | Render (Free) | HuggingFace Spaces |
+|---------|---------------|-------------------|
+| RAM | 512MB | **16GB** ✅ |
+| CPU | Shared | Shared |
+| Storage | Ephemeral | Persistent |
+| Cost | Free | Free (public) |
+| Build Time | 3-5 min | 5-10 min |
+| Auto-restart | ✅ | ✅ |
+| Custom Domain | ❌ | ❌ |
+| Best For | Simple APIs | **ML/Data Science** ✅ |
+
+## Going to Production
+
+For private Spaces with more resources:
+
+- **HuggingFace Pro**: $9/mo for private Spaces
+- **Upgraded Hardware**: Up to 32GB RAM, GPUs available
+- **Custom domains**: Available with Pro
+
+## Support
+
+- **HuggingFace Docs**: https://huggingface.co/docs/hub/spaces-overview
+- **Community Forum**: https://discuss.huggingface.co/
+- **Status Page**: https://status.huggingface.co/
+
+---
+
+**Ready to deploy?** Follow the steps above and your agent will be live in 10-15 minutes! 🚀

Dockerfile

@@ -1,7 +1,11 @@
+# ===============================
+# HuggingFace Spaces Dockerfile
+# ===============================
+# Optimized for 16GB RAM, Port 7860
+
 # ===============================
 # Stage 1: Build Frontend
 # ===============================
-# Cache bust: 2025-12-28 fix
 FROM node:20-alpine AS frontend-builder
 
 WORKDIR /frontend
@@ -52,33 +56,38 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 COPY --from=builder /opt/venv /opt/venv
 ENV PATH="/opt/venv/bin:$PATH"
 
+# Create non-root user for HuggingFace Spaces
+RUN useradd -m -u 1000 user
+USER user
+
 # App working directory
-WORKDIR /app
+WORKDIR /home/user/app
 
-# Copy backend code
-COPY src/ /app/src/
-COPY examples/ /app/examples/
+# Copy backend code (as user)
+COPY --chown=user:user src/ ./src/
+COPY --chown=user:user examples/ ./examples/
 
 # Copy frontend build
-COPY --from=frontend-builder /frontend/dist /app/FRRONTEEEND/dist
+COPY --from=frontend-builder --chown=user:user /frontend/dist ./FRRONTEEEND/dist
 
-# Cloud Run ephemeral directories
+# HuggingFace Spaces directories (user-writable)
 RUN mkdir -p \
-    /tmp/data_science_agent \
-    /tmp/outputs/models \
-    /tmp/outputs/plots \
-    /tmp/outputs/reports \
-    /tmp/outputs/data \
-    /tmp/cache_db
-
-# Environment variables
+    /home/user/app/data \
+    /home/user/app/outputs/models \
+    /home/user/app/outputs/plots \
+    /home/user/app/outputs/reports \
+    /home/user/app/outputs/data \
+    /home/user/app/cache_db
+
+# Environment variables for HuggingFace Spaces
 ENV PYTHONUNBUFFERED=1
-ENV PORT=8080
-ENV OUTPUT_DIR=/tmp/outputs
-ENV CACHE_DB_PATH=/tmp/cache_db/cache.db
+ENV PORT=7860
+ENV OUTPUT_DIR=/home/user/app/outputs
+ENV CACHE_DB_PATH=/home/user/app/cache_db/cache.db
 ENV ARTIFACT_BACKEND=local
 
-EXPOSE 8080
+# HuggingFace Spaces uses port 7860 by default
+EXPOSE 7860
 
-# Start FastAPI
-CMD ["uvicorn", "src.api.app:app", "--host", "0.0.0.0", "--port", "8080"]
+# Start FastAPI on port 7860
+CMD ["uvicorn", "src.api.app:app", "--host", "0.0.0.0", "--port", "7860"]

Dockerfile.render

@@ -0,0 +1,84 @@
+# ===============================
+# Stage 1: Build Frontend
+# ===============================
+# Cache bust: 2025-12-28 fix
+FROM node:20-alpine AS frontend-builder
+
+WORKDIR /frontend
+
+COPY FRRONTEEEND/package*.json ./
+RUN npm install
+
+COPY FRRONTEEEND/ ./
+RUN npm run build
+
+
+# ===============================
+# Stage 2: Build Python environment
+# ===============================
+FROM python:3.12-slim AS builder
+
+# Install build dependencies (needed for ML wheels)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    g++ \
+    make \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create virtual environment
+RUN python -m venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+# Upgrade pip tooling
+RUN pip install --upgrade pip setuptools wheel
+
+# Install Python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+
+# ===============================
+# Stage 3: Runtime environment
+# ===============================
+FROM python:3.12-slim
+
+# Install runtime shared libraries
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libgomp1 \
+    libstdc++6 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy virtual environment
+COPY --from=builder /opt/venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+# App working directory
+WORKDIR /app
+
+# Copy backend code
+COPY src/ /app/src/
+COPY examples/ /app/examples/
+
+# Copy frontend build
+COPY --from=frontend-builder /frontend/dist /app/FRRONTEEEND/dist
+
+# Cloud Run ephemeral directories
+RUN mkdir -p \
+    /tmp/data_science_agent \
+    /tmp/outputs/models \
+    /tmp/outputs/plots \
+    /tmp/outputs/reports \
+    /tmp/outputs/data \
+    /tmp/cache_db
+
+# Environment variables
+ENV PYTHONUNBUFFERED=1
+ENV PORT=8080
+ENV OUTPUT_DIR=/tmp/outputs
+ENV CACHE_DB_PATH=/tmp/cache_db/cache.db
+ENV ARTIFACT_BACKEND=local
+
+EXPOSE 8080
+
+# Start FastAPI
+CMD ["uvicorn", "src.api.app:app", "--host", "0.0.0.0", "--port", "8080"]

Dockerfile.spaces

@@ -0,0 +1,93 @@
+# ===============================
+# HuggingFace Spaces Dockerfile
+# ===============================
+# Optimized for 16GB RAM, Port 7860
+
+# ===============================
+# Stage 1: Build Frontend
+# ===============================
+FROM node:20-alpine AS frontend-builder
+
+WORKDIR /frontend
+
+COPY FRRONTEEEND/package*.json ./
+RUN npm install
+
+COPY FRRONTEEEND/ ./
+RUN npm run build
+
+
+# ===============================
+# Stage 2: Build Python environment
+# ===============================
+FROM python:3.12-slim AS builder
+
+# Install build dependencies (needed for ML wheels)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    g++ \
+    make \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create virtual environment
+RUN python -m venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+# Upgrade pip tooling
+RUN pip install --upgrade pip setuptools wheel
+
+# Install Python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+
+# ===============================
+# Stage 3: Runtime environment
+# ===============================
+FROM python:3.12-slim
+
+# Install runtime shared libraries
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libgomp1 \
+    libstdc++6 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy virtual environment
+COPY --from=builder /opt/venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+# Create non-root user for HuggingFace Spaces
+RUN useradd -m -u 1000 user
+USER user
+
+# App working directory
+WORKDIR /home/user/app
+
+# Copy backend code (as user)
+COPY --chown=user:user src/ ./src/
+COPY --chown=user:user examples/ ./examples/
+
+# Copy frontend build
+COPY --from=frontend-builder --chown=user:user /frontend/dist ./FRRONTEEEND/dist
+
+# HuggingFace Spaces directories (user-writable)
+RUN mkdir -p \
+    /home/user/app/data \
+    /home/user/app/outputs/models \
+    /home/user/app/outputs/plots \
+    /home/user/app/outputs/reports \
+    /home/user/app/outputs/data \
+    /home/user/app/cache_db
+
+# Environment variables for HuggingFace Spaces
+ENV PYTHONUNBUFFERED=1
+ENV PORT=7860
+ENV OUTPUT_DIR=/home/user/app/outputs
+ENV CACHE_DB_PATH=/home/user/app/cache_db/cache.db
+ENV ARTIFACT_BACKEND=local
+
+# HuggingFace Spaces uses port 7860 by default
+EXPOSE 7860
+
+# Start FastAPI on port 7860
+CMD ["uvicorn", "src.api.app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,993 +1,122 @@
-# AI-Powered Data Science Agent
-
-## Overview
-
-The AI-Powered Data Science Agent is an intelligent autonomous system designed to perform complete end-to-end data science workflows through natural language interaction. This agent leverages Google Gemini 2.5 Flash for advanced reasoning and function calling capabilities, combined with a comprehensive suite of over 82 specialized machine learning tools.
-
-The system enables users to upload datasets in CSV or Parquet format and describe their analytical objectives in plain English. The agent autonomously handles the entire pipeline including data profiling, quality assessment, cleaning, feature engineering, model training, hyperparameter optimization, cross-validation, and comprehensive reporting generation.
-
-Key capabilities include intelligent intent classification, session memory for contextual awareness, error recovery mechanisms, and a modern React-based web interface for seamless user interaction.
-
-[![React](https://img.shields.io/badge/React-19-61DAFB?logo=react)](https://reactjs.org/)
-[![FastAPI](https://img.shields.io/badge/FastAPI-0.109-009688?logo=fastapi)](https://fastapi.tiangolo.com/)
-[![Gemini](https://img.shields.io/badge/Gemini-2.5_Flash-4285F4?logo=google)](https://ai.google.dev/)
-[![Python](https://img.shields.io/badge/Python-3.10+-3776AB?logo=python)](https://python.org/)
-
+---
+title: DevSprint Data Science Agent
+emoji: 🤖
+colorFrom: blue
+colorTo: purple
+sdk: docker
+pinned: false
+license: mit
+app_port: 7860
 ---
 
-## Key Features
-
-### Autonomous AI Agent System
-
-The core orchestration engine integrates Google Gemini 2.5 Flash with over 82 specialized machine learning tools organized across multiple categories:
-
-- **Data Profiling Tools**: Generate comprehensive statistical summaries, distribution analysis, correlation matrices, data quality reports, and automated anomaly detection
-- **Data Cleaning Tools**: Handle missing values with intelligent imputation strategies (mean, median, mode, forward/backward fill, KNN), outlier detection and treatment using IQR and Z-score methods, duplicate removal, and data type conversions
-- **Feature Engineering Tools**: Create time-based features (hour, day, month, year, cyclical encodings), polynomial features, interaction terms, statistical aggregations, lag features, rolling window statistics, and domain-specific transformations
-- **Model Training Tools**: Support for multiple algorithm families including linear models (Ridge, Lasso, ElasticNet), tree-based models (Random Forest, Gradient Boosting), and advanced gradient boosting frameworks (XGBoost, LightGBM, CatBoost)
-- **Visualization Tools**: Generate interactive Plotly visualizations, Matplotlib static plots, correlation heatmaps, distribution plots, scatter matrices, feature importance charts, and residual analysis plots
-
-The intelligent orchestration system uses function calling capabilities to dynamically select and execute appropriate tools based on user intent. The agent maintains session memory for contextual awareness across conversation turns, enabling multi-turn dialogues where previous actions and results inform subsequent decisions.
-
-Smart intent detection automatically classifies incoming requests into categories such as full ML pipeline execution, exploratory data analysis, data cleaning only, visualization generation, or multi-intent tasks requiring combined workflows.
-
-Error recovery mechanisms include automatic retry logic with corrected parameters, file existence validation before tool execution, recovery guidance displaying the last successful file state, and loop detection to prevent infinite retry cycles.
-
-### Modern Web Interface
-
-The frontend is built with React 19 and TypeScript 5.8, featuring a modern glassmorphism design aesthetic with smooth animations powered by Framer Motion. Key interface components include:
-
-- **Landing Page**: Geometric hero section with animated background paths, key capabilities showcase, problem-solution presentation, process flow visualization, and technology stack display
-- **Chat Interface**: Real-time message streaming, file upload support for CSV and Parquet formats, markdown rendering for formatted responses with code syntax highlighting, loading states with animated indicators, and error handling with user-friendly messages
-- **Report Viewer**: In-application modal viewer for HTML reports generated by YData Profiling and custom dashboard tools. Full-screen modal with professional styling, iframe embedding for report content, and download capabilities
-- **Session Management**: Maintains conversation history across browser sessions, allows users to review previous analyses, and provides context for follow-up questions
-
-### Complete Machine Learning Pipeline
-
-The agent executes a comprehensive end-to-end pipeline:
-
-1. **Data Profiling and Assessment**: Automatically generates statistical summaries including descriptive statistics (mean, median, standard deviation, quartiles), distribution analysis with histogram generation, correlation analysis with heatmap visualization, missing value analysis with percentage calculations, data type detection and validation, outlier detection using multiple methods (IQR, Z-score, isolation forest), and cardinality analysis for categorical variables
-
-2. **Data Cleaning and Preprocessing**: Handles missing values with context-aware imputation strategies, removes or treats outliers based on statistical thresholds, performs data type conversions and casting, removes duplicate records, handles inconsistent formatting in categorical variables, and validates data integrity constraints
-
-3. Quick Start Guide
-
-### Prerequisites
-
-Before beginning the installation, ensure your system meets the following requirements:
-
-- **Python**: Version 3.10 or higher with pip package manager
-- **Node.js**: V Steps
-
-**Step 1: Clone the Repository**
-
-Clone the repository from GitHub and navigate to the project directory:
-
-```bash
-git clone https://github.com/Pulastya-B/DevSprint-Data-Science-Agent.git
-cd DevSprint-Data-Science-Agent
-```
-
-**Step 2: Configure Environment Variables**
-
-Create a `.env` file in the root directory with the following configuration:
-
-```bash
-# LLM Provider Configuration
-LLM_PROVIDER=gemini
-
-# Google Gemini API Key (required)
-GOOGLE_API_KEY=your_api_key_here
-
-# Model Configuration
-GEMINI_MODEL=gemini-2.5-flash
-
-# Cache Configuration
-CACHE_DB_PATH=./cache_db/cache.db
-CACHE_TTL_SECONDS=86400
-
-# Output and Data Directories
-OUTPUT_DIR=./outputs
-DATA_DIR=./data
-```
-
-Replace `your_api_key_here` with your actual Google Gemini API key obtained from https://ai.google.dev/
-
-**Step 3: Install Python Dependencies**
-
-Install all required Python packages using pip:
-
-```bash
-pip install -r requirements.txt
-```
-
-ThiUsage Guide
-
-### Web Interface Workflow
-
-**Step 1: Access the Application**
-
-Open your web browser and navigate to http://localhost:8080. You will see the landing page with an overview of the agent's capabilities.
-
-**Step 2: Launch the Chat Interface**
-
-Click the "Launch Agent" button to access the interactive chat interface.
-
-**Step 3: Upload Your Dataset**
-
-Click the file upload button (paperclip icon) and select your dataset file. Supported formats:
-- CSV files (.csv) with any delimiter (comma, tab, semicolon, etc.)
-- Parquet files (.parquet) for high-performance columnar storage
-
-The agent will automatically detect the file format and load the data using appropriate parsers.
-
-**Step 4: Describe Your Task**
-
-Type your request in natural language in the chat input box. The agent understands various types of requests and will automatically determine the appropriate workflow.
-
-**Step 5: Review Results**
-
-The agent will execute the requested workflow and display results in the chat interface. For analyses that generate HTML reports (such as YData Profiling), a "View Report" button will appear. Click this button to open the report in a full-screen modal viewer.
-
-### Example Queries and Use Cases
-
-**Data Profiling and Exploration:**
-```
-"Generate a comprehensive profile report on this dataset"
-"Show me the statistical summary and distribution of all variables"
-"Analyze data quality issues including missing values and outliers"
-"Create a correlation matrix and identify highly correlated features"
-```
-
-**Data Cleaning:**
-```
-"Clean the missing values using median imputation for numeric columns"
-"Handle outliers in the dataset using IQR method"
-"Remove duplicate records and fix data type inconsistencies"
-"Drop columns with more than 50% missing values"
-```
-
-**Predictive Modeling:**
-```
-"Train a model to predict the target column 'price' using all features"
-"Build a classification model for the 'churn' column"
-"Compare multiple regression algorithms and select the best one"
-"Train an XGBoost model with default hyperparameters"
-```
-
-**Feature Engineering:**
-```
-"Extract time-based features from the datetime column"
-"Create interaction terms between numeric features"
-"Apply target encoding for high-cardinality categorical variables"
-"Generate polynomial features of degree 2"
-```
-
-**Model Optimization:**
-```
-"Perform hyperparameter tuning on the trained model using Optuna"
-"Run 5-fold cross-validation to evaluate model performance"
-"Optimize the XGBoost model for better accuracy"
-```
+# DevSprint Data Science Agent 🤖
 
-**Visualization:**
-```
-"Generate a correlation heatmap for numeric features"
-"Create distribution plots for all numeric columns"
-"Show feature importance for the trained model"
-"Generate interactive Plotly visualizations"
-```
+An intelligent AI agent for automated data science workflows, powered by Google Gemini 2.5 Flash with 82+ specialized tools for data analysis, visualization, and machine learning.
 
-**End-to-End Pipeline:**
-```
-"Profile the data, clean it, engineer features, and train the best model"
-"Perform complete analysis and predict the target column 'sales'"
-"Do everything needed to build a production-ready model
-.\start.ps1
-```
+## Features
 
-**For Linux/macOS:**
-```bash
-chmod +x start.sh
-./start.sh
-```
+- 🔍 **Automated EDA**: YData profiling, statistical analysis, data quality reports
+- 📊 **Smart Visualizations**: Plotly dashboards, matplotlib plots, interactive charts
+- 🧹 **Data Cleaning**: Missing value handling, outlier detection, type conversion
+- 🛠️ **Feature Engineering**: Automated feature creation, encoding, scaling
+- 🤖 **ML Training**: AutoML with XGBoost, LightGBM, CatBoost, Neural Networks
+- 💬 **Natural Language Interface**: Chat-based interaction for complex workflows
+- 📈 **Business Intelligence**: KPI tracking, trend analysis, forecasting
 
-The startup script will:
-1. Technology Stack
+## Tech Stack
 
-### Frontend Technologies
+- **Backend**: FastAPI + Python 3.12
+- **LLM**: Google Gemini 2.5 Flash (text-based tool calling)
+- **Data Processing**: Polars (high-performance dataframes)
+- **Frontend**: React 19 + TypeScript + Vite
+- **ML Libraries**: Scikit-learn, XGBoost, LightGBM, CatBoost, PyTorch
 
-- **React 19.2.3**: Latest version of React with improved concurrent rendering, automatic batching, and enhanced hooks for building performant user interfaces
-- **TypeScript 5.8.2**: Provides static type checking, enhanced IDE support, and improved code maintainability with advanced type inference
-- **Vite 6.2.0**: Next-generation frontend build tool offering instant server start, lightning-fast hot module replacement (HMR), and optimized production builds
-- **Tailwind CSS 3.4.1**: Utility-first CSS framework enabling rapid UI development with pre-built classes and responsive design utilities
-- **Framer Motion 12.23.26**: Production-ready animation library for React with declarative animations, gestures, and smooth transitions
-- **React Markdown 9.0.1**: Markdown rendering component supporting GitHub-flavored markdown, code syntax highlighting, and custom renderers
-- **Lucide React**: Icon library providing consistent, customizable SVG icons for the user interface
+## Usage
 
-### Backend Technologies
+1. Upload your CSV/Excel dataset
+2. Ask questions in natural language (e.g., "Generate a detailed profiling report")
+3. The agent automatically selects and executes the right tools
+4. View generated reports, visualizations, and insights
 
-- **FastAPI 0.109+**: Modern, high-performance Python web framework with automatic OpenAPI documentation, async/await support, and built-in request validation
-- **Google Gemini 2.5 Flash**: Large language model with advanced reasoning capabilities, function calling support, and high token limits for agent orchestration
-- **Polars 0.20+**: High-performance DataFrame library written in Rust, offering 10-100x speed improvements over pandas for large datasets
-- **Scikit-learn 1.3+**: Comprehensive machine learning library providing classical algorithms for classification, regression, clustering, and preprocessing
-- **XGBoost 2.0+**: Optimized gradient boosting framework with parallel tree construction, regularization, and efficient handling of sparse data
-- **LightGBM 4.1+**: Gradient boosting framework by Microsoft with leaf-wise tree growth, categorical feature support, and memory efficiency
-- **CatBoost 1.2+**: Gradient boosting library by Yandex with native categorical feature handling, GPU support, and symmetric tree structure
-- **Optuna 3.5+**: Hyperparameter optimization framework with Bayesian optimization, pruning strategies, and distributed optimization support
-- **YData Profiling 4.6+**: Automated exploratory data analysis tool generating comprehensive HTML reports with statistical summaries and data quality insights
-- **Plotly 5.18+**: Interactive visualization library creating web-based charts with zooming, panning, and hover tooltips
-- **Matplotlib 3.8+**: Fundamental plotting library for Python offering publication-quality static visualizations
-- **Pydantic 2.5+**: Data validation library using Python type annotations for request/response models
+## Memory Optimization
 
-###Docker Deployment
+For large datasets (>50k rows or >10MB), the agent automatically:
+- Samples to 50,000 rows for profiling
+- Enables minimal mode to reduce memory usage
+- Disables expensive correlation/interaction calculations
 
-The application includes a multi-stage Dockerfile for optimized containerized deployment.
+This ensures smooth operation even with large datasets on HuggingFace's 16GB RAM.
 
-### Building the Docker Image
+## Environment Variables
 
-Build the Docker image with the following command:
+Set `GEMINI_API_KEY` in HuggingFace Spaces settings (Settings → Repository secrets):
 
-```bash
-docker build -t ds-agent:latest .
 ```
-
-The multi-stage build process:
-1. **Stage 1 (Builder)**: Installs Node.js dependencies and builds the React frontend
-2. **Stage 2 (Runtime)**: Sets up Python environment, installs backend dependencies, and copies built frontend
-3. Result: Optimized image size by excluding development dependencies and build tools
-
-### Running the Container
-
-Run the containerized application:
-
-```bash
-docker run -d \
-  -p 8080:8080 \
-  --env-file .env \
-  --name ds-agent-container \
-  ds-agent:latest
+GEMINI_API_KEY=your_google_gemini_api_key_here
 ```
 
-Parameters explained:
-- `-d`: Run container in detached mode (background)
-- `-p 8080:8080`: Map container port 8080 to host port 8080
-- `--env-file .env`: Load environment variables from .env file
-- `--name ds-agent-container`: Assign a name to the container for easy management
-
-### Docker Compose (Recommended)
-
-For easier management, create a `docker-compose.yml` file:
+Get your API key from: https://aistudio.google.com/app/apikey
 
-```yaml
-version: '3.8'
-
-services:
-  ds-agent:
-    build: .
-    container_name: ds-agent
-    ports:
-      - "8080:8080"
-    env_file:
-      - .env
-    volumes:
-   Environment Configuration
-
-The application uses environment variables for configuration management. Create a `.env` file in the project root directory with the following variables:
-
-### Required Configuration
+## Local Development
 
 ```bash
-# LLM Provider Selection
-LLM_PROVIDER=gemini
-# Options: gemini (currently supported)
-
-# Google Gemini API Key (REQUIRED)
-GOOGLE_API_KEY=your_api_key_here
-# Obtain from: https://ai.google.dev/
-# Free tier limits: 10 RPM, 20 RPD
-
-# Gemini Model Selection
-GEMINI_MODEL=gemini-2.5-flash
-# Options:
-#   - gemini-2.5-flash (recommended, balanced performance)
-#   - gemini-1.5-pro (higher capability, lower rate limits)
-#   - gemini-1.5-flash (faster, lower cost)
-```
-
-### Optional Configuration
-Advanced Features
-
-### Intelligent Intent Detection and Classification
-
-The orchestration system employs sophisticated intent detection to automatically classify user requests and route them to appropriate workflow pipelines. The classification system analyzes incoming natural language queries using keyword matching, pattern recognition, and contextual understanding.
-
-**Intent Categories:**
-
-1. **Full ML Pipeline Intent**: Triggered by keywords such as "train", "model", "predict", "machine learning", "regression", "classification". Executes complete workflow including data profiling, cleaning, feature engineering, model training, hyperparameter tuning, and evaluation.
-
-2. **Exploratory Analysis Intent**: Activated by keywords like "explore", "profile", "report", "analysis", "overview", "insights", "understand". Performs comprehensive data profiling with statistical summaries, distribution analysis, correlation matrices, and automated insights generation.
-
-3. **Data Cleaning Intent**: Detected via keywords such as "clean", "missing", "outliers", "duplicates", "impute", "handle". Focuses on data quality improvement operations without proceeding to modeling.
-
-4. **Visualization Intent**: Identified through keywords like "plot", "visualize", "chart", "graph", "heatmap", "distribution". Generates requested visualizations without performing modeling or extensive preprocessing.
-
-5. **Feature Engineering Intent**: Recognized by keywords such as "feature", "engineer", "create features", "transform", "encode". Applies feature transformation and creation operations.
-
-6. **Multi-Intent Workflows**: The system can detect and handle requests combining multiple intents, executing them in a logical sequence.
-
-The intent classification system uses confidence scoring to handle ambiguous requests and can ask clarifying questions when intent is unclear.
-
-### Context-Aware Session Memory
-
-The agent implements persistent session memory that maintains conversation context across multiple turns. This enables natural multi-turn dialogues where subsequent requests can reference previous operations without requiring full context repetition.
-
-**Session Memory Capabilities:**
-
-- **Workflow History**: Stores complete history of executed tools, parameters, and results for the current session
-- **File State Tracking**: Maintains references to uploaded files, intermediate processed datasets, and generated outputs
-- **Model Persistence**: Remembers trained models and their performance metrics for comparison and further tuning
-- **Error Context**: Stores information about encountered errors to avoid repeating failed operations
-- **User Preferences**: Learns from user choices (e.g., preferred visualization types, imputation strategies)
-
-**Example Multi-Turn Conversation:**
+# Clone repository
+git clone https://huggingface.co/spaces/YOUR_USERNAME/devs-print-data-science-agent
+cd devs-print-data-science-agent
 
-```Complete Workflow Example
-
-This section demonstrates a complete end-to-end workflow for a real-world dataset, showing the agent's autonomous decision-making and execution capabilities.
+# Install dependencies
+pip install -r requirements.txt
+npm install --prefix FRRONTEEEND
 
-### Dataset: Earthquake Magnitude Prediction
+# Build frontend
+cd FRRONTEEEND && npm run build && cd ..
 
-**Input Dataset:** `earthquake_data.csv`
-- Rows: 175,947 earthquake records
-- Columns: 22 features including latitude, longitude, depth, time, location, and magnitude
-- Target Variable: Earthquake magnitude (continuous regression task)
-- Data Quality: 11.67% missing values, presence of outliers, mixed data types
+# Set API key
+export GEMINI_API_KEY=your_key_here
 
-**User Prompt:**
-```
-"Train a model to predict earthquake magnitude with the highest possible accuracy"
+# Run server
+uvicorn src.api.app:app --host 0.0.0.0 --port 7860
 ```
 
-### Automated Workflow Execution
-
-**Phase 1: Data Profiling and Assessment** (Step 1)
-- Tool: `generate_ydata_profile`
-- Action: Comprehensive statistical analysis of all 22 features
-- Findings:
-  - Total records: 175,947
-  - Missing values detected in 8 columns
-  - Outliers present in depth, latitude, longitude
-  - High cardinality in location column (15,000+ unique values)
-  - Strong correlation between depth and magnitude (r=0.62)
-- Output: YData Profiling HTML report saved to `outputs/earthquake_profile.html`
-- Time: 18.3 seconds
-API Reference
-
-The FastAPI backend exposes several endpoints for programmatic interaction.
+## Architecture
 
-### Endpoints
-
-**POST /chat**
-- Description: Send a message to the agent with optional file upload
-- Content-Type: multipart/form-data
-- Parameters:
-  - message (string, required): User's natural language request
-  - file (file, optional): Dataset file (CSV or Parquet)
-- Response: JSON with agent's response message and workflow history
-- Example:
-```bash
-curl -X POST http://localhost:8080/chat \
-  -F "message=Generate a data profile report" \
-  -F "file=@dataset.csv"
 ```
-
-**POST /run**
-- Description: Execute a complete analysis workflow
-- Content-Type: application/json
-- Parameters:
-  - query (string, required): Analysis request
-  - use_cache (boolean, optional): Enable caching (default: true)
-- Response: JSON with analysis results and generated artifacts
-- Example:
-```json
-{
-  "query": "Train a regression model to predict sales",
-  "use_cache": true
-}
+┌─────────────────┐
+│  React Frontend │  ← User uploads data + asks questions
+└────────┬────────┘
+         │
+┌────────▼────────┐
+│  FastAPI Server │  ← Serves frontend + API endpoints
+└────────┬────────┘
+         │
+┌────────▼────────┐
+│  Orchestrator   │  ← LLM-driven tool selection & execution
+└────────┬────────┘
+         │
+┌────────▼────────┐
+│   82+ Tools     │  ← Specialized data science functions
+└─────────────────┘
 ```
 
-**GET /outputs/{file_path}**
-- Description: Retrieve generated reports and artifacts
-- Parameters:
-  - file_path (string, required): Path to output file
-- Response: File content (HTML, PNG, CSV, etc.)
-- Example:
-```bash
-curl http://localhost:8080/outputs/ydata_profile.html
-```
+## Key Components
 
-**GET /api/health**
-- Description: Health check endpoint
-- Response: JSON with status information
-- Example response:
-```json
-{
-  "status": "healthy",
-  "version": "1.0.0",
-  "timestamp": "2025-12-27T10:30:00Z"
-}
-```
+- **Orchestrator** ([src/orchestrator.py](src/orchestrator.py)): ReAct-based tool calling with Gemini
+- **Tools Registry** ([src/tools/](src/tools/)): 82+ specialized data science tools
+- **Session Memory** ([src/session_memory.py](src/session_memory.py)): Conversation history + file tracking
+- **Artifact Store** ([src/storage/artifact_store.py](src/storage/artifact_store.py)): File management + metadata
 
-### Interactive API Documentation
+## Deployment
 
-FastAPI automatically generates interactive API documentation:
-- Swagger UI: http://localhost:8080/docs
-- ReDoc: http://localhost:8080/redoc
+This Space uses a **Docker** deployment for maximum compatibility:
+- Base image: `python:3.12-slim`
+- Multi-stage build (Node.js for frontend, Python for backend)
+- Auto-exposes port 7860 for HuggingFace
+- All dependencies bundled in container
 
 ## Contributing
 
-Contributions to improve the AI-Powered Data Science Agent are welcome. Please follow these guidelines:
-
-### Development Setup
-
-1. Fork the repository and clone your fork
-2. Create a new branch for your feature: `git checkout -b feature/your-feature-name`
-3. Install development dependencies: `pip install -r requirements-dev.txt`
-4. Make your changes with appropriate tests
-5. Ensure all tests pass: `pytest tests/`
-6. Format code with black: `black src/`
-7. Lint code with flake8: `flake8 src/`
-8. Commit with descriptive messages
-9. Push to your fork and submit a pull request
-
-### Code Style
-
-- Follow PEP 8 guidelines for Python code
-- Use type hints for function parameters and return values
-- Write docstrings for all functions and classes
-- Keep functions focused and under 50 lines when possible
-- Use meaningful variable names
-
-### Testing
-
-- Write unit tests for new features
-- Ensure existing tests pass before submitting PR
-- Aim for >80% code coverage
+Built for DevSprint Hackathon 2025. Contributions welcome post-hackathon!
 
 ## License
 
-This project is licensed under the MIT License. See the LICENSE file for complete terms.
-
-Copyright (c) 2025 Pulastya B
-
-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. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-## Acknowledgments
-
-This project builds upon several excellent open-source technologies and frameworks:
-
-- **Google Gemini 2.5 Flash**: Advanced language model with function calling capabilities enabling intelligent agent orchestration
-- **FastAPI**: Modern, high-performance web framework for building APIs with Python, providing automatic documentation and validation
-- **React**: JavaScript library for building user interfaces, enabling component-based architecture and efficient rendering
-- **Polars**: High-performance DataFrame library written in Rust, offering significant speed improvements over traditional data processing libraries
-- **Scikit-learn**: Machine learning library providing simple and efficient tools for data analysis and modeling
-- **XGBoost, LightGBM, CatBoost**: Gradient boosting frameworks offering state-of-the-art performance for structured data
-- **Optuna**: Hyperparameter optimization framework with efficient search algorithms
-- **YData Profiling**: Automated exploratory data analysis tool generating comprehensive reports
-- **Plotly**: Interactive visualization library for creating publication-quality graphs
-- **TypeScript**: Typed superset of JavaScript enhancing code quality and developer experience
-- **Tailwind CSS**: Utility-first CSS framework for rapid UI development
-- **Vite**: Next-generation frontend build tool with instant server start
-
-Special thanks to the open-source community for creating and maintaining these exceptional tools.
-
-## Contact and Support
-
-**Developer:** Pulastya B
-
-**GitHub Profile:** [@Pulastya-B](https://github.com/Pulastya-B)
-
-**Project Repository:** [DevSprint-Data-Science-Agent](https://github.com/Pulastya-B/DevSprint-Data-Science-Agent)
-
-**Issues and Bug Reports:** Please use the GitHub Issues page to report bugs or request features
-
-**Documentation:** Additional documentation and tutorials available in the repository wiki
-
-**Project Status:** Active development - Built for DevSprint Hackathon
-
-For questions, suggestions, or collaboration opportunities, please open an issue on GitHub or contact through the repository.
-
----
-
-**Last Updated:** December 27, 2025
-
-**Version:** 1.0.0
-Step 6 - Temporal Feature Extraction:
-- Tool: `extract_time_features`
-- Input column: 'timestamp'
-- Features created:
-  - year, month, day_of_week, hour
-  - Cyclical encodings: hour_sin, hour_cos, month_sin, month_cos
-- Justification: Earthquakes may have temporal patterns
-- New columns: 8 time-based features
-
-Step 7 - Categorical Encoding:
-- Tool: `encode_categorical_features`
-- Method: Target encoding for 'location' (high cardinality), one-hot encoding for 'type'
-- Result: All categorical variables converted to numeric
-- New columns: 3 (reduced from high-cardinality location)
-
-Step 8 - Statistical Features:
-- Tool: `create_statistical_features`
-- Features created:
-  - Distance from nearest plate boundary (calculated from lat/lon)
-  - Depth-to-magnitude ratio
-  - Regional earthquake frequency (rolling count)
-- New columns: 3 domain-specific features
-
-Final feature count: 28 engineered features
-
-**Phase 5: Model Training and Selection** (Step 9)
-- Tool: `train_baseline_models`
-- Algorithms trained in parallel:
-
-1. Ridge Regression: R² = 0.534, RMSE = 0.312
-2. Lasso Regression: R² = 0.541, RMSE = 0.309
-3. ElasticNet: R² = 0.538, RMSE = 0.311
-4. Random Forest: R² = 0.698, RMSE = 0.251
-5. XGBoost: R² = 0.716, RMSE = 0.243 (BEST)
-6. LightGBM: R² = 0.709, RMSE = 0.247
-7. CatBoost: R² = 0.712, RMSE = 0.245
-
-- Best model selected: XGBoost
-- Validation split: 80/20 stratified split
-- Time: 124.7 seconds
-
-**Phase 6: Hyperparameter Optimization** (Step 10)
-- Tool: `optimize_hyperparameters_optuna`
-- Framework: Optuna with Tree-structured Parzen Estimator (TPE)
-- Search space:
-  - max_depth: [3, 10]
-  - learning_rate: [0.001, 0.3] (log scale)
-  - n_estimators: [100, 1000]
-  - min_child_weight: [1, 10]
-  - subsample: [0.6, 1.0]
-  - colsample_bytree: [0.6, 1.0]
-- Trials: 50 iterations
-- Best parameters found:
-  - max_depth: 7
-  - learning_rate: 0.0847
-  - n_estimators: 673
-  - min_child_weight: 3
-  - subsample: 0.8234
-  - colsample_bytree: 0.9123
-- Optimized performance: R² = 0.743, RMSE = 0.231
-- Improvement: +3.8% R² over baseline
-- Time: 312.4 seconds
-
-**Phase 7: Model Validation** (Step 11)
-- Tool: `cross_validate_model`
-- Method: 5-fold stratified cross-validation
-- Results:
-  - Fold 1: R² = 0.741, RMSE = 0.232
-  - Fold 2: R² = 0.745, RMSE = 0.230
-  - Fold 3: R² = 0.738, RMSE = 0.234
-  - Fold 4: R² = 0.747, RMSE = 0.229
-  - Fold 5: R² = 0.742, RMSE = 0.232
-- Mean performance: R² = 0.743 ± 0.003, RMSE = 0.231 ± 0.002
-- Interpretation: Low variance across folds indicates robust, generalizable model
-- Time: 267.8 seconds
-
-**Phase 8: Visualization and Reporting** (Steps 12-13)
-
-Step 12 - Feature Importance Analysis:
-- Tool: `plot_feature_importance`
-- Top 10 features by importance:
-  1. depth (0.284)
-  2. distance_to_plate_boundary (0.167)
-  3. latitude (0.142)
-  4. longitude (0.138)
-  5. regional_frequency (0.095)
-  6. depth_magnitude_ratio (0.067)
-  7. hour_sin (0.034)
-  8. month (0.028)
-  9. location_encoded (0.024)
-  10. year (0.021)
-- Output: Interactive Plotly bar chart saved to `outputs/feature_importance.html`
-
-Step 13 - Comprehensive Dashboard:
-- Tool: `create_plotly_dashboard`
-- Visualizations included:
-  - Correlation heatmap (28x28 features)
-  - Actual vs Predicted scatter plot
-  - Residual distribution plot
-  - Feature importance ranking
-  - Temporal patterns in predictions
-- Output: Multi-panel interactive dashboard saved to `outputs/model_dashboard.html`
-
-### Final Results Summary
-
-**Model Performance:**
-- Algorithm: XGBoost with optimized hyperparameters
-- Training R²: 0.743
-- Cross-validated R²: 0.743 ± 0.003
-- RMSE: 0.231 (on magnitude scale 0-10)
-- MAE: 0.176
-- Explanation: Model explains 74.3% of variance in earthquake magnitudes
-
-**Artifacts Generated:**
-- Trained model file: `outputs/xgboost_model_optimized.pkl`
-- YData profiling report: `outputs/earthquake_profile.html`
-- Feature importance plot: `outputs/feature_importance.html`
-- Interactive dashboard: `outputs/model_dashboard.html`
-- Cleaned dataset: `data/earthquake_data_cleaned.parquet`
-- Feature engineered dataset: `data/earthquake_data_featured.parquet`
-
-**Total Execution Time:** 12 minutes 43 seconds
-
-**Key Insights:**
-1. Depth is the strongest predictor of earthquake magnitude (28.4% importance)
-2. Spatial features (distance to plate boundaries, lat/lon) are highly informative
-3. Temporal patterns show cyclical variations in earthquake characteristics
-4. Model performance is consistent across cross-validation folds (low variance)
-5. The optimized XGBoost model provides reliable magnitude predictions suitable for deployment
-
-### Robust Error Recovery System
-
-The agent implements a comprehensive error recovery system designed to handle failures gracefully and guide users toward successful task completion.
-
-**Error Recovery Mechanisms:**
-
-1. **Automatic Retry with Correction**: When a tool execution fails due to incorrect parameters, the agent analyzes the error message, adjusts parameters based on the error type, and automatically retries the operation with corrected inputs.
-
-2. **File Existence Validation**: Before executing tools that require specific file inputs, the system validates file existence and accessibility, providing clear guidance when files are missing.
-
-3. **Column Name Validation**: Validates that requested column names exist in the dataset before performing operations, suggesting similar column names when exact matches aren't found.
-
-4. **Dependency Tracking**: Ensures tools are executed in proper sequence, checking that prerequisite operations (e.g., data cleaning before training) have been completed.
-
-5. **Loop Detection**: Monitors tool execution patterns to detect and prevent infinite retry loops. If the same operation fails multiple times with the same error, the agent stops retrying and requests user intervention.
-
-6. **Recovery Guidance**: When errors cannot be automatically resolved, the system provides detailed guidance including:
-   - Clear explanation of what went wrong
-   - The last successful file state that can be used to continue
-   - Suggested alternative approaches
-   - Specific parameter corrections needed
-
-7. **Graceful Degradation**: If a requested operation cannot be completed, the agent attempts to provide partial results or alternative analysis that may still be valuable.
-
-**Example Error Recovery Flow:**
-
-```
-Request: "Train a model to predict 'Price' column"
-
-Error Detected: Column 'Price' not found in dataset
-Recovery Action: Search for similar columns → Find 'price', 'PRICE', 'SalePrice'
-Agent Response: "Column 'Price' not found. Did you mean 'SalePrice'? I found these similar columns: ['SalePrice', 'price_usd']. Please specify which column to use."
-
-User: "Yes, use SalePrice"
-Agent: [Continues with corrected column name]
-```
-
-### Interactive Report Viewing
-
-The web interface includes an integrated report viewer that displays comprehensive HTML reports generated during analysis without requiring users to download files or switch to external tools.
-
-**Report Viewer Features:**
-
-- **In-Application Display**: Reports open in a full-screen modal overlay within the chat interface
-- **Multiple Report Types**: Supports YData Profiling reports and custom HTML dashboards
-- **Professional Styling**: Modal features glassmorphism design, smooth animations, and responsive layout
-- **Interactive Navigation**: Users can zoom, scroll, and interact with report elements directly in the viewer
-- **Download Option**: Reports can be downloaded as standalone HTML files for sharing or archival
-- **Automatic Detection**: System automatically detects when tools generate HTML reports and creates "View Report" buttons in the chat interface
-
-**Supported Report Types:**
-
-1. **YData Profiling Reports**: Comprehensive automated EDA with variable statistics, distributions, correlations, missing value analysis, and alerts for data quality issues
-
-2. **Custom Dashboards**: User-created Plotly dashboards with multiple interactive visualizations
-
-The report extraction system uses multiple strategies to locate report files, including checking tool return values, parsing workflow history, and using regex pattern matching on agent responses.
-- Use different API keys for development and production
-- Rotate API keys periodically
-- Set restrictive file permissions on `.env` (chmod 600 on Linux/macOS)inux/macOS:**
-```bash
-chmod +x build-and-deploy.sh
-./build-and-deploy.sh
-```
-
-These scripts handle building the image, stopping any existing containers, and starting a new container with proper configuration.FRRONTEEEND
-npm install
-npm run build
-cd ..
-```
-
-**5. Run the application**
-
-**Windows:**
-```powershell
-.\start.ps1
-```
-
-**Linux/Mac:**
-```bash
-chmod +x start.sh
-./start.sh
-```
-
-The application will be available at **http://localhost:8080**
-
----
-
-## 📖 Usage
-
-### Web Interface
-
-1. **Navigate to http://localhost:8080**
-2. **Click "Launch Agent"** from the landing page
-3. **Upload your dataset** (CSV or Parquet format)
-4. **Type your request** in natural language:
-   - "Generate a comprehensive report on this dataset"
-   - "Train a model to predict [target_column]"
-   - "Clean the data and show me visualizations"
-   - "Perform feature engineering and train the best model"
-5. **View results** in the chat and click "View Report" buttons to see detailed HTML reports
-
-### Example Queries
-
-```
-📊 "Profile this dataset and tell me about data quality issues"
-
-🧹 "Clean the missing values and handle outliers"
-
-🎯 "Train a model to predict house prices with target column 'price'"
-
-📈 "Generate a correlation heatmap and feature importance plot"
-
-🔧 "Create time-based features and perform hyperparameter tuning"
-
-📋 "Generate a comprehensive YData profiling report"
-```
-
----
-
-## 🏗️ Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    React Frontend (Port 8080)                │
-│  Landing Page │ Chat Interface │ Report Viewer               │
-└─────────────────────────┬───────────────────────────────────┘
-                          │
-                          ▼
-┌─────────────────────────────────────────────────────────────┐
-│              FastAPI Backend (Python 3.10+)                  │
-│  /chat │ /run │ /outputs │ /api/health                      │
-└─────────────────────────┬───────────────────────────────────┘
-                          │
-                          ▼
-┌─────────────────────────────────────────────────────────────┐
-│           DataScienceCopilot Orchestrator                    │
-│  • Gemini 2.5 Flash Integration                             │
-│  • 82+ Specialized Tools                                     │
-│  • Session Memory & Context                                  │
-│  • Intelligent Intent Detection                              │
-│  • Error Recovery & Loop Prevention                          │
-└─────────────────────────┬───────────────────────────────────���
-                          │
-                          ▼
-┌─────────────────────────────────────────────────────────────┐
-│                     Tool Categories                          │
-│  Profiling │ Cleaning │ Feature Engineering │ ML Training   │
-│  Visualization │ EDA Reports │ Data Wrangling               │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-##  Tech Stack
-
-### Frontend
-- **React 19** - Modern UI library
-- **TypeScript 5.8** - Type-safe development
-- **Vite 6** - Lightning-fast build tool
-- **Tailwind CSS** - Utility-first styling
-- **Framer Motion** - Smooth animations
-- **React Markdown** - Formatted responses
-
-### Backend
-- **FastAPI** - High-performance Python web framework
-- **Google Gemini 2.5 Flash** - LLM for agent orchestration
-- **Polars** - Fast dataframe library (10-100x faster than pandas)
-- **Scikit-learn** - Classical ML algorithms
-- **XGBoost / LightGBM / CatBoost** - Gradient boosting frameworks
-- **Optuna** - Hyperparameter optimization
-- **YData Profiling** - Automated EDA reports
-- **Plotly / Matplotlib** - Interactive visualizations
-
-### DevOps
-- **Docker** - Containerization with multi-stage builds
-- **Python-dotenv** - Environment variable management
-- **SQLite** - Caching layer for performance
-
----
-
-## 🐳 Docker Deployment
-
-**Build and run with Docker:**
-
-```bash
-docker build -t ds-agent .
-docker run -p 8080:8080 --env-file .env ds-agent
-```
-
-**Or use the deployment script:**
-
-```bash
-.\build-and-deploy.ps1  # Windows
-./build-and-deploy.sh   # Linux/Mac
-```
-
----
-
-## 📂 Project Structure
-
-```
-.
-├── FRRONTEEEND/              # React frontend
-│   ├── components/           # UI components
-│   │   ├── ChatInterface.tsx # Main chat interface
-│   │   ├── HeroGeometric.tsx # Landing page hero
-│   │   └── ...
-│   ├── dist/                 # Built frontend
-│   └── package.json
-│
-├── src/                      # Python backend
-│   ├── api/
-│   │   └── app.py           # FastAPI application
-│   ├── orchestrator.py      # Agent orchestrator
-│   ├── session_memory.py    # Session management
-│   ├── tools/               # 82+ ML tools
-│   │   ├── data_profiling.py
-│   │   ├── data_cleaning.py
-│   │   ├── feature_engineering.py
-│   │   ├── model_training.py
-│   │   └── ...
-│   └── utils/               # Helper utilities
-│
-├── Dockerfile               # Multi-stage Docker build
-├── requirements.txt         # Python dependencies
-├── start.ps1 / start.sh    # Quick start scripts
-└── README.md               # This file
-```
-
----
-
-## 🔑 Environment Variables
-
-Create a `.env` file in the root directory:
-
-```bash
-# LLM Provider Configuration
-LLM_PROVIDER=gemini
-
-# API Keys
-GOOGLE_API_KEY=your_gemini_api_key_here
-
-# Model Configuration
-GEMINI_MODEL=gemini-2.5-flash
-
-# Cache Configuration
-CACHE_DB_PATH=./cache_db/cache.db
-CACHE_TTL_SECONDS=86400
-
-# Output Configuration
-OUTPUT_DIR=./outputs
-DATA_DIR=./data
-```
-
----
-
-## 🎯 Features in Detail
-
-### Intelligent Intent Detection
-The agent automatically classifies your request and applies the appropriate workflow:
-- **Full ML Pipeline** - Complete end-to-end workflow with training
-- **Exploratory Analysis** - Data profiling and visualization only
-- **Cleaning Only** - Data quality improvements without modeling
-- **Visualization Only** - Generate plots and dashboards
-- **Multi-Intent** - Combine multiple tasks intelligently
-
-### Session Memory
-The agent remembers context across messages:
-```
-You: "Train a model on this dataset"
-Agent: [Trains XGBoost model with R² = 0.85]
-
-You: "Now try hyperparameter tuning"
-Agent: [Automatically uses previous model and dataset]
-
-You: "Cross-validate it"
-Agent: [Applies CV to tuned model from context]
-```
-
-### Error Recovery
-- Automatic retry with corrected parameters
-- File existence validation before execution
-- Recovery guidance showing last successful file
-- Loop detection to prevent infinite retries
-
-### Report Viewing
-- Click "View Report" buttons to see HTML reports in-app
-- Full-screen modal with professional styling
-- Supports YData Profiling and custom dashboards
-
----
-
-## 📊 Example Workflow
-
-**Upload:** `earthquake_data.csv` (175K rows, 22 columns)
-
-**Prompt:** "Train a model to predict earthquake magnitude"
-
-**Agent Actions:**
-1. ✅ Profiles dataset (175,947 rows, 22 columns)
-2. ✅ Detects data quality issues (11.67% missing, outliers)
-3. ✅ Drops high-missing columns (>40% missing)
-4. ✅ Imputes remaining missing values with median/mode
-5. ✅ Handles outliers with IQR clipping
-6. ✅ Extracts time-based features (year, month, hour, cyclical)
-7. ✅ Encodes categorical variables
-8. ✅ Trains 6 baseline models (XGBoost wins with R² = 0.716)
-9. ✅ Performs hyperparameter tuning (R² = 0.743)
-10. ✅ Runs 5-fold cross-validation (RMSE = 0.167 ± 0.0005)
-11. ✅ Generates YData profiling report
-12. ✅ Creates interactive Plotly dashboard
-
-**Result:** Trained and tuned XGBoost model ready for deployment!
-
----
-
-## 🤝 Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.
-
----
-
-## 📄 License
-
-This project is licensed under the MIT License.
-
----
-
-## 🙏 Acknowledgments
-
-- **Google Gemini** for powerful LLM capabilities
-- **FastAPI** for excellent async Python framework
-- **React** community for amazing UI libraries
-- **Polars** for blazing-fast data processing
-- **YData Profiling** for comprehensive EDA reports
-
----
-
-## 📧 Contact
-
-**Pulastya B**
-- GitHub: [@Pulastya-B](https://github.com/Pulastya-B)
-- Project: [DevSprint-Data-Science-Agent](https://github.com/Pulastya-B/DevSprint-Data-Science-Agent)
-
----
-
-<div align="center">
-
-**Built with ❤️ for DevSprint Hackathon**
-
-⭐ Star this repo if you find it helpful!
-
-</div>
+MIT License - see LICENSE file for details

README_SPACES.md

@@ -0,0 +1,122 @@
+---
+title: DevSprint Data Science Agent
+emoji: 🤖
+colorFrom: blue
+colorTo: purple
+sdk: docker
+pinned: false
+license: mit
+app_port: 7860
+---
+
+# DevSprint Data Science Agent 🤖
+
+An intelligent AI agent for automated data science workflows, powered by Google Gemini 2.5 Flash with 82+ specialized tools for data analysis, visualization, and machine learning.
+
+## Features
+
+- 🔍 **Automated EDA**: YData profiling, statistical analysis, data quality reports
+- 📊 **Smart Visualizations**: Plotly dashboards, matplotlib plots, interactive charts
+- 🧹 **Data Cleaning**: Missing value handling, outlier detection, type conversion
+- 🛠️ **Feature Engineering**: Automated feature creation, encoding, scaling
+- 🤖 **ML Training**: AutoML with XGBoost, LightGBM, CatBoost, Neural Networks
+- 💬 **Natural Language Interface**: Chat-based interaction for complex workflows
+- 📈 **Business Intelligence**: KPI tracking, trend analysis, forecasting
+
+## Tech Stack
+
+- **Backend**: FastAPI + Python 3.12
+- **LLM**: Google Gemini 2.5 Flash (text-based tool calling)
+- **Data Processing**: Polars (high-performance dataframes)
+- **Frontend**: React 19 + TypeScript + Vite
+- **ML Libraries**: Scikit-learn, XGBoost, LightGBM, CatBoost, PyTorch
+
+## Usage
+
+1. Upload your CSV/Excel dataset
+2. Ask questions in natural language (e.g., "Generate a detailed profiling report")
+3. The agent automatically selects and executes the right tools
+4. View generated reports, visualizations, and insights
+
+## Memory Optimization
+
+For large datasets (>50k rows or >10MB), the agent automatically:
+- Samples to 50,000 rows for profiling
+- Enables minimal mode to reduce memory usage
+- Disables expensive correlation/interaction calculations
+
+This ensures smooth operation even with large datasets on HuggingFace's 16GB RAM.
+
+## Environment Variables
+
+Set `GEMINI_API_KEY` in HuggingFace Spaces settings (Settings → Repository secrets):
+
+```
+GEMINI_API_KEY=your_google_gemini_api_key_here
+```
+
+Get your API key from: https://aistudio.google.com/app/apikey
+
+## Local Development
+
+```bash
+# Clone repository
+git clone https://huggingface.co/spaces/YOUR_USERNAME/devs-print-data-science-agent
+cd devs-print-data-science-agent
+
+# Install dependencies
+pip install -r requirements.txt
+npm install --prefix FRRONTEEEND
+
+# Build frontend
+cd FRRONTEEEND && npm run build && cd ..
+
+# Set API key
+export GEMINI_API_KEY=your_key_here
+
+# Run server
+uvicorn src.api.app:app --host 0.0.0.0 --port 7860
+```
+
+## Architecture
+
+```
+┌─────────────────┐
+│  React Frontend │  ← User uploads data + asks questions
+└────────┬────────┘
+         │
+┌────────▼────────┐
+│  FastAPI Server │  ← Serves frontend + API endpoints
+└────────┬────────┘
+         │
+┌────────▼────────┐
+│  Orchestrator   │  ← LLM-driven tool selection & execution
+└────────┬────────┘
+         │
+┌────────▼────────┐
+│   82+ Tools     │  ← Specialized data science functions
+└─────────────────┘
+```
+
+## Key Components
+
+- **Orchestrator** ([src/orchestrator.py](src/orchestrator.py)): ReAct-based tool calling with Gemini
+- **Tools Registry** ([src/tools/](src/tools/)): 82+ specialized data science tools
+- **Session Memory** ([src/session_memory.py](src/session_memory.py)): Conversation history + file tracking
+- **Artifact Store** ([src/storage/artifact_store.py](src/storage/artifact_store.py)): File management + metadata
+
+## Deployment
+
+This Space uses a **Docker** deployment for maximum compatibility:
+- Base image: `python:3.12-slim`
+- Multi-stage build (Node.js for frontend, Python for backend)
+- Auto-exposes port 7860 for HuggingFace
+- All dependencies bundled in container
+
+## Contributing
+
+Built for DevSprint Hackathon 2025. Contributions welcome post-hackathon!
+
+## License
+
+MIT License - see LICENSE file for details

README_original.md

@@ -0,0 +1,993 @@
+# AI-Powered Data Science Agent
+
+## Overview
+
+The AI-Powered Data Science Agent is an intelligent autonomous system designed to perform complete end-to-end data science workflows through natural language interaction. This agent leverages Google Gemini 2.5 Flash for advanced reasoning and function calling capabilities, combined with a comprehensive suite of over 82 specialized machine learning tools.
+
+The system enables users to upload datasets in CSV or Parquet format and describe their analytical objectives in plain English. The agent autonomously handles the entire pipeline including data profiling, quality assessment, cleaning, feature engineering, model training, hyperparameter optimization, cross-validation, and comprehensive reporting generation.
+
+Key capabilities include intelligent intent classification, session memory for contextual awareness, error recovery mechanisms, and a modern React-based web interface for seamless user interaction.
+
+[![React](https://img.shields.io/badge/React-19-61DAFB?logo=react)](https://reactjs.org/)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.109-009688?logo=fastapi)](https://fastapi.tiangolo.com/)
+[![Gemini](https://img.shields.io/badge/Gemini-2.5_Flash-4285F4?logo=google)](https://ai.google.dev/)
+[![Python](https://img.shields.io/badge/Python-3.10+-3776AB?logo=python)](https://python.org/)
+
+---
+
+## Key Features
+
+### Autonomous AI Agent System
+
+The core orchestration engine integrates Google Gemini 2.5 Flash with over 82 specialized machine learning tools organized across multiple categories:
+
+- **Data Profiling Tools**: Generate comprehensive statistical summaries, distribution analysis, correlation matrices, data quality reports, and automated anomaly detection
+- **Data Cleaning Tools**: Handle missing values with intelligent imputation strategies (mean, median, mode, forward/backward fill, KNN), outlier detection and treatment using IQR and Z-score methods, duplicate removal, and data type conversions
+- **Feature Engineering Tools**: Create time-based features (hour, day, month, year, cyclical encodings), polynomial features, interaction terms, statistical aggregations, lag features, rolling window statistics, and domain-specific transformations
+- **Model Training Tools**: Support for multiple algorithm families including linear models (Ridge, Lasso, ElasticNet), tree-based models (Random Forest, Gradient Boosting), and advanced gradient boosting frameworks (XGBoost, LightGBM, CatBoost)
+- **Visualization Tools**: Generate interactive Plotly visualizations, Matplotlib static plots, correlation heatmaps, distribution plots, scatter matrices, feature importance charts, and residual analysis plots
+
+The intelligent orchestration system uses function calling capabilities to dynamically select and execute appropriate tools based on user intent. The agent maintains session memory for contextual awareness across conversation turns, enabling multi-turn dialogues where previous actions and results inform subsequent decisions.
+
+Smart intent detection automatically classifies incoming requests into categories such as full ML pipeline execution, exploratory data analysis, data cleaning only, visualization generation, or multi-intent tasks requiring combined workflows.
+
+Error recovery mechanisms include automatic retry logic with corrected parameters, file existence validation before tool execution, recovery guidance displaying the last successful file state, and loop detection to prevent infinite retry cycles.
+
+### Modern Web Interface
+
+The frontend is built with React 19 and TypeScript 5.8, featuring a modern glassmorphism design aesthetic with smooth animations powered by Framer Motion. Key interface components include:
+
+- **Landing Page**: Geometric hero section with animated background paths, key capabilities showcase, problem-solution presentation, process flow visualization, and technology stack display
+- **Chat Interface**: Real-time message streaming, file upload support for CSV and Parquet formats, markdown rendering for formatted responses with code syntax highlighting, loading states with animated indicators, and error handling with user-friendly messages
+- **Report Viewer**: In-application modal viewer for HTML reports generated by YData Profiling and custom dashboard tools. Full-screen modal with professional styling, iframe embedding for report content, and download capabilities
+- **Session Management**: Maintains conversation history across browser sessions, allows users to review previous analyses, and provides context for follow-up questions
+
+### Complete Machine Learning Pipeline
+
+The agent executes a comprehensive end-to-end pipeline:
+
+1. **Data Profiling and Assessment**: Automatically generates statistical summaries including descriptive statistics (mean, median, standard deviation, quartiles), distribution analysis with histogram generation, correlation analysis with heatmap visualization, missing value analysis with percentage calculations, data type detection and validation, outlier detection using multiple methods (IQR, Z-score, isolation forest), and cardinality analysis for categorical variables
+
+2. **Data Cleaning and Preprocessing**: Handles missing values with context-aware imputation strategies, removes or treats outliers based on statistical thresholds, performs data type conversions and casting, removes duplicate records, handles inconsistent formatting in categorical variables, and validates data integrity constraints
+
+3. Quick Start Guide
+
+### Prerequisites
+
+Before beginning the installation, ensure your system meets the following requirements:
+
+- **Python**: Version 3.10 or higher with pip package manager
+- **Node.js**: V Steps
+
+**Step 1: Clone the Repository**
+
+Clone the repository from GitHub and navigate to the project directory:
+
+```bash
+git clone https://github.com/Pulastya-B/DevSprint-Data-Science-Agent.git
+cd DevSprint-Data-Science-Agent
+```
+
+**Step 2: Configure Environment Variables**
+
+Create a `.env` file in the root directory with the following configuration:
+
+```bash
+# LLM Provider Configuration
+LLM_PROVIDER=gemini
+
+# Google Gemini API Key (required)
+GOOGLE_API_KEY=your_api_key_here
+
+# Model Configuration
+GEMINI_MODEL=gemini-2.5-flash
+
+# Cache Configuration
+CACHE_DB_PATH=./cache_db/cache.db
+CACHE_TTL_SECONDS=86400
+
+# Output and Data Directories
+OUTPUT_DIR=./outputs
+DATA_DIR=./data
+```
+
+Replace `your_api_key_here` with your actual Google Gemini API key obtained from https://ai.google.dev/
+
+**Step 3: Install Python Dependencies**
+
+Install all required Python packages using pip:
+
+```bash
+pip install -r requirements.txt
+```
+
+ThiUsage Guide
+
+### Web Interface Workflow
+
+**Step 1: Access the Application**
+
+Open your web browser and navigate to http://localhost:8080. You will see the landing page with an overview of the agent's capabilities.
+
+**Step 2: Launch the Chat Interface**
+
+Click the "Launch Agent" button to access the interactive chat interface.
+
+**Step 3: Upload Your Dataset**
+
+Click the file upload button (paperclip icon) and select your dataset file. Supported formats:
+- CSV files (.csv) with any delimiter (comma, tab, semicolon, etc.)
+- Parquet files (.parquet) for high-performance columnar storage
+
+The agent will automatically detect the file format and load the data using appropriate parsers.
+
+**Step 4: Describe Your Task**
+
+Type your request in natural language in the chat input box. The agent understands various types of requests and will automatically determine the appropriate workflow.
+
+**Step 5: Review Results**
+
+The agent will execute the requested workflow and display results in the chat interface. For analyses that generate HTML reports (such as YData Profiling), a "View Report" button will appear. Click this button to open the report in a full-screen modal viewer.
+
+### Example Queries and Use Cases
+
+**Data Profiling and Exploration:**
+```
+"Generate a comprehensive profile report on this dataset"
+"Show me the statistical summary and distribution of all variables"
+"Analyze data quality issues including missing values and outliers"
+"Create a correlation matrix and identify highly correlated features"
+```
+
+**Data Cleaning:**
+```
+"Clean the missing values using median imputation for numeric columns"
+"Handle outliers in the dataset using IQR method"
+"Remove duplicate records and fix data type inconsistencies"
+"Drop columns with more than 50% missing values"
+```
+
+**Predictive Modeling:**
+```
+"Train a model to predict the target column 'price' using all features"
+"Build a classification model for the 'churn' column"
+"Compare multiple regression algorithms and select the best one"
+"Train an XGBoost model with default hyperparameters"
+```
+
+**Feature Engineering:**
+```
+"Extract time-based features from the datetime column"
+"Create interaction terms between numeric features"
+"Apply target encoding for high-cardinality categorical variables"
+"Generate polynomial features of degree 2"
+```
+
+**Model Optimization:**
+```
+"Perform hyperparameter tuning on the trained model using Optuna"
+"Run 5-fold cross-validation to evaluate model performance"
+"Optimize the XGBoost model for better accuracy"
+```
+
+**Visualization:**
+```
+"Generate a correlation heatmap for numeric features"
+"Create distribution plots for all numeric columns"
+"Show feature importance for the trained model"
+"Generate interactive Plotly visualizations"
+```
+
+**End-to-End Pipeline:**
+```
+"Profile the data, clean it, engineer features, and train the best model"
+"Perform complete analysis and predict the target column 'sales'"
+"Do everything needed to build a production-ready model
+.\start.ps1
+```
+
+**For Linux/macOS:**
+```bash
+chmod +x start.sh
+./start.sh
+```
+
+The startup script will:
+1. Technology Stack
+
+### Frontend Technologies
+
+- **React 19.2.3**: Latest version of React with improved concurrent rendering, automatic batching, and enhanced hooks for building performant user interfaces
+- **TypeScript 5.8.2**: Provides static type checking, enhanced IDE support, and improved code maintainability with advanced type inference
+- **Vite 6.2.0**: Next-generation frontend build tool offering instant server start, lightning-fast hot module replacement (HMR), and optimized production builds
+- **Tailwind CSS 3.4.1**: Utility-first CSS framework enabling rapid UI development with pre-built classes and responsive design utilities
+- **Framer Motion 12.23.26**: Production-ready animation library for React with declarative animations, gestures, and smooth transitions
+- **React Markdown 9.0.1**: Markdown rendering component supporting GitHub-flavored markdown, code syntax highlighting, and custom renderers
+- **Lucide React**: Icon library providing consistent, customizable SVG icons for the user interface
+
+### Backend Technologies
+
+- **FastAPI 0.109+**: Modern, high-performance Python web framework with automatic OpenAPI documentation, async/await support, and built-in request validation
+- **Google Gemini 2.5 Flash**: Large language model with advanced reasoning capabilities, function calling support, and high token limits for agent orchestration
+- **Polars 0.20+**: High-performance DataFrame library written in Rust, offering 10-100x speed improvements over pandas for large datasets
+- **Scikit-learn 1.3+**: Comprehensive machine learning library providing classical algorithms for classification, regression, clustering, and preprocessing
+- **XGBoost 2.0+**: Optimized gradient boosting framework with parallel tree construction, regularization, and efficient handling of sparse data
+- **LightGBM 4.1+**: Gradient boosting framework by Microsoft with leaf-wise tree growth, categorical feature support, and memory efficiency
+- **CatBoost 1.2+**: Gradient boosting library by Yandex with native categorical feature handling, GPU support, and symmetric tree structure
+- **Optuna 3.5+**: Hyperparameter optimization framework with Bayesian optimization, pruning strategies, and distributed optimization support
+- **YData Profiling 4.6+**: Automated exploratory data analysis tool generating comprehensive HTML reports with statistical summaries and data quality insights
+- **Plotly 5.18+**: Interactive visualization library creating web-based charts with zooming, panning, and hover tooltips
+- **Matplotlib 3.8+**: Fundamental plotting library for Python offering publication-quality static visualizations
+- **Pydantic 2.5+**: Data validation library using Python type annotations for request/response models
+
+###Docker Deployment
+
+The application includes a multi-stage Dockerfile for optimized containerized deployment.
+
+### Building the Docker Image
+
+Build the Docker image with the following command:
+
+```bash
+docker build -t ds-agent:latest .
+```
+
+The multi-stage build process:
+1. **Stage 1 (Builder)**: Installs Node.js dependencies and builds the React frontend
+2. **Stage 2 (Runtime)**: Sets up Python environment, installs backend dependencies, and copies built frontend
+3. Result: Optimized image size by excluding development dependencies and build tools
+
+### Running the Container
+
+Run the containerized application:
+
+```bash
+docker run -d \
+  -p 8080:8080 \
+  --env-file .env \
+  --name ds-agent-container \
+  ds-agent:latest
+```
+
+Parameters explained:
+- `-d`: Run container in detached mode (background)
+- `-p 8080:8080`: Map container port 8080 to host port 8080
+- `--env-file .env`: Load environment variables from .env file
+- `--name ds-agent-container`: Assign a name to the container for easy management
+
+### Docker Compose (Recommended)
+
+For easier management, create a `docker-compose.yml` file:
+
+```yaml
+version: '3.8'
+
+services:
+  ds-agent:
+    build: .
+    container_name: ds-agent
+    ports:
+      - "8080:8080"
+    env_file:
+      - .env
+    volumes:
+   Environment Configuration
+
+The application uses environment variables for configuration management. Create a `.env` file in the project root directory with the following variables:
+
+### Required Configuration
+
+```bash
+# LLM Provider Selection
+LLM_PROVIDER=gemini
+# Options: gemini (currently supported)
+
+# Google Gemini API Key (REQUIRED)
+GOOGLE_API_KEY=your_api_key_here
+# Obtain from: https://ai.google.dev/
+# Free tier limits: 10 RPM, 20 RPD
+
+# Gemini Model Selection
+GEMINI_MODEL=gemini-2.5-flash
+# Options:
+#   - gemini-2.5-flash (recommended, balanced performance)
+#   - gemini-1.5-pro (higher capability, lower rate limits)
+#   - gemini-1.5-flash (faster, lower cost)
+```
+
+### Optional Configuration
+Advanced Features
+
+### Intelligent Intent Detection and Classification
+
+The orchestration system employs sophisticated intent detection to automatically classify user requests and route them to appropriate workflow pipelines. The classification system analyzes incoming natural language queries using keyword matching, pattern recognition, and contextual understanding.
+
+**Intent Categories:**
+
+1. **Full ML Pipeline Intent**: Triggered by keywords such as "train", "model", "predict", "machine learning", "regression", "classification". Executes complete workflow including data profiling, cleaning, feature engineering, model training, hyperparameter tuning, and evaluation.
+
+2. **Exploratory Analysis Intent**: Activated by keywords like "explore", "profile", "report", "analysis", "overview", "insights", "understand". Performs comprehensive data profiling with statistical summaries, distribution analysis, correlation matrices, and automated insights generation.
+
+3. **Data Cleaning Intent**: Detected via keywords such as "clean", "missing", "outliers", "duplicates", "impute", "handle". Focuses on data quality improvement operations without proceeding to modeling.
+
+4. **Visualization Intent**: Identified through keywords like "plot", "visualize", "chart", "graph", "heatmap", "distribution". Generates requested visualizations without performing modeling or extensive preprocessing.
+
+5. **Feature Engineering Intent**: Recognized by keywords such as "feature", "engineer", "create features", "transform", "encode". Applies feature transformation and creation operations.
+
+6. **Multi-Intent Workflows**: The system can detect and handle requests combining multiple intents, executing them in a logical sequence.
+
+The intent classification system uses confidence scoring to handle ambiguous requests and can ask clarifying questions when intent is unclear.
+
+### Context-Aware Session Memory
+
+The agent implements persistent session memory that maintains conversation context across multiple turns. This enables natural multi-turn dialogues where subsequent requests can reference previous operations without requiring full context repetition.
+
+**Session Memory Capabilities:**
+
+- **Workflow History**: Stores complete history of executed tools, parameters, and results for the current session
+- **File State Tracking**: Maintains references to uploaded files, intermediate processed datasets, and generated outputs
+- **Model Persistence**: Remembers trained models and their performance metrics for comparison and further tuning
+- **Error Context**: Stores information about encountered errors to avoid repeating failed operations
+- **User Preferences**: Learns from user choices (e.g., preferred visualization types, imputation strategies)
+
+**Example Multi-Turn Conversation:**
+
+```Complete Workflow Example
+
+This section demonstrates a complete end-to-end workflow for a real-world dataset, showing the agent's autonomous decision-making and execution capabilities.
+
+### Dataset: Earthquake Magnitude Prediction
+
+**Input Dataset:** `earthquake_data.csv`
+- Rows: 175,947 earthquake records
+- Columns: 22 features including latitude, longitude, depth, time, location, and magnitude
+- Target Variable: Earthquake magnitude (continuous regression task)
+- Data Quality: 11.67% missing values, presence of outliers, mixed data types
+
+**User Prompt:**
+```
+"Train a model to predict earthquake magnitude with the highest possible accuracy"
+```
+
+### Automated Workflow Execution
+
+**Phase 1: Data Profiling and Assessment** (Step 1)
+- Tool: `generate_ydata_profile`
+- Action: Comprehensive statistical analysis of all 22 features
+- Findings:
+  - Total records: 175,947
+  - Missing values detected in 8 columns
+  - Outliers present in depth, latitude, longitude
+  - High cardinality in location column (15,000+ unique values)
+  - Strong correlation between depth and magnitude (r=0.62)
+- Output: YData Profiling HTML report saved to `outputs/earthquake_profile.html`
+- Time: 18.3 seconds
+API Reference
+
+The FastAPI backend exposes several endpoints for programmatic interaction.
+
+### Endpoints
+
+**POST /chat**
+- Description: Send a message to the agent with optional file upload
+- Content-Type: multipart/form-data
+- Parameters:
+  - message (string, required): User's natural language request
+  - file (file, optional): Dataset file (CSV or Parquet)
+- Response: JSON with agent's response message and workflow history
+- Example:
+```bash
+curl -X POST http://localhost:8080/chat \
+  -F "message=Generate a data profile report" \
+  -F "file=@dataset.csv"
+```
+
+**POST /run**
+- Description: Execute a complete analysis workflow
+- Content-Type: application/json
+- Parameters:
+  - query (string, required): Analysis request
+  - use_cache (boolean, optional): Enable caching (default: true)
+- Response: JSON with analysis results and generated artifacts
+- Example:
+```json
+{
+  "query": "Train a regression model to predict sales",
+  "use_cache": true
+}
+```
+
+**GET /outputs/{file_path}**
+- Description: Retrieve generated reports and artifacts
+- Parameters:
+  - file_path (string, required): Path to output file
+- Response: File content (HTML, PNG, CSV, etc.)
+- Example:
+```bash
+curl http://localhost:8080/outputs/ydata_profile.html
+```
+
+**GET /api/health**
+- Description: Health check endpoint
+- Response: JSON with status information
+- Example response:
+```json
+{
+  "status": "healthy",
+  "version": "1.0.0",
+  "timestamp": "2025-12-27T10:30:00Z"
+}
+```
+
+### Interactive API Documentation
+
+FastAPI automatically generates interactive API documentation:
+- Swagger UI: http://localhost:8080/docs
+- ReDoc: http://localhost:8080/redoc
+
+## Contributing
+
+Contributions to improve the AI-Powered Data Science Agent are welcome. Please follow these guidelines:
+
+### Development Setup
+
+1. Fork the repository and clone your fork
+2. Create a new branch for your feature: `git checkout -b feature/your-feature-name`
+3. Install development dependencies: `pip install -r requirements-dev.txt`
+4. Make your changes with appropriate tests
+5. Ensure all tests pass: `pytest tests/`
+6. Format code with black: `black src/`
+7. Lint code with flake8: `flake8 src/`
+8. Commit with descriptive messages
+9. Push to your fork and submit a pull request
+
+### Code Style
+
+- Follow PEP 8 guidelines for Python code
+- Use type hints for function parameters and return values
+- Write docstrings for all functions and classes
+- Keep functions focused and under 50 lines when possible
+- Use meaningful variable names
+
+### Testing
+
+- Write unit tests for new features
+- Ensure existing tests pass before submitting PR
+- Aim for >80% code coverage
+
+## License
+
+This project is licensed under the MIT License. See the LICENSE file for complete terms.
+
+Copyright (c) 2025 Pulastya B
+
+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. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+## Acknowledgments
+
+This project builds upon several excellent open-source technologies and frameworks:
+
+- **Google Gemini 2.5 Flash**: Advanced language model with function calling capabilities enabling intelligent agent orchestration
+- **FastAPI**: Modern, high-performance web framework for building APIs with Python, providing automatic documentation and validation
+- **React**: JavaScript library for building user interfaces, enabling component-based architecture and efficient rendering
+- **Polars**: High-performance DataFrame library written in Rust, offering significant speed improvements over traditional data processing libraries
+- **Scikit-learn**: Machine learning library providing simple and efficient tools for data analysis and modeling
+- **XGBoost, LightGBM, CatBoost**: Gradient boosting frameworks offering state-of-the-art performance for structured data
+- **Optuna**: Hyperparameter optimization framework with efficient search algorithms
+- **YData Profiling**: Automated exploratory data analysis tool generating comprehensive reports
+- **Plotly**: Interactive visualization library for creating publication-quality graphs
+- **TypeScript**: Typed superset of JavaScript enhancing code quality and developer experience
+- **Tailwind CSS**: Utility-first CSS framework for rapid UI development
+- **Vite**: Next-generation frontend build tool with instant server start
+
+Special thanks to the open-source community for creating and maintaining these exceptional tools.
+
+## Contact and Support
+
+**Developer:** Pulastya B
+
+**GitHub Profile:** [@Pulastya-B](https://github.com/Pulastya-B)
+
+**Project Repository:** [DevSprint-Data-Science-Agent](https://github.com/Pulastya-B/DevSprint-Data-Science-Agent)
+
+**Issues and Bug Reports:** Please use the GitHub Issues page to report bugs or request features
+
+**Documentation:** Additional documentation and tutorials available in the repository wiki
+
+**Project Status:** Active development - Built for DevSprint Hackathon
+
+For questions, suggestions, or collaboration opportunities, please open an issue on GitHub or contact through the repository.
+
+---
+
+**Last Updated:** December 27, 2025
+
+**Version:** 1.0.0
+Step 6 - Temporal Feature Extraction:
+- Tool: `extract_time_features`
+- Input column: 'timestamp'
+- Features created:
+  - year, month, day_of_week, hour
+  - Cyclical encodings: hour_sin, hour_cos, month_sin, month_cos
+- Justification: Earthquakes may have temporal patterns
+- New columns: 8 time-based features
+
+Step 7 - Categorical Encoding:
+- Tool: `encode_categorical_features`
+- Method: Target encoding for 'location' (high cardinality), one-hot encoding for 'type'
+- Result: All categorical variables converted to numeric
+- New columns: 3 (reduced from high-cardinality location)
+
+Step 8 - Statistical Features:
+- Tool: `create_statistical_features`
+- Features created:
+  - Distance from nearest plate boundary (calculated from lat/lon)
+  - Depth-to-magnitude ratio
+  - Regional earthquake frequency (rolling count)
+- New columns: 3 domain-specific features
+
+Final feature count: 28 engineered features
+
+**Phase 5: Model Training and Selection** (Step 9)
+- Tool: `train_baseline_models`
+- Algorithms trained in parallel:
+
+1. Ridge Regression: R² = 0.534, RMSE = 0.312
+2. Lasso Regression: R² = 0.541, RMSE = 0.309
+3. ElasticNet: R² = 0.538, RMSE = 0.311
+4. Random Forest: R² = 0.698, RMSE = 0.251
+5. XGBoost: R² = 0.716, RMSE = 0.243 (BEST)
+6. LightGBM: R² = 0.709, RMSE = 0.247
+7. CatBoost: R² = 0.712, RMSE = 0.245
+
+- Best model selected: XGBoost
+- Validation split: 80/20 stratified split
+- Time: 124.7 seconds
+
+**Phase 6: Hyperparameter Optimization** (Step 10)
+- Tool: `optimize_hyperparameters_optuna`
+- Framework: Optuna with Tree-structured Parzen Estimator (TPE)
+- Search space:
+  - max_depth: [3, 10]
+  - learning_rate: [0.001, 0.3] (log scale)
+  - n_estimators: [100, 1000]
+  - min_child_weight: [1, 10]
+  - subsample: [0.6, 1.0]
+  - colsample_bytree: [0.6, 1.0]
+- Trials: 50 iterations
+- Best parameters found:
+  - max_depth: 7
+  - learning_rate: 0.0847
+  - n_estimators: 673
+  - min_child_weight: 3
+  - subsample: 0.8234
+  - colsample_bytree: 0.9123
+- Optimized performance: R² = 0.743, RMSE = 0.231
+- Improvement: +3.8% R² over baseline
+- Time: 312.4 seconds
+
+**Phase 7: Model Validation** (Step 11)
+- Tool: `cross_validate_model`
+- Method: 5-fold stratified cross-validation
+- Results:
+  - Fold 1: R² = 0.741, RMSE = 0.232
+  - Fold 2: R² = 0.745, RMSE = 0.230
+  - Fold 3: R² = 0.738, RMSE = 0.234
+  - Fold 4: R² = 0.747, RMSE = 0.229
+  - Fold 5: R² = 0.742, RMSE = 0.232
+- Mean performance: R² = 0.743 ± 0.003, RMSE = 0.231 ± 0.002
+- Interpretation: Low variance across folds indicates robust, generalizable model
+- Time: 267.8 seconds
+
+**Phase 8: Visualization and Reporting** (Steps 12-13)
+
+Step 12 - Feature Importance Analysis:
+- Tool: `plot_feature_importance`
+- Top 10 features by importance:
+  1. depth (0.284)
+  2. distance_to_plate_boundary (0.167)
+  3. latitude (0.142)
+  4. longitude (0.138)
+  5. regional_frequency (0.095)
+  6. depth_magnitude_ratio (0.067)
+  7. hour_sin (0.034)
+  8. month (0.028)
+  9. location_encoded (0.024)
+  10. year (0.021)
+- Output: Interactive Plotly bar chart saved to `outputs/feature_importance.html`
+
+Step 13 - Comprehensive Dashboard:
+- Tool: `create_plotly_dashboard`
+- Visualizations included:
+  - Correlation heatmap (28x28 features)
+  - Actual vs Predicted scatter plot
+  - Residual distribution plot
+  - Feature importance ranking
+  - Temporal patterns in predictions
+- Output: Multi-panel interactive dashboard saved to `outputs/model_dashboard.html`
+
+### Final Results Summary
+
+**Model Performance:**
+- Algorithm: XGBoost with optimized hyperparameters
+- Training R²: 0.743
+- Cross-validated R²: 0.743 ± 0.003
+- RMSE: 0.231 (on magnitude scale 0-10)
+- MAE: 0.176
+- Explanation: Model explains 74.3% of variance in earthquake magnitudes
+
+**Artifacts Generated:**
+- Trained model file: `outputs/xgboost_model_optimized.pkl`
+- YData profiling report: `outputs/earthquake_profile.html`
+- Feature importance plot: `outputs/feature_importance.html`
+- Interactive dashboard: `outputs/model_dashboard.html`
+- Cleaned dataset: `data/earthquake_data_cleaned.parquet`
+- Feature engineered dataset: `data/earthquake_data_featured.parquet`
+
+**Total Execution Time:** 12 minutes 43 seconds
+
+**Key Insights:**
+1. Depth is the strongest predictor of earthquake magnitude (28.4% importance)
+2. Spatial features (distance to plate boundaries, lat/lon) are highly informative
+3. Temporal patterns show cyclical variations in earthquake characteristics
+4. Model performance is consistent across cross-validation folds (low variance)
+5. The optimized XGBoost model provides reliable magnitude predictions suitable for deployment
+
+### Robust Error Recovery System
+
+The agent implements a comprehensive error recovery system designed to handle failures gracefully and guide users toward successful task completion.
+
+**Error Recovery Mechanisms:**
+
+1. **Automatic Retry with Correction**: When a tool execution fails due to incorrect parameters, the agent analyzes the error message, adjusts parameters based on the error type, and automatically retries the operation with corrected inputs.
+
+2. **File Existence Validation**: Before executing tools that require specific file inputs, the system validates file existence and accessibility, providing clear guidance when files are missing.
+
+3. **Column Name Validation**: Validates that requested column names exist in the dataset before performing operations, suggesting similar column names when exact matches aren't found.
+
+4. **Dependency Tracking**: Ensures tools are executed in proper sequence, checking that prerequisite operations (e.g., data cleaning before training) have been completed.
+
+5. **Loop Detection**: Monitors tool execution patterns to detect and prevent infinite retry loops. If the same operation fails multiple times with the same error, the agent stops retrying and requests user intervention.
+
+6. **Recovery Guidance**: When errors cannot be automatically resolved, the system provides detailed guidance including:
+   - Clear explanation of what went wrong
+   - The last successful file state that can be used to continue
+   - Suggested alternative approaches
+   - Specific parameter corrections needed
+
+7. **Graceful Degradation**: If a requested operation cannot be completed, the agent attempts to provide partial results or alternative analysis that may still be valuable.
+
+**Example Error Recovery Flow:**
+
+```
+Request: "Train a model to predict 'Price' column"
+
+Error Detected: Column 'Price' not found in dataset
+Recovery Action: Search for similar columns → Find 'price', 'PRICE', 'SalePrice'
+Agent Response: "Column 'Price' not found. Did you mean 'SalePrice'? I found these similar columns: ['SalePrice', 'price_usd']. Please specify which column to use."
+
+User: "Yes, use SalePrice"
+Agent: [Continues with corrected column name]
+```
+
+### Interactive Report Viewing
+
+The web interface includes an integrated report viewer that displays comprehensive HTML reports generated during analysis without requiring users to download files or switch to external tools.
+
+**Report Viewer Features:**
+
+- **In-Application Display**: Reports open in a full-screen modal overlay within the chat interface
+- **Multiple Report Types**: Supports YData Profiling reports and custom HTML dashboards
+- **Professional Styling**: Modal features glassmorphism design, smooth animations, and responsive layout
+- **Interactive Navigation**: Users can zoom, scroll, and interact with report elements directly in the viewer
+- **Download Option**: Reports can be downloaded as standalone HTML files for sharing or archival
+- **Automatic Detection**: System automatically detects when tools generate HTML reports and creates "View Report" buttons in the chat interface
+
+**Supported Report Types:**
+
+1. **YData Profiling Reports**: Comprehensive automated EDA with variable statistics, distributions, correlations, missing value analysis, and alerts for data quality issues
+
+2. **Custom Dashboards**: User-created Plotly dashboards with multiple interactive visualizations
+
+The report extraction system uses multiple strategies to locate report files, including checking tool return values, parsing workflow history, and using regex pattern matching on agent responses.
+- Use different API keys for development and production
+- Rotate API keys periodically
+- Set restrictive file permissions on `.env` (chmod 600 on Linux/macOS)inux/macOS:**
+```bash
+chmod +x build-and-deploy.sh
+./build-and-deploy.sh
+```
+
+These scripts handle building the image, stopping any existing containers, and starting a new container with proper configuration.FRRONTEEEND
+npm install
+npm run build
+cd ..
+```
+
+**5. Run the application**
+
+**Windows:**
+```powershell
+.\start.ps1
+```
+
+**Linux/Mac:**
+```bash
+chmod +x start.sh
+./start.sh
+```
+
+The application will be available at **http://localhost:8080**
+
+---
+
+## 📖 Usage
+
+### Web Interface
+
+1. **Navigate to http://localhost:8080**
+2. **Click "Launch Agent"** from the landing page
+3. **Upload your dataset** (CSV or Parquet format)
+4. **Type your request** in natural language:
+   - "Generate a comprehensive report on this dataset"
+   - "Train a model to predict [target_column]"
+   - "Clean the data and show me visualizations"
+   - "Perform feature engineering and train the best model"
+5. **View results** in the chat and click "View Report" buttons to see detailed HTML reports
+
+### Example Queries
+
+```
+📊 "Profile this dataset and tell me about data quality issues"
+
+🧹 "Clean the missing values and handle outliers"
+
+🎯 "Train a model to predict house prices with target column 'price'"
+
+📈 "Generate a correlation heatmap and feature importance plot"
+
+🔧 "Create time-based features and perform hyperparameter tuning"
+
+📋 "Generate a comprehensive YData profiling report"
+```
+
+---
+
+## 🏗️ Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    React Frontend (Port 8080)                │
+│  Landing Page │ Chat Interface │ Report Viewer               │
+└─────────────────────────┬───────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│              FastAPI Backend (Python 3.10+)                  │
+│  /chat │ /run │ /outputs │ /api/health                      │
+└─────────────────────────┬───────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│           DataScienceCopilot Orchestrator                    │
+│  • Gemini 2.5 Flash Integration                             │
+│  • 82+ Specialized Tools                                     │
+│  • Session Memory & Context                                  │
+│  • Intelligent Intent Detection                              │
+│  • Error Recovery & Loop Prevention                          │
+└─────────────────────────┬───────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│                     Tool Categories                          │
+│  Profiling │ Cleaning │ Feature Engineering │ ML Training   │
+│  Visualization │ EDA Reports │ Data Wrangling               │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+##  Tech Stack
+
+### Frontend
+- **React 19** - Modern UI library
+- **TypeScript 5.8** - Type-safe development
+- **Vite 6** - Lightning-fast build tool
+- **Tailwind CSS** - Utility-first styling
+- **Framer Motion** - Smooth animations
+- **React Markdown** - Formatted responses
+
+### Backend
+- **FastAPI** - High-performance Python web framework
+- **Google Gemini 2.5 Flash** - LLM for agent orchestration
+- **Polars** - Fast dataframe library (10-100x faster than pandas)
+- **Scikit-learn** - Classical ML algorithms
+- **XGBoost / LightGBM / CatBoost** - Gradient boosting frameworks
+- **Optuna** - Hyperparameter optimization
+- **YData Profiling** - Automated EDA reports
+- **Plotly / Matplotlib** - Interactive visualizations
+
+### DevOps
+- **Docker** - Containerization with multi-stage builds
+- **Python-dotenv** - Environment variable management
+- **SQLite** - Caching layer for performance
+
+---
+
+## 🐳 Docker Deployment
+
+**Build and run with Docker:**
+
+```bash
+docker build -t ds-agent .
+docker run -p 8080:8080 --env-file .env ds-agent
+```
+
+**Or use the deployment script:**
+
+```bash
+.\build-and-deploy.ps1  # Windows
+./build-and-deploy.sh   # Linux/Mac
+```
+
+---
+
+## 📂 Project Structure
+
+```
+.
+├── FRRONTEEEND/              # React frontend
+│   ├── components/           # UI components
+│   │   ├── ChatInterface.tsx # Main chat interface
+│   │   ├── HeroGeometric.tsx # Landing page hero
+│   │   └── ...
+│   ├── dist/                 # Built frontend
+│   └── package.json
+│
+├── src/                      # Python backend
+│   ├── api/
+│   │   └── app.py           # FastAPI application
+│   ├── orchestrator.py      # Agent orchestrator
+│   ├── session_memory.py    # Session management
+│   ├── tools/               # 82+ ML tools
+│   │   ├── data_profiling.py
+│   │   ├── data_cleaning.py
+│   │   ├── feature_engineering.py
+│   │   ├── model_training.py
+│   │   └── ...
+│   └── utils/               # Helper utilities
+│
+├── Dockerfile               # Multi-stage Docker build
+├── requirements.txt         # Python dependencies
+├── start.ps1 / start.sh    # Quick start scripts
+└── README.md               # This file
+```
+
+---
+
+## 🔑 Environment Variables
+
+Create a `.env` file in the root directory:
+
+```bash
+# LLM Provider Configuration
+LLM_PROVIDER=gemini
+
+# API Keys
+GOOGLE_API_KEY=your_gemini_api_key_here
+
+# Model Configuration
+GEMINI_MODEL=gemini-2.5-flash
+
+# Cache Configuration
+CACHE_DB_PATH=./cache_db/cache.db
+CACHE_TTL_SECONDS=86400
+
+# Output Configuration
+OUTPUT_DIR=./outputs
+DATA_DIR=./data
+```
+
+---
+
+## 🎯 Features in Detail
+
+### Intelligent Intent Detection
+The agent automatically classifies your request and applies the appropriate workflow:
+- **Full ML Pipeline** - Complete end-to-end workflow with training
+- **Exploratory Analysis** - Data profiling and visualization only
+- **Cleaning Only** - Data quality improvements without modeling
+- **Visualization Only** - Generate plots and dashboards
+- **Multi-Intent** - Combine multiple tasks intelligently
+
+### Session Memory
+The agent remembers context across messages:
+```
+You: "Train a model on this dataset"
+Agent: [Trains XGBoost model with R² = 0.85]
+
+You: "Now try hyperparameter tuning"
+Agent: [Automatically uses previous model and dataset]
+
+You: "Cross-validate it"
+Agent: [Applies CV to tuned model from context]
+```
+
+### Error Recovery
+- Automatic retry with corrected parameters
+- File existence validation before execution
+- Recovery guidance showing last successful file
+- Loop detection to prevent infinite retries
+
+### Report Viewing
+- Click "View Report" buttons to see HTML reports in-app
+- Full-screen modal with professional styling
+- Supports YData Profiling and custom dashboards
+
+---
+
+## 📊 Example Workflow
+
+**Upload:** `earthquake_data.csv` (175K rows, 22 columns)
+
+**Prompt:** "Train a model to predict earthquake magnitude"
+
+**Agent Actions:**
+1. ✅ Profiles dataset (175,947 rows, 22 columns)
+2. ✅ Detects data quality issues (11.67% missing, outliers)
+3. ✅ Drops high-missing columns (>40% missing)
+4. ✅ Imputes remaining missing values with median/mode
+5. ✅ Handles outliers with IQR clipping
+6. ✅ Extracts time-based features (year, month, hour, cyclical)
+7. ✅ Encodes categorical variables
+8. ✅ Trains 6 baseline models (XGBoost wins with R² = 0.716)
+9. ✅ Performs hyperparameter tuning (R² = 0.743)
+10. ✅ Runs 5-fold cross-validation (RMSE = 0.167 ± 0.0005)
+11. ✅ Generates YData profiling report
+12. ✅ Creates interactive Plotly dashboard
+
+**Result:** Trained and tuned XGBoost model ready for deployment!
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License.
+
+---
+
+## 🙏 Acknowledgments
+
+- **Google Gemini** for powerful LLM capabilities
+- **FastAPI** for excellent async Python framework
+- **React** community for amazing UI libraries
+- **Polars** for blazing-fast data processing
+- **YData Profiling** for comprehensive EDA reports
+
+---
+
+## 📧 Contact
+
+**Pulastya B**
+- GitHub: [@Pulastya-B](https://github.com/Pulastya-B)
+- Project: [DevSprint-Data-Science-Agent](https://github.com/Pulastya-B/DevSprint-Data-Science-Agent)
+
+---
+
+<div align="center">
+
+**Built with ❤️ for DevSprint Hackathon**
+
+⭐ Star this repo if you find it helpful!
+
+</div>