Learn 9router - Request Matching & Route Selection

#Introduction

In episode 3 you ran your first gateway with a single route catching all requests. Now we go up a level: how to make 9router intelligently choose routes. Instead of all requests going to one model, we'll direct each request to the most appropriate route based on its content and context.

This episode's roadmap: we'll discuss the four routing dimensions — intent, task type, user identity, and metadata — then dive into the basics of rule matching with keyword, semantic classification, and fallback, and finish with route priority and route chaining. You'll leave this episode able to compose sharp matching rules.

#The Four Routing Dimensions

A 9router routing decision can consider four complementary dimensions:

Combining these dimensions enables precise rules: for example, "premium users with intent code and region ap-southeast-1 are directed to a large code model". The more dimensions you use, the more accurate the routing decision — but also the more complex it becomes. Start simple and strengthen gradually.

#Rule Matching Basics: Keyword

The most basic matching method is keyword: matching keywords that appear in the prompt. This approach is fast, cheap, and deterministic — perfect for clear patterns. For example, a route that catches light questions with the keyword "jam buka" (opening hours):

routes:
  - name: faq-fast
    match:
      keywords:
        - "jam buka"
        - "lokasi toko"
        - "nomor telepon"
    target:
      model: gpt-4o-mini

The faq-fast route catches prompts containing any of the keywords and directs them to a cheap, fast model. Note the important ordering: routes with specific criteria must be placed before the default route, because 9router evaluates routes in declaration order. We'll go deeper on this in the route priority section.

#Semantic Classification: Understanding Meaning

Keywords have a weakness: they're rigid against language variation. A user might ask "sampai jam berapa bukanya?" (until what time are you open?) without saying the keyword "jam buka". This is where semantic classification comes in — 9router uses an embedding model to classify prompts into intents based on meaning similarity.

routes:
  - name: faq-fast
    match:
      intent: faq
    target:
      model: gpt-4o-mini

The configuration above uses the faq intent produced by the semantic classifier. 9router manages intent definitions and training data in a separate file, for example config/intents.yaml:

intents:
  - name: faq
    examples:
      - "sampai jam berapa bukanya?"
      - "di mana alamat kantor kalian?"
      - "apa nomor kontak yang bisa dihubungi?"
    strategy: semantic

Each intent has example sentences that serve as training material for the classifier. This approach is more flexible than keywords, with the consequence of a slightly higher execution cost because there's an embedding model call per request.

#Routing Based on User Identity and Metadata

Routing decisions often depend on who the user is and the surrounding context. 9router reads user identity from the auth token or payload field, and metadata from headers and request attributes:

routes:
  - name: premium-code
    match:
      user:
        tier: premium
      metadata:
        region: ap-southeast-1
      intent: code
    target:
      model: gpt-4o-premium
  - name: standard-chat
    match:
      any: true
    target:
      model: gpt-4o-mini

With this configuration, only premium users with intent code and a matching region get the large model; all other requests fall to the default route. This pattern is the foundation of tenant-aware routing we'll explore deeper in episode 9.

#Route Priority and Fallback

Now we reach the most important concept: evaluation order. 9router evaluates routes top to bottom and selects the first matching route. This means declaration order is a design decision, not a coincidence:

A default route with any: true at the bottom guarantees every request is still served. If no route matches, 9router returns an error response with a clear code — checkable in the logs. To handle cases where a model is unavailable, each route can declare fallback models:

routes:
  - name: vision-route
    match:
      taskType: vision
    target:
      model: gpt-4o-vision
      fallback:
        - model: claude-vision
        - model: gemini-vision

If the primary model fails or is unavailable, 9router tries the fallbacks in sequence before giving up. This is an early form of resilience we'll deepen in episode 18.

#Route Chaining: More Than One Decision

So far every route produces a single direct decision. Route chaining lets a request pass through several routes in sequence — the result of the first step becomes the input of the next step. This pattern is useful for layered flows: first classify the request, then decide the tool call, then send to the model.

routes:
  - name: classifier
    match:
      any: true
    chain:
      - next: tool-selector
        on: classify
  - name: tool-selector
    match:
      intent: search
    target:
      tool: search-api
    chain:
      - next: final-model
        on: tool_result
  - name: final-model
    match:
      any: true
    target:
      model: gpt-4o

The configuration above illustrates a simple agentic flow: the request is classified, if its intent is search then the search tool is called, and the result is sent to the final model. Route chaining is the backbone of the tool invocation we introduced in episode 2 — and will be the foundation for advanced routing patterns in episode 8.

#Practice: Testing Rule Matching

To verify your matching rules, send several requests with varied prompts and observe the selected route via metadata:

curl -X POST http://localhost:8080/v1/chat \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"sampai jam berapa bukanya?","include_route_meta":true}'

Repeat with different prompts — technical questions, code requests, or light questions — then compare the route field in each response. You'll see how keywords, intents, and metadata collaborate to determine the route. If the results don't match expectations, run 9router validate again and check the route order in the configuration file.

#Conclusion

In episode 4 you've mastered the art of request matching and route selection: the four routing dimensions, the difference between keyword and semantic classification, the role of user identity and metadata, priority and fallback rules, and the route chaining pattern for layered flows.

Key takeaways:

• Routing decisions can consider intent, task type, user identity, and metadata simultaneously.
• Keywords are fast and cheap for clear patterns; semantic classification captures meaning variation.
• Specific routes on top, default route on the bottom — declaration order determines priority.
• Fallback models keep a route alive when the primary model fails.
• Route chaining lets a request pass through several layered decisions, including tool invocation.

In the next episode, episode 5, we'll discuss model and tool selection — how to choose the target model based on performance, cost, and accuracy, build a multi-model stack for conversational, embeddings, code, and vision, and integrate external tools and API services into routing decisions. We'll fill your matching laboratory with a variety of models!