🎯 Goal

Make RecursiveMAS accessible to everyone — researchers, students, and curious minds — with no prior technical knowledge required. Clone the repo, fill in two lines in a .env file, run one command, and the full multi-agent reasoning system is up and running in your browser in under 60 seconds.

Tested on: HP OMEN 16 Pro · NVIDIA RTX 5080 · 32 GB RAM · NVMe SSD
Result: all 5 collaboration styles working, GPU inference in seconds, warm model cache between requests.

✨ What's new

🐳 Docker infrastructure

• Dockerfile — GPU-ready image for batch inference (run.py)
• Dockerfile.serve — separate image for the Gradio web UI (serve.py)
• docker-compose.yml — orchestrates both services with a shared hf_cache named volume; reads HF_TOKEN and TAVILY_API_KEY from .env
• .dockerignore — keeps secrets and cache out of the build context

🖥️ Gradio web UI (serve.py)

• Chat interface exposing all 5 collaboration styles via dropdown
• Warm model cache — models are loaded into VRAM on first request and stay resident; no reload between questions
• Style switching evicts the old models and loads the new set automatically
• Sliders for recursive rounds (1–5) and latent steps (8–64)
• Informational note below the style selector: first-use download time, subsequent runs instant from cache
• Compatible with Gradio 6.0 (messages format updated, theme moved to launch())

🩺 Health check (healthcheck.py)

Three-level check to verify the container environment before running inference:

• Level 1 — Python deps + all 5 styles registered (no GPU needed)
• Level 2 — CUDA device detection + tensor allocation
• Level 3 — HuggingFace Hub reachability

🪟 Windows / no-GPU support

• serve-cpu.bat — one double-click to launch the web UI on CPU; reads credentials from .env automatically
• docker-compose.override.yml pattern documented in README with runtime: runc to bypass NVIDIA hook on WSL2 systems without GPU passthrough configured
• WSL2 GPU fix checklist included (driver ≥ 470, wsl --list --verbose, Docker Desktop WSL integration)

🔒 Security

• .gitignore added — .env is never tracked by git
• .env.example provided as a safe template
• All secrets passed at runtime via environment variables, never baked into images

📖 Documentation

• New 🐳 Docker: One-Click Setup section in README covering prerequisites, build, batch inference, web UI launch, health check, and CPU fallback
• Repository structure updated to reflect all new files

🚀 Quickstart (for reviewers)

git clone https://github.com/danielesalpietro/RecursiveMAS.git
cd RecursiveMAS

# Create .env
echo "HF_TOKEN=hf_your_token" > .env
echo "TAVILY_API_KEY=your_key" >> .env

# Build and launch web UI
docker compose build serve
docker compose up serve
# → open http://localhost:7860

No GPU on your machine right now? Create docker-compose.override.yml:

services:
  recursivemas:
    runtime: runc
    deploy: {}
  serve:
    runtime: runc
    deploy: {}

Then docker compose up serve — the UI runs on CPU (slower, but fully functional for exploration).

🗂️ Files changed