# Agents & Providers Guide

TagForge uses "Agents" to connect to various AI providers. This guide explains how to set up your preferred model.

## 🤖 The Agent Manager

Here you can configure connections to different AI services.

### Supported Providers

| Provider | Best For | Requirement |
| :--- | :--- | :--- |
| **Google Gemini** | High-performance, multimodal reasoning. | [Google AI Studio API Key](https://aistudio.google.com/app/apikey) |

| **OpenRouter** | Access to OpenAI (GPT-4), Anthropic (Claude), etc. | [OpenRouter Key](https://openrouter.ai/keys) |
| **Hugging Face** | Massive library of open-source models. | [User Access Token](https://huggingface.co/settings/tokens) |
| **LM Studio** | Local inference server. | **Local Only** (Running app required) |
| **Ollama** | Local command-line inference. | **Local Only** (Installed service required) |

---

Different providers handle output lengths differently. You can precisely control these limits using the **Max Tokens Slider** in the Agent Manager.

### 🎚️ Max Tokens Slider
- **Range**: 128 to 32,768 tokens.
- **Default**: 4,096 tokens (optimal for most workflows).
- **Per-Agent**: Settings are saved individually for each agent configuration.

| Provider | Recommended Max Tokens | Why? |
| :--- | :--- | :--- |
| **Google Gemini** | **8192+** | Stable at extremely high output lengths. |
| **OpenRouter** | **4096** | Balanced for high-end cloud models. |
| **Ollama / LM Studio** | **4096** | Best for local VRAM and speed. |
| **Hugging Face** | **2048** | Avoids timeouts on free-tier inference. |

---

## 🔌 Connection Steps

### Cloud Providers
*(Google Gemini, OpenRouter, Hugging Face)*

1.  Select the provider.
2.  Paste your **API Key** into the field.
3.  Click **Fetch Models** to verify the key and get the latest model list.
    *   *If successful, the dropdown will populate with available models.*
4.  Select a **Model** from the dropdown.

> [!NOTE]
> **Zero-Trust Encryption**: Your API keys are secured using a machine-specific, hardware-salted obfuscation layer. This ensures that your credentials are protected cross-platform (Windows, Linux, and macOS) and cannot be utilized on a different device.

### Local Providers

#### Ollama
1.  Ensure [Ollama](https://ollama.com) is installed.
2.  Open a terminal and run `ollama serve`.
3.  In TagForge, select **Ollama** and click **Fetch Models**.

#### LM Studio
1.  Open [LM Studio](https://lmstudio.ai).
2.  Go to the **Local Server** tab.
3.  Load a model into memory.
4.  Start the server (usually on port `1234`).
5.  In TagForge, select **LM Studio** and click **Fetch Models**.



---

## 🛠️ Testing Connections (Ping)

Use the **Test Connection** button to verify your connection.
*   **Green Notification**: Success! The API is reachable.
*   **Red Notification**: Connection failed.

> [!WARNING]
> **Troubleshooting Failures**:
> *   **401 Unauthorized**: Your API Key is invalid.
> *   **429 Too Many Requests**: You have run out of credits or hit the rate limit.
> *   **Connection Refused**: For local providers, ensure the server is actually running.