docs/USER_GUIDE.md

# 🧭 User Guide: How the App Works

This application is more than just a simple "Chat with PDF" tool. It is a professional **Knowledge Management System** designed to bridge the gap between your raw data (files) and actionable intelligence (answers).

To use it effectively, you need to understand the three core concepts: **Knowledge Bases**, **Assistants**, and **Chats**.

---

## 1. The Core Concepts (The Hierarchy)

Think of this system like a real-world library, but supercharged with AI:

1.  **📚 Knowledge Base (The Library Shelf):**
    *   **Role:** The Storage Layer.
    *   This is where you store your documents. It handles the "heavy lifting" of converting text into mathematical vectors.
    *   It is *passive*. It doesn't "think"; it just remembers.
    *   *Example:* "Legal Documents", "Personal Journals", "Python Textbooks".

2.  **🤖 Assistant (The Librarian):**
    *   **Role:** The Logic Layer.
    *   This is the "Brain". It has a personality, instructions, and a memory of your conversation.
    *   Crucially, **an Assistant must be assigned to a Knowledge Base**. Without a KB, the Assistant is just a generic chatbot (like standard ChatGPT) with no access to your private data.
    *   *Example:* "Legal Advisor" (linked to Legal Docs), "Coding Tutor" (linked to Python Textbooks).

3.  **💬 Chat (The Conversation):**
    *   **Role:** The Interaction Layer.
    *   This is a specific session between YOU and an ASSISTANT.
    *   You can have multiple chats with the same assistant (e.g., "Session 1: Contract Review", "Session 2: Lease Agreement"). The Assistant remembers the context *within* a chat, but not *across* chats.

---

## 2. The Workflow: Step-by-Step

Follow this flow to build your first RAG application.

### Step 1: Create a Knowledge Base
*   **Action:** Go to the "Knowledge Bases" tab and click "Create New".
*   **Why?** You need a container for your data.
*   **Behind the Scenes:** The system contacts the **Qdrant Vector Database** and creates a new "Collection". Think of this as creating a new, empty bucket specifically designed to hold high-dimensional vectors (numbers).

### Step 2: Ingest Documents
*   **Action:** Open your new Knowledge Base and upload files (PDFs, Text, etc.).
*   **Why?** The system needs to read, understand, and index your content.
*   **What happens (The "Magic"):**
    1.  **Parsing:** The file is cleaned and converted to text (see `PARSING_STRATEGIES.md`).
    2.  **Chunking:** The text is intelligently split into small, meaningful pieces (see `CHUNKING_STRATEGIES.md`).
    3.  **Embedding:** Each piece is run through an AI model to create a "vector" (see `EMBEDDING_MODELS.md`).
    *   *Note:* This process is CPU-intensive. A large PDF might take a minute to process because the AI is reading every sentence carefully.

### Step 3: Create an Assistant
*   **Action:** Go to the "Assistants" tab and click "Create New".
*   **Why?** You need an interface to talk to your data.
*   **Crucial Settings:**
    *   **Knowledge Base:** You MUST link the KB you created in Step 1.
    *   **System Prompt:** This is where you program the AI's behavior.
        *   *Bad Prompt:* "You are a bot."
        *   *Good Prompt:* "You are a senior legal analyst. Answer strictly based on the provided documents. If the answer is not in the text, say 'I don't know'."
    *   **Temperature:** Controls creativity.
        *   `0.0` (Strict): Good for factual Q&A.
        *   `0.7` (Creative): Good for brainstorming or writing.

### Step 4: Start a Chat
*   **Action:** Go to the "Chats" tab, select your "Finance Guru" assistant, and start a new chat.
*   **Why?** To begin the Q&A loop.
*   **The RAG Loop (What actually happens):**
    1.  **Query:** You ask, "What is the refund policy?"
    2.  **Retrieval:** The system pauses, searches your Knowledge Base for the top 5 chunks related to "refunds" (using the strategies in `RETRIEVAL_STRATEGIES.md`).
    3.  **Context Injection:** It secretly pastes those 5 chunks into the prompt, right before your question.
    4.  **Generation:** The LLM reads the chunks and generates an answer based *only* on that information.

---

## 3. Why this Architecture?

Why separate "Assistants" from "Knowledge Bases"? Why not just upload a file and chat?

**1. The Power of Reusability (One-to-Many)**
Imagine you have a huge Knowledge Base called **"Company Financial Reports"** (100+ PDFs). Indexing this takes time and storage. You can create **multiple assistants** that use this *same* data for different purposes:
*   **Assistant A ("The Auditor"):** Strict, low temperature, looks for errors.
*   **Assistant B ("The Summarizer"):** Creative, high temperature, writes blog posts.
*   **Assistant C ("The Historian"):** Focuses on year-over-year trends.
All three use the same expensive vector index.

**2. Data Safety**
If you delete an Assistant (e.g., "The Auditor"), **you do not delete the data**. Your Knowledge Base remains intact. This prevents accidental data loss and allows you to experiment with different Assistant personalities without re-uploading files.