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

# SAFIA FAQ: Common Setup, Privacy and Usage Questions

> Answers to the most common questions about SAFIA — setup, privacy, supported providers, languages, data storage, and day-to-day usage limits.

This page answers the questions that come up most often when setting up and using SAFIA. Topics range from initial configuration and LLM provider choices to privacy, multi-user support, and data management. If you don't find your answer here, run `safia logs` to inspect runtime errors, or consult the [Troubleshooting](/troubleshooting) page for step-by-step diagnostics.

***

## Usage & Limits

<AccordionGroup>
  <Accordion title="How many messages can I send per day?">
    By default, each Telegram user can send **1000 messages per day**. The counter resets at **UTC midnight** and applies equally to text messages, voice messages, and photo scans — each counts as one message.

    If you host SAFIA yourself and need a higher limit, open your `.env` file and set:

    ```text theme={null}
    DAILY_MESSAGE_LIMIT=2000
    ```

    Then restart SAFIA:

    ```bash theme={null}
    safia restart
    ```

    You can set the limit as high as you like — there is no enforced maximum on the server side.
  </Accordion>

  <Accordion title="Can I use SAFIA in English?">
    Yes. SAFIA detects the language of your message and responds in the same language. While the bot's personality and default financial context (e.g. IDR prices, Indonesian markets) are tuned for Indonesian users, you can converse naturally in English and receive English replies.
  </Accordion>

  <Accordion title="What currencies does SAFIA support?">
    SAFIA's primary currency is **Indonesian Rupiah (IDR)**. It also supports **USD → IDR conversion** using live exchange rates refreshed every hour. Gold and silver prices are returned in IDR by default.

    If you need broader multi-currency support, you can ask SAFIA about exchange rates for other currency pairs — it will attempt to retrieve them — but IDR is the core reference currency for expense tracking and portfolio calculations.
  </Accordion>
</AccordionGroup>

***

## Setup & Requirements

<AccordionGroup>
  <Accordion title="How do I get a Telegram bot token?">
    You create a bot and receive a token through [@BotFather](https://t.me/BotFather) on Telegram:

    <Steps>
      <Step title="Open BotFather">
        Search for `@BotFather` in Telegram and start a conversation.
      </Step>

      <Step title="Create a new bot">
        Send `/newbot` and follow the prompts — you'll choose a display name and a username (must end in `bot`).
      </Step>

      <Step title="Copy your token">
        BotFather will send a token that looks like `123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ`. Copy it into the `TELEGRAM_BOT_TOKEN` field when you run `safia setup`.
      </Step>
    </Steps>

    Keep your token private — anyone who has it can control your bot.
  </Accordion>

  <Accordion title="What LLM providers does SAFIA support?">
    SAFIA supports four provider options, set via `LLM_PROVIDER` in your `.env`:

    | Provider   | `LLM_PROVIDER` value | Notes                                                          |
    | ---------- | -------------------- | -------------------------------------------------------------- |
    | **Lunos**  | `lunos`              | Default. Routes to `https://api.lunosrouter.com/v1`            |
    | **Groq**   | `groq`               | Routes to `https://api.groq.com/openai/v1`                     |
    | **OpenAI** | `openai`             | Routes to `https://api.openai.com/v1`                          |
    | **Custom** | `custom`             | Any OpenAI-compatible API; set `LLM_BASE_URL` to your endpoint |

    Set the corresponding key in `LLM_API_KEY`. For custom providers, also set `LLM_BASE_URL` and choose an appropriate `LLM_MODEL` name.

    <Note>
      **Voice transcription always requires a separate `GROQ_API_KEY`**, regardless of which provider you choose for chat. SAFIA uses Whisper via the Groq API for speech-to-text and there is currently no alternative backend for this feature.
    </Note>
  </Accordion>

  <Accordion title="What is Lunos?">
    Lunos is the **default LLM provider** for SAFIA, accessed at `https://api.lunosrouter.com/v1`. It is an LLM routing service that exposes an OpenAI-compatible API, allowing SAFIA to use a range of models without you needing accounts at multiple providers.

    When you run `safia setup` and don't specify a different provider, SAFIA configures itself to use Lunos automatically. You can switch to Groq, OpenAI, or any custom OpenAI-compatible provider at any time by updating `LLM_PROVIDER` and `LLM_API_KEY` in your `.env` and restarting.
  </Accordion>
</AccordionGroup>

***

## Privacy & Data

<AccordionGroup>
  <Accordion title="Is my financial data private?">
    Yes. SAFIA is **local-first** — your data never leaves your machine unless you explicitly configure a remote service. Here's where each component runs:

    | Component                          | Location                                                     |
    | ---------------------------------- | ------------------------------------------------------------ |
    | Expense & investment records       | Local SQLite (or your own PostgreSQL)                        |
    | Chat history                       | Local in-memory cache, persisted to SQLite (`CACHE_DB_PATH`) |
    | Vector embeddings (knowledge base) | Local Qdrant on-disk storage                                 |
    | Embedding model                    | Local ONNX file, runs on CPU                                 |

    The only data that travels to external services is the content of your chat messages, which is sent to your chosen LLM API (Lunos, Groq, OpenAI, or custom) to generate responses — the same as any AI chat assistant. Market data (gold prices, crypto rates, etc.) is fetched from public APIs.

    <Tip>
      If you want to minimise data sent externally, you can self-host a compatible LLM and point `LLM_BASE_URL` at your local server using the `custom` provider option.
    </Tip>
  </Accordion>

  <Accordion title="Can multiple users share one SAFIA instance?">
    Yes. SAFIA maintains **per-user records** keyed to each person's Telegram user ID. Expenses, debts, investments, reminders, and chat history are all stored separately for each user — one SAFIA instance can serve a family or small team without mixing data between accounts.

    By default, any Telegram user who messages the bot can use it. If you want to restrict access, enable the allowlist in the admin dashboard at [http://127.0.0.1:5454](http://127.0.0.1:5454) and add each approved user ID.

    <Note>
      The daily message limit (default 1000) applies **per user**, not per instance. Each user has their own independent counter.
    </Note>
  </Accordion>

  <Accordion title="How do I back up my data?">
    SAFIA's database is a single SQLite file. Back it up by copying:

    ```text theme={null}
    data/safia.db
    ```

    For example:

    ```bash theme={null}
    cp data/safia.db ~/backups/safia-$(date +%Y%m%d).db
    ```

    If you've switched to PostgreSQL, use `pg_dump` to back up that database instead. The local Qdrant vector index is stored at `data/qdrant/` — include this directory if you also want to preserve your knowledge base embeddings.

    <Tip>
      Stop SAFIA before copying the SQLite file to avoid backing up a partially written state: `safia stop && cp data/safia.db ~/backups/safia.db && safia start`.
    </Tip>
  </Accordion>

  <Accordion title="Can I use PostgreSQL instead of SQLite?">
    Yes. SQLite is the default (zero configuration required), but SAFIA fully supports PostgreSQL for production or multi-user deployments that need better concurrency.

    Set `DATABASE_URL` in your `.env` to your PostgreSQL connection string:

    ```text theme={null}
    DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/safia
    ```

    Then restart SAFIA:

    ```bash theme={null}
    safia restart
    ```

    SAFIA creates the required tables automatically on first startup. Make sure the target database already exists before starting.
  </Accordion>
</AccordionGroup>

***

## Features & Capabilities

<AccordionGroup>
  <Accordion title="What file types can I upload to the knowledge base?">
    The admin dashboard's knowledge base accepts three file types:

    * **PDF** (`.pdf`) — financial statements, policy documents, reports
    * **Plain text** (`.txt`) — notes, custom rules, raw data exports
    * **Word documents** (`.docx`) — formatted documents from Microsoft Word or compatible editors

    Files are chunked into overlapping segments (default: 450 words per chunk, 70-word overlap), embedded using the local ONNX model, and stored in the on-disk Qdrant vector index. The maximum upload size is **200 MB** per file by default, configurable via `KB_MAX_UPLOAD_MB` in `.env`.

    Once uploaded, SAFIA automatically retrieves relevant passages from the knowledge base to ground its responses — no extra commands needed.
  </Accordion>

  <Accordion title="How do I update SAFIA to the latest version?">
    Run the built-in update command:

    ```bash theme={null}
    safia update
    ```

    This pulls the latest code from GitHub, updates Python dependencies, and restarts the daemons automatically. Your `.env` configuration and data files are preserved.

    <Note>
      If the update introduces changes to the database schema, SAFIA runs any required migrations on the next startup. Always back up `data/safia.db` before a major update.
    </Note>
  </Accordion>

  <Accordion title="Does SAFIA support voice messages?">
    Yes. Send a voice message to the bot and SAFIA transcribes it using **Whisper via the Groq API**, then processes the transcribed text as a normal message. The transcription step requires a valid `GROQ_API_KEY` in your `.env` — this key is free to obtain from [console.groq.com](https://console.groq.com) and is required even if you use a different provider for chat.

    Voice messages count toward your daily message limit (1000 by default) the same as text messages.
  </Accordion>

  <Accordion title="Does SAFIA support receipt and document scanning?">
    Yes. Send a clear photo of a receipt, payslip, or invoice and SAFIA will extract the content using your configured vision model, identify the final amount (net salary, total after discounts, etc.), and prompt you to record the transaction.

    Photo scanning requires a valid `LLM_API_KEY`. The vision model defaults to `mistralai/mistral-small-3.2-24b-instruct` and can be changed via the `VISION_MODEL` setting in `.env`.

    For best results:

    * Make sure the document is well-lit and fully in frame.
    * Avoid steep angles or heavy shadows.
    * Use the highest camera resolution your device supports.
  </Accordion>
</AccordionGroup>