README.md

metadata

title: Agents
emoji: 😻
colorFrom: green
colorTo: yellow
sdk: docker
pinned: false
license: mit
short_description: Local Agents Program

🛰️ NEXUS AI — Elite AI Chat Platform

A state-of-the-art, self-hosted AI chat platform for Hugging Face Spaces running on an NVIDIA A100 instance. Local ultra-fast inference via vLLM, a FastAPI orchestrator, a glassmorphic web UI, a three-tier AI engine, a secure sandbox terminal, live GPU/CPU telemetry, and an AI-powered self-healing log analyzer.

---

✨ Feature Map

Area	Description
⚡ Flash mode	Direct low-latency token streaming from the local model
🧠 Max mode	Deep reasoning pipeline: planning → web research → reasoning → self-reflection → final answer, with visible <thinking> steps
🤖 Agents mode	A swarm of specialized agents (PM, Coder, Debugger, Security, Researcher, Database, UI/UX) collaborating through a routing loop
🗄️ Turso DB	users, chats, messages, memories, system_logs, sandbox_projects, auth_audit
🛡️ Security shield	Master-token auth (HF secret ADMIN_API_KEY) + IP capture + HTML5 GPS audit + JWT sessions; every page is locked
📊 usage.html	Live CPU / RAM (142 GB) / GPU engine / VRAM / token-rate dashboard over WebSocket + Chart.js
🩺 logs.html	AI diagnostic agent that analyzes the rolling log buffer and can apply patches to repair files
💻 console.html	Web-based bash emulator (xterm.js) jailed to the sandbox folder, with pip install support
🎨 UI	Deep dark #0B0F19 palette, backdrop-blur glass panels, neon-cyan glow, fully responsive

---

🔐 Required Space Secrets

Secret	Purpose
ADMIN_API_KEY	Master token that unlocks the platform lockscreen
TURSO_DATABASE_URL	e.g. libsql://your-db.turso.io (optional — falls back to a local embedded database)
TURSO_AUTH_TOKEN	Turso auth token
HF_TOKEN	Only if you serve a gated model (e.g. Llama-3-70B-Instruct)

⚙️ Optional environment variables

Variable	Default	Description
MODEL_NAME	deepseek-ai/DeepSeek-Coder-V2-Lite-Instruct	Any vLLM-compatible model
MAX_MODEL_LEN	32768	Context window served by vLLM
GPU_MEMORY_UTILIZATION	0.90	Fraction of VRAM vLLM may use
MOCK_MODE	auto	1 forces the built-in simulation engine (no GPU needed)
JWT_SECRET	derived	Session-signing secret
SAFE_LAT / SAFE_LON / SAFE_RADIUS_KM	unset	Optional geo-fence for logins
STRICT_GEO	0	1 rejects logins outside the geo-fence
EXTRA_VLLM_ARGS	empty	Extra flags passed to vllm serve

🚀 Local development (CPU only)

pip install -r requirements.txt
MOCK_MODE=1 ADMIN_API_KEY=dev-key uvicorn main:app --port 7860
# open http://127.0.0.1:7860  → enter "dev-key" on the lockscreen

📁 Layout

├── Dockerfile              # CUDA PyTorch base, A100 tuning, vLLM bootstrap
├── entrypoint.sh           # starts vLLM (background) + uvicorn
├── requirements.txt
├── main.py                 # FastAPI orchestrator (engines, auth, DB, WS)
└── static/
    ├── index.html          # main chat UI
    ├── lockscreen.html     # glassmorphic multi-factor lockscreen
    ├── usage.html          # live resource dashboard
    ├── logs.html           # AI log analyzer / self-healing console
    ├── console.html        # web terminal emulator
    ├── style.css           # design system
    └── app.js              # chat application logic