Spaces:
Sleeping
Sleeping
| 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 | |