README.md

metadata

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.

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:

   pip install -r requirements.txt
   playwright install
   

3. Start Ollama (for the Agent):

   ollama serve
   ollama pull kimi-k2.5:cloud
   

4. Run the Application:

   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