> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fs.soquincy.qzz.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect AI Providers and Models to Your Bot

> Freesona supports Gemini, OpenAI, Ollama, NVIDIA NIM, Azure AI Foundry, Groq, and OpenRouter. Switch providers at runtime without restarting.

Freesona supports seven AI providers that all work with the same commands. Whether you use `/ask`, `/write`, `/search`, a conversation channel, or autonomy mode, the experience is identical regardless of which provider is active. Set your preferred provider at startup with environment variables, or switch to a different provider at any time without restarting the bot.

## Supported Providers

| Provider         | `AI_PROVIDER` value | Required environment variable(s)     |
| ---------------- | ------------------- | ------------------------------------ |
| Google Gemini    | `gemini`            | `GOOGLE_API_KEY`                     |
| OpenAI           | `openai`            | `OPENAI_API_KEY`                     |
| Ollama (local)   | `ollama`            | `OLLAMA_BASE_URL`                    |
| NVIDIA NIM       | `nim`               | `NVIDIA_API_KEY`                     |
| Azure AI Foundry | `azure`             | `AZURE_AI_KEY` + `AZURE_AI_BASE_URL` |
| Groq             | `groq`              | `GROQ_API_KEY`                       |
| OpenRouter       | `openrouter`        | `OPENROUTER_API_KEY`                 |

## Setting the Provider at Startup

Set `AI_PROVIDER` in your `.env` file to the provider value from the table above, then add the matching credentials. Set `MODEL_NAME` (or `AI_PROVIDER_MODEL`) to specify the default model for that provider.

<Tabs>
  <Tab title="Gemini">
    ```dotenv theme={null}
    AI_PROVIDER=gemini
    GOOGLE_API_KEY=your_gemini_api_key
    MODEL_NAME=gemini-flash-lite-latest
    ```
  </Tab>

  <Tab title="OpenAI">
    ```dotenv theme={null}
    AI_PROVIDER=openai
    OPENAI_API_KEY=your_openai_api_key
    AI_PROVIDER_MODEL=gpt-4o-mini
    # Optional: override the endpoint (e.g. for a proxy)
    OPENAI_BASE_URL=https://api.openai.com/v1/chat/completions
    ```
  </Tab>

  <Tab title="Ollama">
    ```dotenv theme={null}
    AI_PROVIDER=ollama
    OLLAMA_BASE_URL=http://localhost:11434/api/chat
    AI_PROVIDER_MODEL=llama3.1
    # No API key required — Ollama runs locally
    ```
  </Tab>

  <Tab title="NVIDIA NIM">
    ```dotenv theme={null}
    AI_PROVIDER=nim
    NVIDIA_API_KEY=your_nvidia_api_key
    NVIDIA_NIM_BASE_URL=https://integrate.api.nvidia.com/v1/chat/completions
    AI_PROVIDER_MODEL=meta/llama-3.1-8b-instruct
    ```
  </Tab>

  <Tab title="Azure">
    ```dotenv theme={null}
    AI_PROVIDER=azure
    AZURE_AI_KEY=your_azure_ai_key
    AZURE_AI_BASE_URL=https://your-resource.openai.azure.com/openai/deployments/your-deployment/chat/completions?api-version=2024-02-01
    AI_PROVIDER_MODEL=gpt-4o-mini
    ```
  </Tab>

  <Tab title="Groq">
    ```dotenv theme={null}
    AI_PROVIDER=groq
    GROQ_API_KEY=your_groq_api_key
    GROQ_BASE_URL=https://api.groq.com/openai/v1/chat/completions
    AI_PROVIDER_MODEL=llama-3.3-70b-versatile
    ```
  </Tab>

  <Tab title="OpenRouter">
    ```dotenv theme={null}
    AI_PROVIDER=openrouter
    OPENROUTER_API_KEY=your_openrouter_api_key
    OPENROUTER_BASE_URL=https://openrouter.ai/api/v1/chat/completions
    AI_PROVIDER_MODEL=meta-llama/llama-3.3-70b-instruct:free
    # Optional: attribution headers
    OPENROUTER_SITE_URL=https://your-site.example.com
    OPENROUTER_SITE_NAME=Freesona
    ```
  </Tab>
</Tabs>

## Switching Providers at Runtime

Change the active provider from Discord without editing `.env` or restarting. All provider commands are restricted to the Bot Owner.

| Command                | What it does                               |
| ---------------------- | ------------------------------------------ |
| `/provider show`       | Display the currently active provider      |
| `/provider set <name>` | Switch to a different provider immediately |
| `/provider reset`      | Revert to the provider value set in `.env` |

The `<name>` argument accepts the same values as `AI_PROVIDER` — `gemini`, `openai`, `ollama`, `nim`, `azure`, `groq`, or `openrouter`.

## Switching Models at Runtime

Override the active model independently of the provider, also without a restart.

| Command             | What it does                          |
| ------------------- | ------------------------------------- |
| `/model show`       | Display the currently active model    |
| `/model set <name>` | Switch to a different model name      |
| `/model reset`      | Revert to the model defined in `.env` |

<Tip>
  Use `/model set` to test different models on the same provider before committing a choice to your `.env` file. Use `/model reset` to snap back to your default after experimenting.
</Tip>

## Multimodal Input

Attach files to any AI command or conversation channel message and the bot will read them alongside your text prompt. Supported file types include:

* **Images:** PNG, JPEG, WEBP, GIF, HEIC, HEIF
* **Documents:** PDF, plain text, Markdown, CSV, HTML, RTF, XML
* **Code:** JavaScript, Python
* **Audio:** MP3, WAV, AAC, OGG, FLAC, AIFF
* **Video:** MP4, MOV, AVI, WEBM, WMV, 3GPP, MPEG

<Note>
  Multimodal input is fully supported on Gemini. Non-Gemini providers receive text-only input — attached files are silently ignored on providers that don't support multimodal processing.
</Note>

## Notes on Specific Providers

<AccordionGroup>
  <Accordion title="Google Gemini">
    Gemini is the default provider and the only one that supports server-side conversation continuity. Each user's conversation thread is tracked via Gemini's Interactions API using `previous_interaction_id`, scoped to `(guild_id, channel_id, user_id)` so one user's thread never bleeds into another's in the same channel. All other providers remain stateless and rely on the persona and long-term memory injection for context.
  </Accordion>

  <Accordion title="Ollama">
    Ollama runs entirely on your own machine — no API key is required. Set `OLLAMA_BASE_URL` to the address where your Ollama server is listening (default: `http://localhost:11434/api/chat`) and set `AI_PROVIDER_MODEL` to the name of a model you've already pulled locally.
  </Accordion>

  <Accordion title="OpenRouter">
    Set `OPENROUTER_SITE_URL` and `OPENROUTER_SITE_NAME` in your `.env` to send attribution headers with each request. OpenRouter uses these to identify your application in usage dashboards and to comply with certain model provider policies.
  </Accordion>
</AccordionGroup>