How OmniRoute's Wildcard Router Handles Dynamic Model Routing Patterns

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

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

// 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, 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:

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:

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:

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}