Configuration
=============

Configuration lives inside your folder at ``.folderbot/config.toml``.

Run ``folderbot init`` from your folder to create it interactively.

Basic Configuration
-------------------

.. code-block:: toml

   telegram_token = "YOUR_TELEGRAM_BOT_TOKEN"
   anthropic_api_key = "YOUR_API_KEY"  # Or set FOLDERBOT_API_KEY env var
   allowed_user_ids = [123456789]  # Your Telegram user ID

   # root_folder is implicit — the parent of .folderbot/
   model = "anthropic/claude-sonnet-4-20250514"  # or openai/gpt-4o, etc.

Required Fields
^^^^^^^^^^^^^^^

``telegram_token``
   Your Telegram bot token from `@BotFather <https://t.me/BotFather>`_.

``allowed_user_ids``
   List of Telegram user IDs allowed to use the bot.
   Get yours from `@userinfobot <https://t.me/userinfobot>`_.

Optional Fields
^^^^^^^^^^^^^^^

``root_folder``
   Path to the folder the bot has access to. Defaults to the parent of ``.folderbot/``.
   Only needed if you want to override this default.

``api_key``
   Your LLM provider API key. Can also be set via ``FOLDERBOT_API_KEY`` env var
   or the provider's own env var (e.g., ``ANTHROPIC_API_KEY``, ``OPENAI_API_KEY``).
   Optional if the provider's env var is already set.

``model``
   The LLM model to use. Format: ``provider/model-name``.
   Default: ``anthropic/claude-sonnet-4-20250514``.

``user_name``
   The name the bot uses when addressing you. Default: ``User``.

``auto_log_folder``
   Subdirectory for auto-logging conversations. Default: ``logs/``.

``whisper_model``
   Model for voice transcription. Default: ``base``.
   Options: ``tiny``, ``base``, ``small``, ``medium``, ``large-v3``.

``max_history_chars``
   Maximum character budget for conversation history sent to the LLM. Default: ``50000``.

``max_context_chars``
   Maximum character budget for file context. Default: ``10000``.

Supported Providers
-------------------

Folderbot uses `instructor <https://python.useinstructor.com/>`_ for LLM integration,
supporting 18+ providers:

.. list-table::
   :header-rows: 1
   :widths: 20 40 30

   * - Provider
     - Model format
     - Env var
   * - Anthropic
     - ``anthropic/claude-sonnet-4-20250514``
     - ``ANTHROPIC_API_KEY``
   * - OpenAI
     - ``openai/gpt-4o``
     - ``OPENAI_API_KEY``
   * - Azure OpenAI
     - ``azure_openai/gpt-4``
     - ``AZURE_OPENAI_API_KEY``
   * - AWS Bedrock
     - ``bedrock/anthropic.claude-3-sonnet``
     - AWS credentials
   * - Google
     - ``google/gemini-2.0-flash``
     - ``GOOGLE_API_KEY``
   * - Groq
     - ``groq/llama-3.1-70b``
     - ``GROQ_API_KEY``
   * - Mistral
     - ``mistral/mistral-large-latest``
     - ``MISTRAL_API_KEY``
   * - Ollama
     - ``ollama/llama3.1``
     - (local, no key needed)
   * - DeepSeek
     - ``deepseek/deepseek-chat``
     - ``DEEPSEEK_API_KEY``
   * - OpenRouter
     - ``openrouter/openai/gpt-4-turbo``
     - ``OPENROUTER_API_KEY``

See the `instructor docs <https://python.useinstructor.com/concepts/from_provider/>`_
for the full list of supported providers.

Read Rules
----------

Control which files the bot can access:

.. code-block:: toml

   [read_rules]
   include = ["**/*.md", "**/*.txt"]
   exclude = ["**/docs/**", ".git/**"]
   append_allowed = ["**/todo.md"]

``include``
   Glob patterns for files the bot can read. Default: all files.

``exclude``
   Glob patterns for files to skip. Default: none.

``append_allowed``
   Glob patterns for files the bot can append to (not just overwrite).

File Watching
-------------

Configure file change notifications:

.. code-block:: toml

   [watch]
   debounce_seconds = 3.0
   ignore_patterns = ["*.tmp", ".git/**"]

Multi-Bot Configuration
-----------------------

Run multiple bots with different folders from a single config:

.. code-block:: toml

   api_key = "SHARED_KEY"

   [bots.work]
   telegram_token = "WORK_BOT_TOKEN"
   root_folder = "~/work/notes"
   allowed_user_ids = [123456789]

   [bots.personal]
   telegram_token = "PERSONAL_BOT_TOKEN"
   root_folder = "~/personal/notes"
   allowed_user_ids = [123456789]

Run a specific bot:

.. code-block:: bash

   folderbot run --bot work
   folderbot run --bot personal

Each bot gets its own systemd service when installed:

.. code-block:: bash

   folderbot service install --bot work
   folderbot service install --bot personal

Tool Configuration
------------------

Tools can be configured under the ``[tools]`` section, with subsections per tool:

.. code-block:: toml

   [tools.web_search]
   google_api_key = "YOUR_GOOGLE_API_KEY"
   google_cx = "YOUR_SEARCH_ENGINE_ID"

   [tools.whisper]
   model = "base"  # Options: tiny, base, small, medium, large-v3

Each tool reads its own ``[tools.<name>]`` section. Custom tools (see below) can also
define their own configuration sections.

Web Search
^^^^^^^^^^

To enable web search, configure a Google Custom Search API key:

.. code-block:: toml

   [tools.web_search]
   google_api_key = "YOUR_GOOGLE_API_KEY"
   google_cx = "YOUR_SEARCH_ENGINE_ID"

See `Google Custom Search API <https://developers.google.com/custom-search/v1/overview>`_ for setup instructions.

Custom tools can read their own configuration from ``[tools.<tool_name>]``:

.. code-block:: toml

   [tools.my_custom_tool]
   api_url = "https://example.com"
   timeout = 30

The ``tools_config`` dict is passed to ``CustomTools.__init__()`` or ``create_tools()``
as a keyword argument. Old-style custom tools that don't accept ``tools_config`` continue
to work without changes.