docs: refresh README for ModUI; Groq-focused, quick start, and scope

README.md

@@ -1,142 +1,188 @@
 
----
-
-# 💻 Deepshell UI
+# 💻 DeepShell ModUI
 
 ![Python](https://img.shields.io/badge/python-3.9+-blue.svg)
 ![FastAPI](https://img.shields.io/badge/FastAPI-async-green.svg)
 ![License](https://img.shields.io/badge/license-MIT-purple.svg)
-[![Release](https://img.shields.io/github/v/release/muralipala1504/deepshell-ui)](https://github.com/muralipala1504/deepshell-ui/releases)
 
-_A lightweight web UI for the **Deepshell** AI Shell Assistant._
+A lightweight web UI + backend for DeepShell — an infra‑only assistant for Linux SysAdmin, DevOps, IaC, Cloud, and Linux scripting tasks.
+
+DeepShell intentionally rejects out‑of‑domain queries. It focuses on actionable commands, troubleshooting steps, automation snippets, and config examples for real‑world ops.
 
 ---
 
-## 🚀 What is Deepshell UI?
+## 🚀 What is DeepShell ModUI?
 
-Deepshell‑UI is a **domain‑focused Infra & DevOps AI assistant**, built for  
-**Linux Sysadmins, DevOps Engineers, Cloud Engineers, and IaC Specialists**.  
+DeepShell ModUI is a minimal, fast web application:
+- Frontend: a clean chat interface served by the backend itself
+- Backend: FastAPI service with pluggable LLM client (default: Groq) and guardrails
 
-Unlike generic chatbots or wrappers, **it rejects out‑of‑domain queries** (trivia, poems, recipes, etc.) and focuses only on delivering **copy‑ready Linux, Cloud, and IaC commands/scripts**.
+Current default mode is “hard‑block” (demo/safe mode): any prompt returns an admin‑only scope message. This keeps the UI responsive while preventing unintended LLM usage. You can re‑enable LLM calls later with a one‑line change in deepshell-backend/deepshell/main.py.
 
 ---
 
 ## ✨ Features
 
-- Intuitive **chat‑style interface**
-- Syntax‑highlighted outputs with **Copy‑to‑Clipboard**
-- Rejects irrelevant/non‑infra prompts → **no nonsense answers**
-- Clean & responsive layout with scrollable responses
-- Seamless integration with the **Deepshell backend API**
+- Simple, single‑page chat UI
+- FastAPI backend serves UI assets (index.html, app.js, CSS)
+- Health/readiness endpoint
+- Polite block message for non‑admin use cases
+- Ready to wire Groq LLM for infra answers (opt‑in)
+- Works locally or over LAN
 
 ---
 
 ## 🛠️ Tech Stack
 
-- **Frontend**: HTML, CSS, Vanilla JS, Prism.js  
-- **Backend**: FastAPI, Uvicorn, Typer, OpenAI (LiteLLM), psutil, Rich  
-- **Other**: YAML for config, Python 3.9+
+- Frontend: HTML, CSS, Vanilla JS
+- Backend: FastAPI, Uvicorn
+- LLM Client: Groq (via deepshell-backend/deepshell/llm.py)
+- Python: 3.9+
 
 ---
 
 ## 🖼️ Preview
 
-![Deepshell UI Screenshot](docs/screenshot.png)  
-*Example: Infra‑only assistant → rejects capital‑cities, delivers `df -h` instantly*
+Example screen (demo mode blocks general trivia; encourages admin/DevOps prompts).
+
+![DeepShell UI Screenshot](docs/screenshot.png)
 
 ---
 
-## ⚡ Getting Started
+## ⚡ Quick Start
 
-### Prerequisites
-- Python **3.9+**
+Prerequisites
+- Python 3.9+
 - Git
-- OpenAI API Key (required for backend AI calls)
-
-### Installation
+- Network: open TCP 8001 if accessing from another machine
 
-```bash
-git clone https://github.com/muralipala1504/deepshell-ui.git
-cd deepshell-ui
-```
+Clone and install
 
 ```bash
+git clone https://github.com/muralipala1504/deepshell_modui.git
+cd deepshell_modui
 
+# Install backend deps and package
 pip install -r deepshell-backend/requirements.txt
 pip install -e deepshell-backend/
 
-```
-
-Set your OpenAI API key:
-
-Linux/macOS
+Run the app
 
 ```bash
-export OPENAI_API_KEY="your_openai_api_key_here"
-```
 
-Windows PowerShell
+python run_deepshell.py
 
-```pshell
+```
 
-$env:OPENAI_API_KEY="your_openai_api_key_here"
+Open in your browser
 
-```
+    Local: http://localhost:8001
+    Remote/LAN: http://:8001
 
-⚡ Firewall Config (Linux only):
+Linux firewall (if remote access needed)
 
 ```bash
+
 sudo firewall-cmd --add-port=8001/tcp --permanent
 sudo firewall-cmd --reload
 
 ```
 
-Run the backend:
+Stop
+
+    Ctrl + C in the terminal that’s running the server.
+
+
+🔌 LLM Provider: Groq (optional)
+
+By default, the app is in “hard‑block” mode and does not call any LLM. When you’re ready to enable responses:
+
+    Set your Groq API key in the environment
+
+    Linux/macOS:
+
 
 ```bash
 
-python run_deepshell.py > deepshell.log 2>&1 &
+export GROQ_API_KEY="your_groq_api_key"
 
 ```
 
-Now open in browser:
+    Windows PowerShell
 
-```bash
+```pshell
 
-http://localhost:8001
+$env:GROQ_API_KEY="your_groq_api_key"
 
 ```
 
-👉 If remote, replace localhost with your server IP.
+	Enable LLM in the backend
 
-🛑 To stop server: hit Ctrl + C in terminal.
+    	Edit deepshell-backend/deepshell/main.py
+    	In run_agent(), replace the hard‑block return with the provided LLM call        (commented in the file).
+    
+	Restart the server.
 
+	The LLM client code lives in:
 
-🤝 Contributing
+    	deepshell-backend/deepshell/llm.py (get_global_client / provider wiring)
 
-Open issues, submit PRs — contributions welcome!
-Help shape the future of Deepshell 🚀
 
+🔧 Project Layout
 
-🤖 AI Assistance
+deepshell_modui/  
+├── app.js                         # Frontend script  
+├── index.html                     # Frontend page  
+├── services.css                   # Styling  
+├── run_deepshell.py               # Convenience launcher  
+├── deepshell-backend/  
+│   ├── deepshell/  
+│   │   ├── __init__.py  
+│   │   ├── main.py               # FastAPI app (entrypoint)  
+│   │   ├── __main__.py           # Shim: python -m deepshell → main.main()  
+│   │   ├── llm.py                # LLM provider wiring (Groq)  
+│   │   ├── handlers/             # Routers/handlers (extensible)  
+│   │   └── utils.py              # Helpers  
+│   ├── requirements.txt  
+│   └── setup.py  
+└── docs/  
+    └── screenshot.png  
 
-This project was developed with help from AI models (OpenAI GPT, Gemini 2.5 Flash) for code, debugging, and docs.
-🛠️ All code has been reviewed, hardened, and validated by the maintainer.
+How to run (alternatives)
 
+    python run_deepshell.py
+    python -m deepshell # via main shim
+    python -m deepshell.main
+    uvicorn deepshell.main:app --host 0.0.0.0 --port 8001
 
-📜 License
 
-MIT Licensed. See LICENSE for details.
+🔒 Scope and Guardrails
+
+DeepShell is for:
+
+    Linux SysAdmin commands and troubleshooting
+    DevOps tooling (Docker, Kubernetes, Helm, etc.)
+    IaC (Terraform, Ansible, CloudFormation)
+    Cloud CLIs and services (AWS/GCP/Azure)
+    Bash/Python scripting for ops
+
+Out‑of‑scope prompts are politely declined.
+
 
 🛣️ Roadmap
 
-    🌙 Dark mode theme
-    💾 Persistent chat history
-    📂 Save/export responses to file
-    ⚡ Multi‑LLM backend (OpenAI, Anthropic, Local LLMs)
-    🔄 Clear/reset chat sessions
-    🛠️ More infra helpers (Cloud CLI, Ansible, Terraform, etc.)
+    Optional “allow‑list” mode for infra keywords
+    Persistent chat history
+    Export responses
+    More helper modules (cloud/infra recipes)
+    Multi‑LLM support via provider switch
 
-⭐ Star this repo if you find it useful!
 
----
+🤝 Contributing
+
+Issues and PRs are welcome. Please keep contributions focused on infra/DevOps/IaC use cases and simple, maintainable code.
+
+
+📜 License
+
+MIT. See LICENSE for details.