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

AI Engine — ``.env``
====================

The recommendation engine is configured entirely through environment variables
loaded from a ``.env`` file at the engine root.

.. code-block:: ini

   # Generative AI (Gemini via OpenRouter)
   OPENROUTER_API_KEY=sk-or-v1-your-key
   OPENROUTER_MODEL=google/gemini-2.0-flash-exp:free

   # Vector database
   QDRANT_USE_SERVER=true
   QDRANT_URL=http://localhost:6333

   # Embeddings
   OLLAMA_BASE_URL=http://localhost:11434

   # PostgreSQL
   POSTGRES_HOST=localhost
   POSTGRES_PORT=5432
   POSTGRES_DB=agent_memory
   POSTGRES_USER=oim_user
   POSTGRES_PASSWORD=your_password
   POSTGRES_SSLMODE=prefer

.. warning::

   Never commit a populated ``.env`` file to version control. Use a secrets
   manager in production and rotate the OpenRouter API key periodically.

PostgreSQL SSL Modes
====================

The ``POSTGRES_SSLMODE`` value controls transport security to the database:

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Mode
     - Behaviour
   * - ``disable``
     - No SSL. Use only on a trusted local network.
   * - ``prefer``
     - Try SSL but accept a non-SSL connection (default).
   * - ``require``
     - Require SSL. Use when the database is reached over the public Internet.

Connection Pool (v2.0)
======================

The PostgreSQL memory layer (``agent_memory.py``) uses an optimized connection
pool with the following characteristics:

* 1–10 reusable connections.
* Automatic TCP keepalive to prevent idle-connection timeouts.
* Auto-reconnection with retry (up to three attempts).
* Configurable SSL mode (``disable`` / ``prefer`` / ``require``).
* 2–5× improved throughput versus per-request connections.

Web Clients
===========

The Next.js frontend and partners portal read configuration from
``.env.local``. The key variable is the backend API base URL (for example
``NEXT_PUBLIC_API_URL``); internationalization (``next-intl``) and theme
defaults are configured in the ``messages/`` directory and the providers under
``src/providers``.

Mobile Application
==================

The mobile app reads its API base URL and environment from ``.env`` and
``app.json`` (Expo configuration). Secure values (tokens) are stored on-device
using ``expo-secure-store``; localization is handled with ``i18n-js`` and
``expo-localization``.