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

# Smart Routing

> Define custom routing logic based on the user's intent. Let LLM Router automatically detect the topic and select the best model from your predefined tags.

***

To maximize efficiency and cost savings, LLM Router requires you to define strict rules about which models handle specific types of workloads.

Instead of hardcoding a single model for every request in your application, you define **Tags**. For example, you can configure your router so that all **UI Design** questions go to Gemini, but all **Unit Testing** questions go to DeepSeek.

You achieve this powerful dynamic routing using the `gateway.tags` configuration.

## How Tag Routing Works

When a request arrives, our internal Gateway AI analyzes the prompt in milliseconds. It performs two critical steps:

1. **Intent Matching:** It matches the user's prompt to the `description` of one of your provided tags.
2. **Complexity Scoring:** It scores the difficulty of the prompt (from 0.0 to 1.0) and selects the appropriate model from that tag's `models` array.

### Critical Rule: Sorting Your Models

When defining the `models` array inside a tag, **you must sort the models from most complex (smartest/most expensive) to least complex (simplest/cheapest).**

The Gateway uses the complexity score to pick the right model from this list:

* A score of **`0.9` (Very Hard)** will select the **first** model in your array.
* A score of **`0.1` (Very Simple)** will select the **last** model in your array.

### Basic Implementation

You pass the `gateway` object directly into your request.

```typescript TypeScript theme={null}
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.llmrouter.app/v1",
  apiKey: process.env.LLM_ROUTER_API_KEY,
});

async function main() {
  const response = await client.chat.completions.create({
    // Notice we do NOT specify a hardcoded `model` here.
    // The router will pick one based on the matched tag.
    messages: [
      { role: "user", content: "Write a Jest unit test for my React button." },
    ],

    // @ts-expect-error - Custom LLM Router extension
    gateway: {
      tags: [
        {
          name: "coding",
          description:
            "Code generation, refactoring, debugging, and software development",
          models: [
            "anthropic/claude-3-5-sonnet", // Complex (Score: 0.8+)
            "openai/gpt-5.4", // Medium (Score: 0.4 - 0.7)
            "deepseek/deepseek-chat", // Simple (Score: < 0.4)
          ],
        },
        {
          name: "testing",
          description:
            "Writing unit tests, integration tests, test-driven development, and QA",
          models: [
            "openai/gpt-5.4", // Complex
            "deepseek/deepseek-chat", // Medium
            "mistral/mistral-large-latest", // Simple
          ],
        },
      ],
      // Fallback specifically for Multi-Modal / Image requests
      imageGenerationModel: "black-forest-labs/flux-1.1-pro",
    },
  });

  console.log(response.choices[0].message.content);
}
main();
```

### What happens in this example?

1. **Analysis:** The user asked for a *"Jest unit test"*.
2. **Intent Matching:** The Gateway matches the intent perfectly to the `"testing"` tag.
3. **Complexity Scoring:** The Gateway determines that writing a basic React button test is moderately difficult (Score: `0.5`).
4. **Execution:** Because the score is in the middle, it selects the middle model from the `"testing"` array: `deepseek/deepseek-chat`. (Saving you the cost of GPT-5.4).

***

## Configuring Multi-Modal Fallbacks

Sometimes, a user's prompt will trigger a completely different modality. For example, if your app is a general chatbot, a user might suddenly ask: *"Generate an image of a sunset."*

If the Gateway detects that the user's intent is to create a visual asset (not text), it will ignore your text-based tags and instantly route the request to the model specified in `imageGenerationModel`.

```typescript theme={null}
gateway: {
  // Used exclusively when the request involves creating images.
  imageGenerationModel: "google/gemini-3-pro-image",
}
```

***

## Configuration Properties

### The `Tag` Object

| Property      | Type       | Description                                                                                                                              |
| :------------ | :--------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | `string`   | A short identifier for the tag (e.g., "coding", "support").                                                                              |
| `description` | `string`   | **Crucial:** A clear, semantic description of the topics this tag covers. The internal AI uses this string to match the user's prompt.   |
| `models`      | `string[]` | An array of models sorted from **Most Complex** to **Least Complex**. The router picks the model based on the prompt's difficulty score. |

### The `Gateway` Object

| Property               | Type     | Description                                                                                                         |
| :--------------------- | :------- | :------------------------------------------------------------------------------------------------------------------ |
| `tags`                 | `Tag[]`  | An array of custom routing rules.                                                                                   |
| `imageGenerationModel` | `string` | (Optional) The specific model to use if the Gateway determines the user wants to generate an image instead of text. |