> ## Documentation Index
> Fetch the complete documentation index at: https://safia.maximusolution.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge Base — Document-Grounded Answers in SAFIA

> Upload PDF, TXT, or DOCX files via the admin dashboard so SAFIA can answer user questions grounded in your own documents and policies.

The Knowledge Base lets administrators upload internal documents — company financial policies, investment guides, product FAQs, or any reference material — and have SAFIA answer user questions using the content of those files. When a user asks something covered by an uploaded document, SAFIA searches the knowledge base first and grounds its reply in the actual text, citing the source naturally in the response.

This is particularly useful for organisations deploying SAFIA to their employees or customers: you can upload your own investment policy, expense reimbursement guide, or financial product documentation once, and SAFIA will answer questions about it accurately without requiring users to read the files themselves.

***

## Supported File Formats

<CardGroup cols={3}>
  <Card title="PDF" icon="file-pdf">
    Standard PDF documents. Text is extracted automatically — scanned image-only PDFs without embedded text are not supported.
  </Card>

  <Card title="TXT" icon="file-lines">
    Plain text files. Any `.txt` file with readable content is fully supported.
  </Card>

  <Card title="DOCX" icon="file-word">
    Microsoft Word documents (`.docx` format). Legacy `.doc` files are not supported.
  </Card>
</CardGroup>

***

## Uploading Documents

Only administrators can upload documents to the knowledge base. Uploads are managed through the **Admin Dashboard** — a local web interface served at `http://127.0.0.1:5454` (available after running `safia start`).

<Steps>
  <Step title="Open the Admin Dashboard">
    Navigate to `http://127.0.0.1:5454` in your browser and log in with your admin credentials (`ADMIN_USERNAME` and `ADMIN_PASSWORD` from your `.env` file).
  </Step>

  <Step title="Go to Knowledge Base">
    Select the **Knowledge Base** section from the admin sidebar.
  </Step>

  <Step title="Upload a file">
    Click **Upload Document**, choose your PDF, TXT, or DOCX file, optionally add a display title, and confirm. SAFIA will extract the text, split it into chunks, generate embeddings locally, and store everything in Qdrant.

    <Note>
      The maximum upload size defaults to **200 MB** and is controlled by the `KB_MAX_UPLOAD_MB` environment variable in your `.env` file.
    </Note>
  </Step>

  <Step title="Confirm indexing">
    Once upload completes, the dashboard shows the document status as **ready** and displays the number of chunks indexed. The document is immediately searchable by users.
  </Step>
</Steps>

***

## How SAFIA Answers Questions from Documents

When a user asks a question, SAFIA automatically checks the knowledge base to see if any uploaded document is relevant before answering. If a match is found, SAFIA uses that content to ground its reply.

```text theme={null}
You:    Berapa batas pengeluaran entertainment yang bisa di-reimburse?

SAFIA:  Berdasarkan kebijakan perusahaan (Panduan Keuangan Karyawan 2024),
        batas reimburse hiburan klien adalah Rp 1.500.000 per acara,
        dengan persetujuan manajer untuk pengeluaran di atas Rp 750.000.
        Bukti transaksi wajib dilampirkan dalam 7 hari kerja.
```

```text theme={null}
You:    What does our investment policy say about crypto allocation?

SAFIA:  According to the Investment Policy Statement (uploaded March 2024),
        the maximum allocation to crypto assets is capped at 10% of total
        investable assets. Direct purchases of individual tokens are
        permitted only through OJK-registered exchanges.
```

SAFIA cites the document source naturally in its reply — users always know when an answer comes from an uploaded file versus SAFIA's general knowledge.

<Tip>
  The knowledge base is designed for internal documents and policies, not live market data. For real-time prices, news, or portfolio values, SAFIA uses its dedicated market data tools instead.
</Tip>

***

## How Documents Are Processed

Understanding how SAFIA processes your files helps you get the best retrieval quality.

<Accordion title="Text extraction">
  When you upload a file, SAFIA extracts all readable text from the document. For PDFs, this requires the PDF to have embedded text (not just scanned images). DOCX files are parsed directly from the Word XML structure. TXT files are read as-is.
</Accordion>

<Accordion title="Chunking">
  The extracted text is split into overlapping chunks for search. Default settings:

  | Setting       | Default   | Environment variable     |
  | ------------- | --------- | ------------------------ |
  | Chunk size    | 450 words | `KB_CHUNK_WORDS`         |
  | Chunk overlap | 70 words  | `KB_CHUNK_OVERLAP_WORDS` |

  The 70-word overlap ensures that sentences spanning chunk boundaries are still found by search queries. You can tune both values in your `.env` file.
</Accordion>

<Accordion title="Embeddings (local)">
  Each chunk is converted into a vector embedding using a **local ONNX model** (`paraphrase-multilingual-MiniLM-L12-v2`, \~120 MB) that runs entirely on your server's CPU. No text is sent to an external embedding API by default. To switch to a remote embedding provider, set `EMBEDDING_LOCAL=false` and configure `EMBEDDING_BASE_URL`, `EMBEDDING_API_KEY`, and `EMBEDDING_MODEL` in your `.env`.
</Accordion>

<Accordion title="Vector storage (Qdrant)">
  Embeddings are stored in **Qdrant**, a local on-disk vector database (`data/qdrant/`). No separate Qdrant server or Docker container is required by default. When a user asks a question, SAFIA embeds the query and performs a vector similarity search to find the most relevant chunks, then passes them to the LLM as context for a grounded reply.

  To use a remote Qdrant instance, set `QDRANT_URL` in your `.env`.
</Accordion>

***

## Configuration Reference

| Variable                 | Default           | Description                                  |
| ------------------------ | ----------------- | -------------------------------------------- |
| `KB_MAX_UPLOAD_MB`       | `200`             | Maximum file size allowed for uploads (MB)   |
| `KB_CHUNK_WORDS`         | `450`             | Words per document chunk                     |
| `KB_CHUNK_OVERLAP_WORDS` | `70`              | Overlap words between consecutive chunks     |
| `KB_UPLOAD_DIR`          | *(set in config)* | Directory where uploaded files are stored    |
| `QDRANT_URL`             | Local on-disk     | Remote Qdrant URL (optional)                 |
| `EMBEDDING_LOCAL`        | `true`            | Set to `false` to use a remote embedding API |

***

## Limitations

<Warning>
  Keep the following constraints in mind when using the knowledge base:

  * **Scanned PDFs** (image-only, no embedded text) cannot be processed. Use OCR software to convert them to searchable PDFs first.
  * **File size** is limited by `KB_MAX_UPLOAD_MB`. Very large documents should be split before uploading.
  * **Retrieval quality** depends on chunking. If answers feel incomplete, try splitting large documents into smaller, topic-focused files.
  * The knowledge base answers questions from **static uploaded content only** — it cannot browse the web or access live market data.
  * Only **administrators** can add or remove documents. End users interact with the knowledge base only through chat questions.
</Warning>