Welcome to the Nexus AI Workspace — a robust, modular microservice architecture engineered for advanced AI integration, real-time network telemetry, and automated academic assistance. The workspace is composed of three fully independent services that can be run individually or orchestrated together using the provided batch launcher.
- Project Overview
- Repository Architecture
- The Three Microservices
- Technology Stack
- System Design Principles
- Quick Start
- Port Allocation
- Essential Documentation
- Project Status
The Nexus AI Workspace was designed and built as an internship evaluation project (Proternship 2026) at GCET. It demonstrates the practical implementation of several advanced software engineering concepts:
- Microservice architecture — three loosely coupled, independently deployable services.
- Large Language Model (LLM) integration — real-time, streaming AI inference using Groq Cloud and Google Gemini APIs.
- Retrieval-Augmented Generation (RAG) — local FAISS vector database for document-grounded AI answers.
- Multi-agent systems — a dual-agent paraphrase-and-inspect loop using both LLM generation and deterministic mathematical validation.
- Real-time data streaming — Server-Sent Events (SSE) used across all three services for progressive, live UI updates.
- Local data persistence — siloed SQLite databases per service, ensuring modularity and fault isolation.
- API reliability engineering — multi-key pool rotation and model fallback chains to guarantee near-zero downtime.
The following is the complete, annotated directory tree for the entire workspace:
Nexus AI Workspace/
│
├── nexus-ai/ # Core conversational AI and RAG engine
│ ├── backend/
│ │ ├── main.py # FastAPI application — all routes, auth, chat, admin
│ │ ├── api_key_manager.py # Dynamic API key pool: discovery, rotation, addition
│ │ ├── health_check.py # Startup health verification for all model providers
│ │ ├── models_config.json # Model registry: IDs, providers, fallback chains
│ │ ├── database.db # SQLite database (auto-created on first run, gitignored)
│ │ └── uploads/ # Uploaded PDFs and images (auto-created, gitignored)
│ ├── frontend/
│ │ ├── index.html # Main split-pane chat interface
│ │ ├── app.js # Complete frontend logic (~1,600 lines of vanilla JS)
│ │ ├── login.html # User authentication page
│ │ ├── register.html # New user registration page
│ │ ├── admin.html # System administration dashboard
│ │ └── favicon.png # Transparent brand favicon (served at /static/favicon.png)
│ ├── src/
│ │ ├── __init__.py # Package marker
│ │ ├── memory_manager.py # Long-term user memory: profile I/O, FIFO chat history
│ │ ├── rag_scholar.py # RAG pipeline: document ingestion, FAISS indexing, search
│ │ ├── latency_tracker.py # Background ping logger — writes to raw_pings.csv
│ │ └── latency_predictor.py # Random Forest ML model for time-of-day latency prediction
│ ├── data/
│ │ ├── textbooks/ # Place PDFs, DOCX, PPTX, XLSX, TXT here for RAG index
│ │ ├── raw_pings.csv # Auto-created by latency_tracker.py (gitignored)
│ │ └── <username>_profile.json # Auto-created per-user memory profiles (gitignored)
│ ├── models/
│ │ └── latency_model.pkl # Trained Random Forest model (auto-created, gitignored)
│ └── vector_store/
│ ├── .gitkeep # Preserves directory on fresh clone
│ └── faiss_index/ # Local FAISS vector index (auto-created, gitignored)
│
├── nexus-gamer/ # Network telemetry and speed test suite
│ ├── app.py # Flask server: speedtest SSE, chart generation, AI remark
│ ├── templates/
│ │ └── index.html # Jinja2 dashboard template
│ └── public/
│ ├── favicon.png # Transparent brand favicon (served at /public/favicon.png)
│ ├── style.css # Base styles
│ └── speed_chart_<uuid>.png # Dynamically generated chart images (gitignored)
│
├── nexus-academic-agent/ # Academic paraphrase and citation engine
│ ├── backend/
│ │ ├── main.py # FastAPI app: SSE endpoint, citation endpoint, static mount
│ │ └── agent_loop.py # Transmuter + Inspector dual-agent logic and citation scraper
│ └── frontend/
│ ├── index.html # Two-panel academic agent interface
│ ├── script.js # SSE consumer, citation API caller, UI controller
│ └── favicon.png # Transparent brand favicon (served at root /favicon.png)
│
├── assets/
│ ├── logo-transparent.png # Primary brand logo (PNG with alpha transparency)
│ ├── logo.jpg # Alternate brand logo (opaque, dark background)
│ └── nexus-launcher.ico # Multi-resolution Windows icon (committed, repo-portable)
│
├── tools/
│ └── launcher/
│ ├── nexus_launcher.py # Embedded Python launcher (entry point for the .exe)
│ └── build_launcher_exe.py # Rebuilds NexusLauncher-x64.exe — uses committed .ico
│
├── NexusLauncher-x64.spec # Portable PyInstaller spec (repo-relative paths, committed)
├── .env # Local API keys — never committed to version control
├── .env.example # Template showing all required environment variable names
├── .gitignore # Comprehensive ignore rules (build/, dist/, __pycache__, etc.)
├── requirements.txt # Unified, pinned dependency list for all services + build
├── start.bat # Windows one-click orchestration launcher
├── CODE_OF_CONDUCT.md # Community standards and conduct guidelines
├── CONTRIBUTING.md # Contribution policy and issue reporting guidelines
├── GUIDE.md # Deep-dive architecture and technical reference
├── LICENSE # MIT License
├── README.md # This file — project overview and entry point
└── SETUP.md # Complete installation and first-run instructions
Full documentation: nexus-ai/README.md
Nexus AI is the primary service of the workspace. It is a full-stack web application providing a sophisticated AI assistant experience. Running at http://localhost:8000, it exposes both a polished web interface and a complete JSON/SSE REST API.
Core capabilities:
- Multi-model streaming chat — Real-time token-by-token responses via SSE, with support for multiple Groq and Gemini models selectable per conversation.
- Multi-API fallback and key rotation — A pool of API keys per provider, cycled automatically on rate-limit errors (HTTP 429) or authentication failures (HTTP 401). A three-tier fallback chain (primary model → fallback model → emergency failover model) ensures near-continuous availability.
- Scholar Mode with RAG — Users upload PDFs or other documents; the backend extracts text using PyMuPDF, chunks and embeds it locally with FAISS, and injects semantically retrieved context into the LLM prompt. Responses include inline citations with exact quote references, and the right-pane PDF viewer highlights them live.
- Persistent user memory — A two-tier system: short-term thread-based history in SQLite, and a long-term memory vault in JSON profiles. A silent background task extracts personal facts from messages and stores them, so the AI personalizes every future response.
- Vision and multimodal analysis — Uploaded images (JPEG, PNG, WebP, GIF) are normalized to JPEG using Pillow and submitted to vision-capable LLMs for analysis.
- Live weather context injection — When weather keywords are detected in a query, the backend fetches real-time data from wttr.in and injects it into the system prompt.
- User authentication — Credential-based login with SHA-256 password hashing, thread-isolated history per user, and an admin account seeded on startup.
- Admin dashboard — Full control panel for managing users, model registries, API keys, and global LLM settings, all without a server restart.
Full documentation: nexus-gamer/README.md
Nexus Gamer is a lightweight Flask application running at http://localhost:5000, designed to help competitive gamers diagnose their network conditions before queuing for a match.
Core capabilities:
- Real-time speed testing via SSE — Runs a full Speedtest.net test (ping, download, upload) using
speedtest-cliand streams live status frames to the browser at each stage, so the user never sees a blank loading screen. - Dynamic chart generation — After every test, a Matplotlib bar chart (amber/blue/emerald bars on a transparent background) is generated and saved as a UUID-named PNG for cache-busting.
- LLM-powered network analysis — Test results are forwarded via HTTP POST to Nexus AI's
/api/analytics/evaluateendpoint, which uses the configured LLM to generate a concise, themed assessment of the connection quality. If Nexus AI is offline, Nexus Gamer degrades gracefully. - Experimental latency tracker and ML predictor — Two standalone scripts in
nexus-ai/src/provide continuous background ping logging and a Random Forest regression model for predicting expected latency by time of day.
Full documentation: nexus-academic-agent/README.md
The Nexus Academic Agent is a FastAPI service running at http://localhost:8001, designed to assist with academic writing by providing mathematically safe paraphrasing and automated citation generation.
Core capabilities:
- Dual-agent paraphrase loop — Two agents collaborate in a feedback loop. The Transmuter (a Groq LLM) rewrites text with a strict academic tone. The Inspector (Python's
difflib.SequenceMatcher) computes the exact structural similarity ratio between the original and the rewrite — at zero API cost. If the similarity exceeds 75%, the Inspector rejects the output and triggers another Transmuter iteration, up to three times. - Zero-token similarity validation — The Inspector performs no LLM calls. Using the Gestalt Pattern Matching algorithm, it provides deterministic, objective, and instantaneous similarity scoring.
- SSE live terminal streaming — Every step of the agent loop (attempt number, Inspector score, pass/fail decision) is streamed to the browser in real time, giving users full visibility into the AI's internal process.
- Automated web-scraping citation generator — Given a URL, the service uses
httpxandBeautifulSoup4to extract hidden metadata (title, author, publication date, site name) from the page's HTML meta tags. This metadata is then passed to a Groq LLM to generate a perfectly formatted APA, MLA, or IEEE citation.
| Layer | Technology | Version | Used In |
|---|---|---|---|
| Web framework (async) | FastAPI | Latest | nexus-ai, nexus-academic-agent |
| Web framework (sync) | Flask | Latest | nexus-gamer |
| ASGI server | Uvicorn | Latest | nexus-ai, nexus-academic-agent |
| LLM provider (primary) | Groq Cloud API | — | nexus-ai, nexus-academic-agent |
| LLM provider (secondary) | Google Gemini API | — | nexus-ai |
| LLM provider (tertiary) | Pollinations AI | — | nexus-ai |
| Vector database | FAISS (CPU) | Latest | nexus-ai (rag_scholar) |
| Document processing | PyMuPDF (fitz) | Latest | nexus-ai |
| Embedding model | all-MiniLM-L6-v2 | HuggingFace | nexus-ai (rag_scholar) |
| Similarity engine | difflib.SequenceMatcher | stdlib | nexus-academic-agent |
| HTML scraping | BeautifulSoup4 | Latest | nexus-academic-agent |
| Speed testing | speedtest-cli | Latest | nexus-gamer |
| Chart generation | Matplotlib | Latest | nexus-gamer |
| Image processing | Pillow | ≥10.3.0 | nexus-ai, icon build |
| HTTP client (async) | httpx | ≥0.27.0 | nexus-ai, nexus-academic-agent |
| HTTP client (sync) | requests | ≥2.32.0 | nexus-gamer |
| Database | SQLite (stdlib) | 3.x | nexus-ai |
| Environment management | python-dotenv | ≥1.0.0 | All services |
| ML model | scikit-learn (RandomForest) | ≥1.5.0 | nexus-ai (latency_predictor) |
| Frontend | Vanilla HTML + JavaScript | ES6+ | All services |
| Build tool | PyInstaller | ≥6.6.0 | tools/launcher (dev only) |
Microservice independence. Each service owns its own data, its own database file, and its own process. Killing or restarting one service has zero effect on the others. The only runtime dependency is Nexus Gamer's optional HTTP call to Nexus AI for the LLM remark — and even that is wrapped in a try/except block.
Local-first data privacy. No cloud databases. No third-party data storage. All user data, chat histories, uploaded files, vector indexes, and ML models are stored entirely on the local machine.
Fork/Clone data isolation. Every user who forks or clones this repository starts from a completely clean slate. The .gitignore is carefully designed so that no developer's personal data (chat history, user profiles, uploaded files, trained models, FAISS indexes, speed-test charts, SQLite databases, API keys) ever enters version control. Each user's data is generated locally at runtime and stays on their own device only.
Graceful degradation. Every external dependency (LLM APIs, the wttr.in weather service, the Nexus AI remark call from Nexus Gamer) is protected by exception handling. The system never crashes for the user due to an external service failure — it falls back to a safe default.
Zero-restart configuration. API keys, model registries, and system prompts can all be modified at runtime via the Admin Dashboard. Changes take effect immediately without restarting any service.
Progressive UI feedback. All long-running operations (LLM inference, speed tests, paraphrasing loops) stream their progress to the browser via Server-Sent Events. The user is never left staring at a spinner with no feedback.
Full instructions are in the Setup Guide (SETUP.md). The condensed version:
# 1. Create and activate the Conda environment
conda create -n nexus python=3.10 -y
conda activate nexus
# 2. Copy the environment template and fill in your API keys
cp .env.example .env
# Edit .env and paste your GROQ_API_KEY and GEMINI_API_KEY
# 3. Install all dependencies
pip install -r requirements.txt
# 4a. Launch all three services at once (Windows — recommended)
.\start.bat
# 4b. Or use the pre-built Windows x64 launcher executable
# (already committed in the repo — just double-click or run from terminal)
.\NexusLauncher-x64.exe
# 4c. Rebuild the launcher .exe from the current repo state (dev only)
# The icon is read from assets/nexus-launcher.ico (committed, portable)
python .\tools\launcher\build_launcher_exe.py
# 4d. Or launch each service manually (cross-platform)
cd nexus-ai && uvicorn backend.main:app --port 8000 --reload
uvicorn backend.main:app --port 8001 --reload # from nexus-academic-agent/
flask run --port 5000 # from nexus-gamer/| Service | Port | URL |
|---|---|---|
| Nexus AI (Core Engine) | 8000 | http://localhost:8000 |
| Nexus Academic Agent | 8001 | http://localhost:8001 |
| Nexus Gamer Suite | 5000 | http://localhost:5000 |
| Document | Purpose |
|---|---|
| SETUP.md | Complete installation guide: prerequisites, Conda setup, API key configuration, dependency installation, service launch, and troubleshooting |
| GUIDE.md | Comprehensive technical reference: system architecture, all API endpoints, database schemas, security model, frontend architecture, and design decisions |
| nexus-ai/README.md | Nexus AI service: feature breakdown, module descriptions, database schema, and configuration reference |
| nexus-academic-agent/README.md | Academic Agent service: dual-agent architecture, citation generator, SSE protocol, and API reference |
| nexus-gamer/README.md | Nexus Gamer service: speed test internals, chart generation, cross-service communication, and result interpretation |
| CONTRIBUTING.md | Contribution policy, bug report template, issue guidelines, and project roadmap |
| CODE_OF_CONDUCT.md | Community standards and conduct expectations |
| Milestone | Status |
|---|---|
| Nexus AI — Core Chat & Auth | Stable |
| Nexus AI — Scholar Mode (RAG) | Stable |
| Nexus AI — Vision & Multimodal | Stable |
| Nexus AI — Memory Vault | Stable |
| Nexus AI — Admin Dashboard | Stable |
| Nexus AI — Weather Integration | Stable |
| Nexus Gamer — Speed Test Suite | Stable |
| Nexus Gamer — LLM Network Remark | Stable |
| Nexus Academic Agent — Paraphrase Loop | Stable |
| Nexus Academic Agent — Citation Generator | Stable |
| Latency Tracker & ML Predictor | Experimental |
| Portable .exe Icon (nexus-launcher.ico) | ✅ v1.1.0 |
| Portable PyInstaller spec (repo-relative) | ✅ v1.1.0 |
| Pinned requirements.txt | ✅ v1.1.0 |
| Favicon PNG (transparent, all services) | ✅ v1.1.0 |
| Fork/Clone data isolation guarantee | ✅ v1.1.0 |
| Docker Compose Deployment | Planned |
| OAuth2 / Production Auth | Planned |
Nexus AI Workspace — Proternship 2026, GCET