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

# Introduction to Router

> Route AI requests through visual decision graphs

## Overview

Bud AI Foundry Router lets teams build reusable routing graphs for AI traffic. A router combines signals, projections, decision rules, algorithms, and plugins so a single OpenAI-compatible request can be evaluated and sent to the best endpoint or policy path.

Routers are created as project resources, configured in a visual editor, saved as active router definitions, and exposed through the chat completions API by using the router name as the `model` value.

```mermaid theme={null}
graph LR
    Request[Chat Completion Request] --> Trigger[Router Trigger]
    Trigger --> Signal[Signal]
    Trigger --> Projection[Projection]
    Trigger --> Decision[Decision]
    Signal -. referenced by .-> Decision
    Projection -. referenced by .-> Decision
    Decision --> Algorithm[Algorithm]
    Decision --> Plugin[Plugin]
    Algorithm --> Endpoint[Selected Endpoint]
    Plugin --> Response[Policy or Enhanced Response]
```

## Key Features

**Visual Router Editor**
Build router graphs with drag-and-drop actions, category-aware lanes, and guarded connection rules.

**Project-Scoped Creation**
Create routers globally and assign them to a project, or create routers directly from project context.

**Dynamic Action Catalog**
Router actions load from the `/routers/actions` API and include parameter metadata, output definitions, validation rules, and categories.

**OpenAI-Compatible Usage**
Use a router through `v1/chat/completions` with your API key and the router name in the `model` field.

**Operational Controls**
Search, paginate, edit, delete, save, and inspect router cards with status, step count, run count, and last execution metadata.

## Router Building Blocks

| Category       | Purpose                                               | Connection Behavior                                       |
| -------------- | ----------------------------------------------------- | --------------------------------------------------------- |
| **Trigger**    | Entry point for a router request                      | Connects to Signal, Decision, or Projection actions       |
| **Signal**     | Extract or evaluate request inputs                    | Connects from Trigger and is referenced by Decision rules |
| **Projection** | Derive normalized routing context                     | Connects from Trigger and is referenced by Decision rules |
| **Decision**   | Evaluate rules and choose downstream behavior         | Connects to Algorithm or Plugin actions                   |
| **Algorithm**  | Select, order, weight, or fallback across endpoints   | Leaf node connected from a Decision                       |
| **Plugin**     | Add policy, cache, guardrail, or integration behavior | Leaf node connected from a Decision                       |

<Info>
  Router action categories are resolved from API metadata and action type prefixes. The editor blocks invalid edges and shows contextual guidance when users try to connect unsupported node pairs.
</Info>

## How It Works

1. **Create** - Define the router name, description, icon, and project.
2. **Design** - Open the router detail page and add actions from the router action catalog.
3. **Connect** - Wire Trigger → Signal / Decision / Projection and Decision → Algorithm / Plugin.
4. **Configure** - Fill action parameters using clusters, models, projects, providers, credentials, and endpoints.
5. **Save** - Persist the router DAG as `dag_config` and activate the router.
6. **Use** - Call `v1/chat/completions` with `model` set to the router name.

## Use Cases

<CardGroup cols={2}>
  <Card title="Endpoint Selection" icon="route">
    Route traffic to the best deployment based on request metadata, availability, or configured rules.
  </Card>

  <Card title="Fallback Routing" icon="shuffle">
    Attach algorithms that recover from endpoint failures or route to alternate deployments.
  </Card>

  <Card title="Policy-Aware Routing" icon="shield-halved">
    Combine decision rules and plugins to apply guardrails, cache policies, or governance controls.
  </Card>

  <Card title="Project-Level AI Gateway" icon="diagram-project">
    Give each project a managed router that frontends and applications call through one API surface.
  </Card>
</CardGroup>

## Getting Started

<CardGroup cols={3}>
  <Card title="Quick Start" icon="play" href="/router/quickstart">
    Create and use your first router in minutes
  </Card>

  <Card title="Router Concepts" icon="book" href="/router/router-concepts">
    Understand router DAGs, categories, and connection rules
  </Card>

  <Card title="Detailed Tutorial" icon="graduation-cap" href="/router/creating-first-router">
    Build a production-ready routing graph step by step
  </Card>
</CardGroup>