# How OmniRoute's Wildcard Router Handles Dynamic Model Routing Patterns

> Discover how OmniRoute's wildcard router manages dynamic model routing patterns using a three-tier precedence system for flexible AI backend routing.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: deep-dive
- Published: 2026-07-25

---

**OmniRoute's wildcard router resolves dynamic model identifiers through a strict three-tier precedence system—exact alias lookup, glob-style wildcard matching, and provider fallback inference—enabling flexible routing across multiple AI backends.**

OmniRoute implements a sophisticated wildcard routing system to map dynamic model names to concrete provider-model pairs. Located in [`open-sse/services/wildcardRouter.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/wildcardRouter.ts), the router enables administrators to define flexible routing rules using `*` and `?` operators while maintaining deterministic resolution order. This article examines the complete implementation of dynamic model routing patterns in the diegosouzapw/OmniRoute repository.

## Three-Tier Resolution Architecture

The `resolveModelInfo` function orchestrates model resolution through a strict hierarchy defined in the source code. When processing a `modelId`, the router attempts three strategies in sequence, returning immediately upon the first successful match.

### Exact Alias Lookup (Fast Path)

First, the router queries the model alias map via `getModelAliasMap()` for an exact string match. If the map contains the key, the corresponding value—formatted as `"provider/model"`—is split into components and validated against `getProviderInfo()`. This provides immediate O(1) resolution for frequently used models without regex overhead.

```typescript
// From open-sse/services/wildcardRouter.ts
const exactAlias = await getModelAliasMap().then((map) => map[modelId]);
if (exactAlias) {
  const [providerId, model] = exactAlias.split("/");
  const providerInfo = await getProviderInfo(providerId);
  return providerInfo ? { providerId, model } : undefined;
}

```

### Wildcard Pattern Matching

When no exact match exists, the router extracts entries containing wildcard characters from the alias map. The `resolveWildcardAlias` helper converts each glob pattern to a case-insensitive regular expression—replacing `*` with `.*` and `?` with `.`—and tests the model ID against each pattern in configuration order. The first match wins, allowing patterns like `"claude-*"` to dynamically route all Claude variants to a specific provider.

```typescript
// Wildcard resolution logic
const wildcardAliases = await getModelAliasMap().then((map) => {
  return Object.entries(map).filter(([pattern]) => pattern.includes("*"));
});
const wildcardMatch = resolveWildcardAlias(modelId, wildcardAliases);
if (wildcardMatch) {
  const { target } = wildcardMatch;
  const [providerId, model] = target.split("/");
  const providerInfo = await getProviderInfo(providerId);
  return providerInfo ? { providerId, model } : undefined;
}

```

### Provider Fallback Resolution

If neither exact nor wildcard aliases match, the router falls back to `getModelInfoCore(modelId)`, which infers the provider from the model ID's prefix or naming convention. This ensures that even unconfigured models resolve to appropriate providers, though the function returns `undefined` if inference fails or the provider is invalid.

## Wildcard Syntax and Matching Rules

The router implements standard glob semantics with specific constraints:

- **Asterisk (`*`)**: Matches zero or more characters (converted to `.*` in RegExp)
- **Question mark (`?`)**: Matches exactly one character (converted to `.` in RegExp)
- **Case insensitivity**: All patterns use the `/i` flag for case-insensitive comparison
- **First-match wins**: When multiple wildcards match, the earliest entry in the configuration array prevails
- **Anchor enforcement**: Patterns are anchored with `^` and `$` to require full string matches

These behaviors are validated by the unit test suite in [`tests/unit/wildcard-router.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tests/unit/wildcard-router.test.ts), which covers prefix stars (`"claude-*"`), middle stars (`"claude-*-4*"`), single-character matching (`"gpt-?o"`), and null safety checks.

## Implementing Dynamic Routing in Code

### Resolving Models with Automatic Fallback

Use `resolveModelInfo` to leverage the complete three-tier resolution pipeline:

```typescript
import { resolveModelInfo } from "@/open-sse/services/wildcardRouter";

// Matches wildcard alias "claude-*" → "openai/gpt-4o-mini"
const info = await resolveModelInfo("claude-haiku-2024");
// Returns: { providerId: "openai", model: "gpt-4o-mini" }

```

### Direct Wildcard Matching

For custom logic, use `resolveWildcardAlias` with tuple arrays:

```typescript
import { resolveWildcardAlias } from "@/open-sse/services/wildcardRouter";

const wildcards: Array<[string, string]> = [
  ["claude-*", "anthropic/claude-3-opus"],
  ["gpt-?o", "openai/gpt-4o"],
  ["*preview*", "openai/gpt-4-turbo"]
];

const match = resolveWildcardAlias("gpt-4o", wildcards);
// Returns: { pattern: "gpt-?o", target: "openai/gpt-4o" }

```

### Custom Resolution with Explicit Maps

The lower-level `resolveModel` function accepts separate exact and wildcard maps, useful for testing or isolated resolution contexts:

```typescript
import { resolveModel } from "@/open-sse/services/wildcardRouter";

const exactMap = { "premium-model": "openai/gpt-4-turbo" };
const wildcardList = [
  { pattern: "legacy-*", target: "openai/gpt-3.5-turbo" },
  { pattern: "exp-*", target: "anthropic/claude-instant" }
];

// Exact match takes precedence
resolveModel("premium-model", exactMap, wildcardList); 
// Returns: "openai/gpt-4-turbo"

// Falls back to wildcard
resolveModel("legacy-001", exactMap, wildcardList);
// Returns: "openai/gpt-3.5-turbo"

```

## Summary

- OmniRoute's wildcard router implements a deterministic three-tier resolution strategy: exact aliases, wildcard patterns, then provider inference via `getModelInfoCore`.
- The `resolveModelInfo` function in [`open-sse/services/wildcardRouter.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/wildcardRouter.ts) orchestrates lookups against `getModelAliasMap()` and validates providers through `getProviderInfo()`.
- **Glob patterns** support `*` (multi-character) and `?` (single-character) operators with case-insensitive matching implemented via RegExp conversion.
- The `resolveWildcardAlias` helper converts patterns like `"claude-*"` to anchored regular expressions (`/^claude-.*$/i`) for flexible model ID matching.
- Comprehensive unit tests in [`tests/unit/wildcard-router.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tests/unit/wildcard-router.test.ts) enforce correct precedence and pattern semantics, including null safety and specificity rules.

## Frequently Asked Questions

### What precedence order does the wildcard router use?

OmniRoute evaluates model resolution in strict sequence: first exact alias matches via `getModelAliasMap()`, then wildcard pattern matching through `resolveWildcardAlias()`, and finally provider fallback using `getModelInfoCore()`. This hierarchy ensures that specific configurations always override general patterns, and explicit wildcards take priority over inferred defaults.

### How are wildcard patterns converted to regular expressions?

The `resolveWildcardAlias` function transforms glob patterns by replacing `*` with `.*` and `?` with `.`, then wraps the result in `^...$` anchors with the case-insensitive `i` flag. For example, the pattern `"claude-*"` becomes the regular expression `/^claude-.*$/i`, while `"gpt-?o"` becomes `/^gpt-.o$/i`.

### Can wildcard patterns match any part of a model ID?

Yes. Patterns can utilize `*` at the beginning, middle, or end of strings. The pattern `"claude-*-4*"` matches `"claude-sonnet-4-20250514"` by capturing variable segments between fixed prefixes and suffixes. The single-character `?` operator matches exactly one character, making `"gpt-?o"` valid for `"gpt-4o"` but not `"gpt-40o"`.

### What happens if no alias or wildcard matches?

When no configuration matches, the router invokes `getModelInfoCore` to infer the provider from the model ID's prefix structure. If the inference succeeds and the provider exists in `getProviderInfo`, the router returns the inferred pair; otherwise, it returns `undefined`, indicating that the model cannot be routed.