Blame for README.md

---
title: NPS-AI
emoji: 👀
colorFrom: indigo
colorTo: yellow
sdk: docker
pinned: false
---

# 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