Documentation

Build LLM-powered agents
with production-ready TypeScript

DSPy for TypeScript. Working with LLMs is complex—they don't always do what you want. DSPy makes it easier to build amazing things with LLMs. Just define your inputs and outputs (signature) and an efficient prompt is auto-generated and used. Connect together various signatures to build complex systems and workflows using LLMs.

15+ LLM Providers
End-to-end Streaming
Auto Prompt Tuning

AxProviderRouter

Defined in: https://github.com/ax-llm/ax/blob/9a5a7060a48f9eef46efc680b0cdf6b42bff5df2/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/9a5a7060a48f9eef46efc680b0cdf6b42bff5df2/src/ax/ai/router.ts#L130

Creates a new provider router with the specified configuration.

Parameters

ParameterTypeDescription
configAxMultiProviderConfigRouter configuration including providers, routing preferences, and processing services

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/9a5a7060a48f9eef46efc680b0cdf6b42bff5df2/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

ParameterTypeDescription
requestAxChatRequestThe chat request to process
optionsAxAIServiceOptions & objectExtended options including fallback providers and routing preferences

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/9a5a7060a48f9eef46efc680b0cdf6b42bff5df2/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

ParameterTypeDescription
requestAxChatRequestThe chat request to analyze

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/9a5a7060a48f9eef46efc680b0cdf6b42bff5df2/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

NameType
capabilityMatrix{ [capability: string]: string[]; }
recommendedProviderstring
totalProvidersnumber

validateRequest()

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

Defined in: https://github.com/ax-llm/ax/blob/9a5a7060a48f9eef46efc680b0cdf6b42bff5df2/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

ParameterTypeDescription
requestAxChatRequestThe chat request to validate

Returns

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

Promise resolving to validation result with handling capability and recommendations