> ## 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.

# Router Concepts

> Understanding router DAGs, actions, parameters, and connections

## What is a Router?

A **router** is a directed graph that evaluates an AI request and chooses how it should be handled. Routers are especially useful when a project has multiple endpoints, policies, or optimization strategies but application developers need one stable API target.

```mermaid theme={null}
graph TB
    Request[Incoming Request] --> Trigger((Trigger))
    Trigger --> Signal[Signal]
    Trigger --> Projection[Projection]
    Trigger --> Decision[Decision]
    Signal -. context .-> Decision
    Projection -. context .-> Decision
    Decision --> Algorithm[Algorithm]
    Decision --> Plugin[Plugin]
```

## Router DAG Definition

The Bud admin UI models router graphs with a `RouterDAGDefinition` shape:

| Field         | Description                                  |
| ------------- | -------------------------------------------- |
| `name`        | Router graph name                            |
| `version`     | Optional version label                       |
| `description` | Optional summary of the routing purpose      |
| `parameters`  | Runtime inputs accepted by the router        |
| `steps`       | Ordered action nodes and dependency metadata |
| `outputs`     | Optional named outputs produced by the graph |

Each step includes an id, display name, action type, parameter object, dependency list, optional condition, optional failure behavior, and optional timeout.

## Action Categories

Router actions are fetched dynamically from the router API. The editor uses action metadata for display, parameter forms, outputs, and connection validation.

| Category       | Role in the Graph                                  | Examples of Parameters                                           |
| -------------- | -------------------------------------------------- | ---------------------------------------------------------------- |
| **Signal**     | Evaluate request or environment inputs             | Request fields, string lists, content rules                      |
| **Projection** | Transform context into normalized routing features | Templates, JSON objects, derived fields                          |
| **Decision**   | Choose downstream route based on rules             | Branches, rule trees, conditions                                 |
| **Algorithm**  | Execute endpoint selection strategy                | Endpoint lists, weighted endpoints, ordered fallback endpoints   |
| **Plugin**     | Apply extension behavior                           | Credentials, provider settings, cache or guardrail configuration |

<Note>
  The exact action list is backend-driven. If an expected action does not appear, refresh the router actions catalog or verify that `/routers/actions` returns the category and action metadata.
</Note>

## Connection Rules

The router editor intentionally supports a constrained topology so routing graphs remain predictable.

```mermaid theme={null}
graph LR
    Trigger((Trigger)) --> Signal[Signal]
    Trigger --> Projection[Projection]
    Trigger --> Decision[Decision]
    Decision --> Algorithm[Algorithm]
    Decision --> Plugin[Plugin]
```

### Allowed Connections

| Source   | Allowed Targets              |
| -------- | ---------------------------- |
| Trigger  | Signal, Decision, Projection |
| Decision | Algorithm, Plugin            |

### Rejected Connections

* Signal → any node
* Projection → any node
* Decision → Signal, Projection, Decision, or Trigger
* Algorithm → any node
* Plugin → any node
* Trigger → Algorithm or Plugin directly

The editor shows warnings for invalid connections, such as trying to connect a Trigger directly to an Algorithm. In that case, insert a Decision first and connect the Algorithm from the Decision.

## Parameters and Data Sources

Router action forms can draw options from Bud resources loaded on the detail page:

* **Clusters** use `cluster_id` values for deployment-compatible workflows.
* **Models** load global model records.
* **Projects** identify project-scoped routing ownership.
* **Providers** and **credentials** support proprietary or cloud-backed actions.
* **Endpoints** provide deployment targets for algorithm and routing actions.

## Save Lifecycle

When you click **Save**, Bud admin performs these steps:

1. Flush unsaved action configuration changes.
2. Validate action parameters in the editor panel.
3. Convert editor steps into API `dag_config.steps`.
4. Add `entry_step`, `parameters`, `outputs`, dependencies, conditions, and `next_steps`.
5. Update the router and set status to `active`.

```mermaid theme={null}
flowchart TD
    A[Click Save] --> B{Unsaved action changes?}
    B -->|Yes| C[Flush and validate]
    B -->|No| D[Map editor DAG]
    C -->|Valid| D
    C -->|Invalid| E[Show validation errors]
    D --> F[PUT /routers/{id}]
    F --> G[Router saved as active]
```

## Status and Operational Metadata

Routers can appear as `draft`, `active`, or `inactive`. Router cards display step count, execution count, creation time, and last execution time when available.