> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Router.Rerank SDK Reference

> SDK reference for the Router.Rerank API, available in Node.js and Python.

## Router.Rerank

### Create a Rerank

Rerank a list of documents based on their relevance to a query.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.router.rerank.create(query="<value>", documents=[
          "<value 1>",
      ], model="XTS", retry={
          "on_codes": [
              429,
              500,
              502,
              503,
              504,
          ],
      }, cache={
          "ttl": 3600,
          "type": "exact_match",
      }, load_balancer={
          "type": "weight_based",
          "models": [],
      }, timeout={
          "call_timeout": 30000,
      }, orq={
          "fallbacks": [
              {
                  "model": "openai/gpt-4o-mini",
              },
          ],
          "cache": {
              "ttl": 3600,
              "type": "exact_match",
          },
          "retry": {
              "on_codes": [
                  429,
                  500,
                  502,
                  503,
                  504,
              ],
          },
          "identity": {
              "id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
              "display_name": "Jane Doe",
              "email": "jane.doe@example.com",
              "metadata": [
                  {
                      "department": "Engineering",
                      "role": "Senior Developer",
                  },
              ],
              "logo_url": "https://example.com/avatars/jane-doe.jpg",
              "tags": [
                  "hr",
                  "engineering",
              ],
          },
          "load_balancer": {
              "type": "weight_based",
              "models": [
                  {
                      "model": "openai/gpt-4o",
                      "weight": 0.7,
                  },
                  {
                      "model": "anthropic/claude-3-5-sonnet",
                      "weight": 0.3,
                  },
              ],
          },
          "timeout": {
              "call_timeout": 30000,
          },
      })

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.router.rerank.create({
      query: "<value>",
      documents: [
        "<value 1>",
      ],
      model: "XTS",
      retry: {
        onCodes: [
          429,
          500,
          502,
          503,
          504,
        ],
      },
      cache: {
        ttl: 3600,
        type: "exact_match",
      },
      loadBalancer: {
        type: "weight_based",
        models: [],
      },
      timeout: {
        callTimeout: 30000,
      },
      orq: {
        fallbacks: [
          {
            model: "openai/gpt-4o-mini",
          },
        ],
        cache: {
          ttl: 3600,
          type: "exact_match",
        },
        retry: {
          onCodes: [
            429,
            500,
            502,
            503,
            504,
          ],
        },
        identity: {
          id: "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
          displayName: "Jane Doe",
          email: "jane.doe@example.com",
          metadata: [
            {
              "department": "Engineering",
              "role": "Senior Developer",
            },
          ],
          logoUrl: "https://example.com/avatars/jane-doe.jpg",
          tags: [
            "hr",
            "engineering",
          ],
        },
        loadBalancer: {
          type: "weight_based",
          models: [
            {
              model: "openai/gpt-4o",
              weight: 0.7,
            },
            {
              model: "anthropic/claude-3-5-sonnet",
              weight: 0.3,
            },
          ],
        },
        timeout: {
          callTimeout: 30000,
        },
      },
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "query": str,  # required
        "documents": List[str],  # required
        "model": str,  # required
        "top_n": Optional[float],
        "filename": OptionalNullable[str],
        "name": Optional[str],
        "fallbacks": {  # optional
            "model": str,  # required
        },
        "retry": {  # optional
            "count": Optional[float],
            "on_codes": List[float],
        },
        "cache": {  # optional
            "ttl": Optional[float],
            "type": Literal["exact_match"],  # required
        },
        "load_balancer": Union[CreateRerankLoadBalancer1],
        "timeout": {  # optional
            "call_timeout": float,  # required
        },
        "plugins": Union[PIIRedactionPluginAuto, PIIRedactionPluginEn, PIIRedactionPluginNl],
        "orq": {  # optional
            "name": Optional[str],
            "fallbacks": {  # optional
                "model": str,  # required
            },
            "cache": {  # optional
                "ttl": Optional[float],
                "type": Literal["exact_match"],  # required
            },
            "retry": {  # optional
                "count": Optional[float],
                "on_codes": List[float],
            },
            "identity": {  # optional
                "id": str,  # required
                "display_name": Optional[str],
                "email": Optional[str],
                "metadata": List[Dict[str, Any]],
                "logo_url": Optional[str],
                "tags": List[str],
            },
            "~~`contact`~~": {  # optional
                "id": str,  # required
                "display_name": Optional[str],
                "email": Optional[str],
                "metadata": List[Dict[str, Any]],
                "logo_url": Optional[str],
                "tags": List[str],
            },
            "load_balancer": Union[CreateRerankLoadBalancerRouterRerank1],
            "timeout": {  # optional
                "call_timeout": float,  # required
            },
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      query: string;  // required
      documents: string[];  // required
      model: string;  // required
      topN?: number;
      filename?: string;
      name?: string;
      fallbacks?: {
        model: string;  // required
      };
      retry?: {
        count?: number;
        onCodes?: number[];
      };
      cache?: {
        ttl?: number;
        type: string;  // required
      };
      loadBalancer?: string;
      timeout?: {
        callTimeout: number;  // required
      };
      plugins?: string;
      orq?: {
        name?: string;
        fallbacks?: {
          model: string;  // required
        };
        cache?: {
          ttl?: number;
          type: string;  // required
        };
        retry?: {
          count?: number;
          onCodes?: number[];
        };
        identity?: {
          id: string;  // required
          displayName?: string;
          email?: string;
          metadata?: Record<string, any>[];
          logoUrl?: string;
          tags?: string[];
        };
        ~~`contact`~~?: {
          id: string;  // required
          displayName?: string;
          email?: string;
          metadata?: Record<string, any>[];
          logoUrl?: string;
          tags?: string[];
        };
        loadBalancer?: string;
        timeout?: {
          callTimeout: number;  // required
        };
      };
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": Optional[str],
        "object": Literal["list"],
        "results": {
            "object": Literal["rerank"],
            "index": float,
            "relevance_score": float,
            "document": {  # optional
                "text": str,
            },
        },
        "usage": {  # optional
            "total_tokens": float,
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id?: string;
      object: string;
      results: {
        object: string;
        index: number;
        relevanceScore: number;
        document?: {
          text: string;
        };
      };
      usage?: {
        totalTokens: number;
      };
    }
    ```
  </CodeGroup>
</Expandable>