🌌 Nexus AutoML Platform

An Enterprise-Grade Machine Learning Operations Platform.
Designed for scalable execution, real-time telemetry, and hyper-optimized predictive modeling.

---

🚀 Overview

The Nexus AutoML Platform (formerly EvalHub) is a full-stack, state-of-the-art machine learning orchestration engine. Built from the ground up to eliminate the friction between data engineering and model deployment, it offers an elegant, glassmorphism-inspired React dashboard connected to a high-performance Python/FastAPI backend.

Whether you're benchmarking baseline models or orchestrating massive hyperparameter sweeps across XGBoost and LightGBM, the Nexus Engine handles real-time distributed execution, cross-validation, and metrics aggregation with zero configuration overhead.

✨ Key Enterprise Features

• ⚡ Eager Concurrency Engine: Bypasses traditional queue-locking bottlenecks with a highly optimized background thread-pool executor, delivering instantaneous execution without heavy message brokers.
• 📊 Real-Time Telemetry: Live execution timelines pushed directly to the UI, allowing data scientists to monitor data validation, feature engineering, and fold-by-fold cross-validation in real-time.
• 🧠 Full Algorithmic Suite: Natively supports the industry's most powerful algorithms: LightGBM, XGBoost, RandomForest, GradientBoosting, SupportVectorMachines, NeuralNetworks, and more.
• 🛡️ Pristine Architecture: Completely decoupled frontend and backend. Highly portable, container-ready, and designed with clean domain-driven architecture.

---

🏗️ End-to-End Pipeline Architecture

The Nexus engine automates the entire lifecycle of a machine learning experiment through a rigorously structured Directed Acyclic Graph (DAG) pipeline:

1. Data Validation & Ingestion: Securely loads immutable DatasetVersions, dynamically parsing features, handling categorical encoding, and performing integrity checks.
2. Feature Engineering: Applies robust transformations, one-hot encoding, and feature caching via advanced hash-based storage.
3. Distributed Cross-Validation Search: Spawns concurrent folds and distributes training across multiple ML algorithms simultaneously. Evaluates utilizing F1-Score, Accuracy, Precision, and Recall.
4. Intelligence Aggregation: Synthesizes cross-validation folds into centralized statistical reports, instantly ranking the best-performing models on the Global Leaderboard.

---

🗂️ Project Architecture & Directory Structure

This project is built utilizing a strict Domain-Driven Design (DDD) approach, ensuring absolute separation of concerns between the presentation layer, the API routing layer, and the core machine learning worker engine.

backend/ (FastAPI & ML Engine)

The brain of the platform. It handles all database transactions, API requests, and triggers the machine learning workflows.

• routers/: Contains modular REST API endpoints (e.g., experiments.py, timeline.py), ensuring clean, scalable endpoint separation.
• models.py & schemas.py: SQLAlchemy ORM definitions and Pydantic validation models. Ensures 100% type-safety and robust data serialization between the database and the client.
• worker.py: The powerhouse ML executor. Contains the @workflow_task orchestration decorators and the mathematical implementations for training LightGBM, XGBoost, and other algorithms utilizing Scikit-Learn and Pandas.
• database.py & storage.py: Handles optimized SQLite connection pooling and artifact storage management.

frontend/ (React Dashboard)

The user interface layer built for high-performance telemetry rendering.

• src/components/: Modular, highly reusable React UI components. Highlights include Dashboard.tsx for tracking Global Leaderboards and Timeline.tsx for real-time Polling integration of the ML execution DAG.
• src/api.ts: The strongly-typed Axios fetch client bridging the frontend to the FastAPI backend.
• Tailwind & Vite: Utilizes Vite for lightning-fast Hot Module Replacement (HMR) and Tailwind for deep, modern glassmorphism UI styling.

scripts/ (DevOps & Initialization)

Automated scripts for zero-friction deployments.

• seed_demo.py: A robust database seeder that automatically provisions dummy data, benchmark experiments, and downloads the Scikit-Learn Iris dataset to simulate real-world usage immediately.
• start_demo.bat: A concurrent process manager that boots both Uvicorn and Vite servers simultaneously on Windows environments.
• qa_runner.bat: Quality assurance script for running Ruff linting, MyPy type-checking, and PyTest suites.

tests/ & Clean Infrastructure

• .gitignore: Strictly configured to block __pycache__, local SQLite datasets, node_modules, and .env files, maintaining 100% repository purity.
• tests/: Contains the pytest suites validating API integrity (test_api.py, test_auth.py).

---

🛠️ Tech Stack & Professionalism

• Frontend: React 18, TypeScript, TailwindCSS, Vite (Lightning-fast HMR & glassmorphism aesthetic).
• Backend: FastAPI (Asynchronous Python 3.12), SQLAlchemy 2.0 (ORM).
• ML Core: Scikit-Learn, LightGBM, XGBoost, Pandas.
• Orchestration: Custom Eager Thread Executor (designed for seamless portability without Redis/RabbitMQ overhead on Windows/macOS).

---

⚙️ Quickstart Setup

We have stripped away complex infrastructure requirements to ensure the platform is highly portable and immediately usable.

1. Clone & Install: Ensure you have Node.js and Python 3.12 installed.

   git clone https://github.com/yourusername/Nexus-AutoML-Platform.git
   cd Nexus-AutoML-Platform
   pip install -r requirements.txt
   npm install --prefix frontend

2. Initialize Demo Data: Populate the platform with seeded classification tasks.

   python scripts/seed_demo.py

3. Launch the Nexus Engine: Start both the backend and frontend simultaneously.

   ./scripts/start_demo.bat

4. Access the Dashboard: Open your browser to http://localhost:5173.

---

Built with absolute precision for high-performance machine learning execution.