Skip to main content
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

PDF

Standard PDF documents. Text is extracted automatically — scanned image-only PDFs without embedded text are not supported.

TXT

Plain text files. Any .txt file with readable content is fully supported.

DOCX

Microsoft Word documents (.docx format). Legacy .doc files are not supported.

​
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).
1

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).
2

Go to Knowledge Base

Select the Knowledge Base section from the admin sidebar.
3

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.
The maximum upload size defaults to 200 MB and is controlled by the KB_MAX_UPLOAD_MB environment variable in your .env file.
4

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.

​
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.
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.
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.

​
How Documents Are Processed

Understanding how SAFIA processes your files helps you get the best retrieval quality.
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.
The extracted text is split into overlapping chunks for search. Default settings: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.
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.
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.

​
Configuration Reference

​
Limitations

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.