Spaces:

Aaryan17
/

MAC

Sleeping

App Files Files Community

Aaryan17 commited on Apr 28

Commit

73c4eaa

verified ·

1 Parent(s): 2959187

fix: sdk=docker, app_port=7860, SQLite+Redis

Browse files

Files changed (1) hide show

README.md +23 -252

README.md CHANGED Viewed

@@ -1,252 +1,23 @@
----
-title: MAC - MBM AI Cloud
-emoji: 🤖
-colorFrom: red
-colorTo: blue
-sdk: static
-pinned: true
-license: mit
----
-<p align="center">
-  <img src="logo.png" alt="MAC — MBM AI Cloud" width="160" />
-</p>
-<h1 align="center">MAC — MBM AI Cloud</h1>
-<p align="center">
-  <strong>Self-hosted AI platform for MBM University Jodhpur.</strong><br/>
-  Private ChatGPT-style chat, Jupyter-style notebooks, RAG over college documents,<br/>
-  face-based attendance, AI exam grading — all running on the college's own GPUs.
-</p>
-<p align="center">
-  <img src="https://img.shields.io/badge/Python-3.11+-3776AB?style=flat-square&logo=python&logoColor=white" />
-  <img src="https://img.shields.io/badge/FastAPI-0.115-009688?style=flat-square&logo=fastapi&logoColor=white" />
-  <img src="https://img.shields.io/badge/SvelteKit-2-FF3E00?style=flat-square&logo=svelte&logoColor=white" />
-  <img src="https://img.shields.io/badge/PostgreSQL-16-4169E1?style=flat-square&logo=postgresql&logoColor=white" />
-  <img src="https://img.shields.io/badge/Redis-7-DC382D?style=flat-square&logo=redis&logoColor=white" />
-  <img src="https://img.shields.io/badge/vLLM-inference-6B4FBB?style=flat-square" />
-  <img src="https://img.shields.io/badge/Docker-Compose-2496ED?style=flat-square&logo=docker&logoColor=white" />
-  <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" />
-</p>
----
-## What is MAC?
-**MAC (MBM AI Cloud)** is a fully on-premise AI platform built for MBM University, Jodhpur. It gives students, faculty, and admins a unified interface for AI-powered tools — with **zero external API calls**. All inference runs locally on the university's GPU cluster via [vLLM](https://github.com/vllm-project/vllm).
-> Think: a private, self-hosted ChatGPT + Jupyter + Google Classroom, built and controlled entirely by the university.
----
-## Features
-| Feature | Description |
-|---|---|
-| **AI Chat** | Streaming chat with open-source LLMs (Qwen, DeepSeek, etc.). Custom system prompts, guardrails, multi-language support (19 Indian languages). |
-| **Notebooks** | Kaggle/Colab-style code execution cells (Python, JS, SQL) backed by Docker kernel containers or remote GPU workers. |
-| **RAG Search** | Upload PDFs and documents; query them with AI-augmented answers. Per-subject collections. |
-| **Attendance** | Face-capture based check-in. Faculty creates session → students selfie-check-in → export CSV/PDF. |
-| **Copy Check** | Upload exam answer sheets; AI grades per-question with marks + feedback; plagiarism detection across submissions. |
-| **Doubts Forum** | Students post questions; AI drafts answers; faculty moderates. |
-| **File Sharing** | Admin/faculty distribute class materials; per-file download analytics. |
-| **API Keys** | Scoped `mac_sk_*` API keys for students to access models from anywhere (OpenAI-compatible endpoint). |
-| **Multi-node Cluster** | GPU worker nodes register via one-time token, send heartbeats every 10 s; master load-balances LLM requests by GPU utilisation. |
-| **Admin Console** | Feature flags, quota overrides, guardrail rules, cluster management, system diagnostics. |
----
-## Architecture
-```
-Browser / API Client
-        │ HTTPS
-        ▼
-      Nginx  (port 80/443)
-        │
-        ├─ /          → SvelteKit PWA (static)
-        └─ /api/v1/*  → FastAPI backend
-                            │
-              ┌─────────────┼──────────────┬────────────┐
-              ▼             ▼              ▼            ▼
-         PostgreSQL       Redis          Qdrant      SearXNG
-         (primary DB)  (JWT blacklist  (RAG vectors)  (web search)
-                        rate limits)
-                             │
-                    load_balancer.get_best_worker()
-                             │
-                    GPU Worker Nodes  (LAN)
-                       └── vLLM  (OpenAI-compatible)
-                       └── worker_agent.py  (heartbeat every 10 s)
-```
-**Routing algorithm:** `gpu_util × 0.5 + vram_ratio × 0.3` — workers stale after 30 s are skipped.
----
-## Repository Layout
-```
-mac/                     FastAPI backend
-  routers/               API route handlers (thin — parse, auth, call service)
-  services/              Business logic (no HTTP types)
-  models/                SQLAlchemy ORM models
-  schemas/               Pydantic request/response schemas
-  middleware/            Auth, rate-limit, feature-gate middleware
-  utils/                 JWT, security helpers
-frontend/                SvelteKit 2 PWA
-  src/routes/            Page components (chat, dashboard, notebooks, rag, …)
-  src/lib/               API client, stores, i18n (19 languages), utils
-alembic/                 Database migration environment + versioned revisions
-installer/               Windows GUI installer (PyInstaller + Tkinter)
-nginx/                   Reverse proxy config (HTTP + HTTPS)
-tests/                   pytest suite
-dist/                    Built installer — MAC-Installer.exe
-docker-compose.yml       Master node deployment stack
-docker-compose.worker.yml  Worker node deployment stack
-worker_agent.py          Worker enrollment + heartbeat agent
-```
----
-## Quick Start
-**Prerequisites:** Docker Desktop, Python 3.11+, Git
-```bash
-git clone https://github.com/mbmuniversity2026/MAC.git
-cd MAC
-cp .env.example .env          # edit DB password, model paths, etc.
-```
-Start all services:
-```bash
-docker compose up -d --build
-```
-Open **http://localhost** — the setup wizard runs on first boot to create the admin account.
-API docs: **http://localhost:8000/docs**
----
-## Adding a GPU Worker Node
-On the **master**, mint an enrollment token:
-```bash
-curl -X POST http://MASTER_IP:8000/api/v1/cluster/enroll-token \
-  -H "Authorization: Bearer ADMIN_JWT" \
-  -d '{"label": "Lab PC 1", "expires_hours": 24}'
-```
-On the **worker PC**, create a `.env` with:
-```env
-MAC_MASTER_URL=http://MASTER_IP:8000
-MAC_ENROLL_TOKEN=<token from above>
-MAC_VLLM_PORT=8001
-```
-Then start the worker stack:
-```bash
-docker compose -f docker-compose.worker.yml up -d
-```
-Approve the node in **Admin → Cluster** tab. The node starts receiving LLM requests immediately.
----
-## Windows Installer
-A standalone GUI installer (`dist/MAC-Installer.exe`) handles everything:
-- Clones the repo, configures `.env`, sets a static IP on the network adapter, starts all Docker services.
-To rebuild it:
-```powershell
-powershell -ExecutionPolicy Bypass -File .\installer\build_installer.ps1
-```
----
-## Tech Stack
-| Layer | Technology |
-|---|---|
-| Backend API | FastAPI 0.115, Python 3.11+ |
-| Database | PostgreSQL 16 + Alembic |
-| Cache / Rate-limit / Blacklist | Redis 7 |
-| LLM inference | vLLM (OpenAI-compatible, GPU) |
-| Vector DB | Qdrant |
-| Web search | SearXNG |
-| Frontend | SvelteKit 2 + Svelte 5 + Tailwind CSS 3 + Vite 6 |
-| Reverse proxy | Nginx |
-| Containerisation | Docker Compose |
-| Installer | PyInstaller (Windows) |
----
-## Documentation
-| Document | Description |
-|---|---|
-| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Full architecture, subsystem deep-dives, deployment guide |
-| [docs/MAC-CONTEXT.md](docs/MAC-CONTEXT.md) | Complete agent context — stack, auth, routing, design decisions |
-| [docs/MAC-PROGRESS.md](docs/MAC-PROGRESS.md) | Build progress log and roadmap |
----
-## License
-MIT © MBM University Jodhpur
-Environment flags:
-- MAC_MODEL_AUTO_DOWNLOAD_ON_USE=true
-- MAC_MODEL_AUTO_DOWNLOAD_LIMIT=0
-This enables background pulling for configured open-source repositories when API usage begins.
-## Testing
-Run full tests:
-```bash
-pytest
-```
-Run CPU-safe subset (no GPU-specific tests):
-```bash
-pytest -k "not gpu"
-```
-## Windows Installer
-Build the standalone installer executable:
-```powershell
-powershell -ExecutionPolicy Bypass -File .\installer\build_installer.ps1
-```
-Output artifact:
-- dist/MAC-Installer.exe
-The installer uses embedded base64 branding assets from installer/embedded_assets.py so branding is retained even if source image files are unavailable during runtime.
-## Security and Operations Notes
-- Keep .env secrets private and never commit credentials.
-- PostgreSQL is the canonical datastore in deployment.
-- Apply migrations via Alembic before serving traffic.
-- Use scoped API keys for automation instead of sharing admin JWTs.
-## License
-Internal/Institutional project repository.

+---
+title: MAC - MBM AI Cloud
+emoji: 🤖
+colorFrom: red
+colorTo: blue
+sdk: docker
+app_port: 7860
+pinned: true
+license: mit
+---
+<p align="center">
+  <img src="logo.png" alt="MAC" width="120" />
+</p>
+<h1 align="center">MAC — MBM AI Cloud</h1>
+<p align="center">Self-hosted AI platform for MBM University Jodhpur</p>
+> This Space runs the full MAC backend (FastAPI + SQLite + Redis) live on Docker.
+> Source code & full deployment guide: https://github.com/mbmuniversity2026/MAC
+**Default admin login:** `admin@mbm.ac.in` / `Admin@1234`
+(seeded automatically on first boot)