AxProviderRouter

Defined in: https://github.com/ax-llm/ax/blob/5b28f9093bb70863b59459bb6df5062d005bce41/src/ax/ai/router.ts#L120

Multi-provider router that automatically selects optimal AI providers and handles content processing.

The router analyzes requests to determine capability requirements, scores available providers, and automatically handles content transformation for unsupported media types. It provides graceful degradation and fallback mechanisms for robust multi-modal AI applications.

Example

const router = new AxProviderRouter({
  providers: {
    primary: openaiProvider,
    alternatives: [geminiProvider, cohereProvider]
  },
  routing: {
    preferenceOrder: ['capability', 'quality'],
    capability: {
      requireExactMatch: false,
      allowDegradation: true
    }
  },
  processing: {
    imageToText: async (data) => await visionService.describe(data),
    audioToText: async (data) => await speechService.transcribe(data)
  }
});

const result = await router.chat(multiModalRequest);
console.log(`Used: ${result.routing.provider.getName()}`);

Constructors

Constructor

new AxProviderRouter(config: AxMultiProviderConfig): AxProviderRouter;

Defined in: https://github.com/ax-llm/ax/blob/5b28f9093bb70863b59459bb6df5062d005bce41/src/ax/ai/router.ts#L130

Creates a new provider router with the specified configuration.

Parameters

Returns

AxProviderRouter

Methods

chat()

chat(request: AxChatRequest, options: AxAIServiceOptions & object): Promise<{
  response:   | AxChatResponse
     | ReadableStream<AxChatResponse>;
  routing: AxRoutingResult;
}>;

Defined in: https://github.com/ax-llm/ax/blob/5b28f9093bb70863b59459bb6df5062d005bce41/src/ax/ai/router.ts#L170

Routes a chat request to the most appropriate provider with automatic content processing.

This method analyzes the request, selects the optimal provider, preprocesses content for compatibility, and executes the request with fallback support.

Example

const result = await router.chat(
  { chatPrompt: [{ role: 'user', content: [{ type: 'image', image: '...' }] }] },
  {
    processingOptions: { fallbackBehavior: 'degrade' },
    routingOptions: { allowDegradation: true }
  }
);

console.log(`Provider: ${result.routing.provider.getName()}`);
console.log(`Processing applied: ${result.routing.processingApplied}`);

Parameters

Returns

Promise<{ response: | AxChatResponse | ReadableStream<AxChatResponse>; routing: AxRoutingResult; }>

Promise resolving to the AI response and routing information

Throws

AxMediaNotSupportedError when no suitable provider can handle the request

getRoutingRecommendation()

getRoutingRecommendation(request: AxChatRequest): Promise<AxRoutingResult>;

Defined in: https://github.com/ax-llm/ax/blob/5b28f9093bb70863b59459bb6df5062d005bce41/src/ax/ai/router.ts#L405

Gets routing recommendation without executing the request.

Analyzes the request and returns routing information including which provider would be selected, what processing would be applied, and any degradations or warnings.

Example

const recommendation = await router.getRoutingRecommendation(request);
console.log(`Would use: ${recommendation.provider.getName()}`);
console.log(`Degradations: ${recommendation.degradations.join(', ')}`);

Parameters

Returns

Promise<AxRoutingResult>

Promise resolving to routing result with provider selection and processing info

getRoutingStats()

getRoutingStats(): object;

Defined in: https://github.com/ax-llm/ax/blob/5b28f9093bb70863b59459bb6df5062d005bce41/src/ax/ai/router.ts#L527

Gets detailed statistics about the router’s provider capabilities.

Returns information about available providers, their supported capabilities, and routing recommendations for analysis and debugging purposes.

Example

const stats = router.getRoutingStats();
console.log(`Total providers: ${stats.totalProviders}`);
console.log('Capabilities:');
for (const [capability, providers] of Object.entries(stats.capabilityMatrix)) {
  console.log(`  ${capability}: ${providers.join(', ')}`);
}

Returns

object

Object containing provider statistics and capability matrix

validateRequest()

validateRequest(request: AxChatRequest): Promise<{
  canHandle: boolean;
  issues: string[];
  recommendations: string[];
}>;

Defined in: https://github.com/ax-llm/ax/blob/5b28f9093bb70863b59459bb6df5062d005bce41/src/ax/ai/router.ts#L430

Validates whether the configured providers can handle a specific request.

Performs pre-flight validation to check if the request can be successfully processed by available providers, identifies potential issues, and provides recommendations for improving compatibility.

Example

const validation = await router.validateRequest(request);
if (!validation.canHandle) {
  console.log('Issues:', validation.issues);
  console.log('Recommendations:', validation.recommendations);
}

Parameters

Returns

Promise<{ canHandle: boolean; issues: string[]; recommendations: string[]; }>

Promise resolving to validation result with handling capability and recommendations