docs: expand README with a comprehensive project overview and feat: implement dynamic headless mode for the Playwright browser based on environment.

README.md

@@ -7,4 +7,72 @@ sdk: docker
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# NPS-ChatAgentBot (NPS-AI)
+
+Welcome to the **NPS-ChatAgentBot** repository! This project (also referred to as GNDU Assistant) is a comprehensive AI solution combining a **Retrieval-Augmented Generation (RAG) Chatbot** and an **Autonomous Web Browser Agent**. It is built using Python, FastAPI, LangChain, and state-of-the-art Large Language Models (LLMs) like Mistral AI and local Ollama models.
+
+## 🌟 Key Features
+
+1. **RAG-Powered Chatbot**:
+   - Uses the **Mistral AI API** to answer queries accurately based on uploaded documents (PDF, DOCX, TXT, MD).
+   - Custom `EnsembleRetriever` combining Scikit-Learn's TF-IDF for keyword matching and FAISS for semantic similarity (using HuggingFace embeddings).
+   - **Multi-language Support**: Automatically translates non-English queries to English for internal processing, and translates the generated answer back to the user's language using Mistral.
+
+2. **Autonomous Web Browser Agent**:
+   - Uses an autonomous web browsing framework (integrated via `nps_agent.py`) to search the web, navigate pages, and extract information.
+   - Powered by a local **Ollama** LLM (default model: `kimi-k2.5:cloud`), ensuring privacy and saving API costs.
+   - The agent is accessible via a dedicated `/agent/run` endpoint or via a standalone script.
+
+3. **FastAPI Backend & Frontend Integration**:
+   - Modern, fast, and robust backend using **FastAPI**.
+   - Includes an admin API (`/admin/files`) for managing documents (upload/delete files with HTTP Basic Auth).
+   - Serves static files for the frontend user interface.
+
+4. **Hugging Face Spaces Ready**:
+   - Contains configuration (`Dockerfile`, YAML frontmatter) for seamless deployment on Hugging Face Spaces.
+   - Intelligent data handling: Uses `/data` persistent storage on HF Spaces while defaulting to a local `data` folder during local development.
+
+## 🏗️ Project Architecture
+
+- `app.py`: The main entry point for the FastAPI server. Features the `/ask` endpoint (for RAG/Agent/Chat), document processing, initialization of the vector store, translation wrappers, and admin routes.
+- `mistral.py`: A standalone alternative or legacy iteration emphasizing the Mistral-based RAG logic without full agent integration.
+- `nps_agent.py`: Contains the logic for the Autonomous Browser Agent, communicating with a local Ollama instance to perform multi-step web navigation tasks.
+- `STARTUP.md`: A step-by-step guide to setting up and running the application, including environment setup and starting local servers.
+- `AGENTS.md`: Instructions and behavioral guidelines governing the browsing agent's deep-research flow.
+- `/data`: Directory storing the knowledge base files.
+- `/frontend`: Contains the static web files (HTML, CSS, JS) forming the UI.
+
+## 🚀 Getting Started
+
+If you want to run this project locally, follow the detailed setup guide in [`STARTUP.md`](./STARTUP.md).
+
+Here's the quick summary:
+
+1. **Clone & Env Setup**: 
+   Ensure you have a `.env` file containing your `MISTRAL_API_KEY`, `ADMIN_USERNAME`, and `ADMIN_PASSWORD`.
+2. **Install Requirements**:
+   ```bash
+   pip install -r requirements.txt
+   playwright install
+   ```
+3. **Start Ollama** (for the Agent):
+   ```bash
+   ollama serve
+   ollama pull kimi-k2.5:cloud
+   ```
+4. **Run the Application**:
+   ```bash
+   python app.py
+   ```
+   *Access the Web UI at http://localhost:7860.*
+
+## 📖 How to Use
+
+- **Chatbot**: Submit queries via the Web UI. If you ask about details contained in the `/data` folder, the bot will synthesize an answer and cite the source pages.
+- **Agent Mode**: Select "agent" mode or send a request to `/agent/run` with a specific `task` (e.g., "Find the latest news about AI"). The backend invokes the browser agent to complete the task and return the result.
+- **Document Management**: Use the secure endpoints under `/admin` to upload or delete PDFs dynamically without restarting the server.
+
+## 🛠️ Configuration Details
+
+Hugging Face Spaces config blocks the top of this `README.md`.
+For full configuration parameters, check https://huggingface.co/docs/hub/spaces-config-reference

nps_agent.py

@@ -66,9 +66,15 @@ class PlaywrightTool(Tool):
     async def _ensure_initialized(self):
         if not self._initialized:
             self._playwright = await async_playwright().start()
+            
+            # Auto-detect HF Spaces or allow HEADLESS env var override
+            is_spaces = "SPACE_ID" in os.environ
+            default_headless = "true" if is_spaces else "false"
+            is_headless = os.getenv("HEADLESS", default_headless).lower() == "true"
+
             # Launch with anti-detection args
             self._browser = await self._playwright.chromium.launch(
-                headless=False,
+                headless=is_headless,
                 args=[
                     "--no-sandbox",
                     "--disable-blink-features=AutomationControlled",