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

# semantic_router.routers.base

#### is\_valid

```python theme={null}
def is_valid(layer_config: str) -> bool
```

Make sure the given string is json format and contains the 3 keys:
\["encoder\_name", "encoder\_type", "routes"]

## RouterConfig Objects

```python theme={null}
class RouterConfig()
```

Generates a RouterConfig object that can be used for initializing routers.

#### \_\_init\_\_

```python theme={null}
def __init__(routes: List[Route] = [],
             encoder_type: str = "openai",
             encoder_name: Optional[str] = None)
```

Initialize a RouterConfig object.

**Arguments**:

* `routes` (`List[Route]`): A list of routes.
* `encoder_type` (`str`): The type of encoder to use.
* `encoder_name` (`Optional[str]`): The name of the encoder to use.

#### from\_file

```python theme={null}
@classmethod
def from_file(cls, path: str) -> "RouterConfig"
```

Initialize a RouterConfig from a file. Expects a JSON or YAML file with file

extension .json, .yaml, or .yml.

**Arguments**:

* `path` (`str`): The path to the file to load the RouterConfig from.

#### from\_tuples

```python theme={null}
@classmethod
def from_tuples(cls,
                route_tuples: List[Tuple[str, str, Optional[List[Dict[str,
                                                                      Any]]],
                                         Dict[str, Any]]],
                encoder_type: str = "openai",
                encoder_name: Optional[str] = None)
```

Initialize a RouterConfig from a list of tuples of routes and

utterances.

**Arguments**:

* `route_tuples` (`List[Tuple[str, str]]`): A list of tuples, each containing a route name and an
  associated utterance.
* `encoder_type` (`str, optional`): The type of encoder to use, defaults to "openai".
* `encoder_name` (`Optional[str], optional`): The name of the encoder to use, defaults to None.

#### from\_index

```python theme={null}
@classmethod
def from_index(cls,
               index: BaseIndex,
               encoder_type: str = "openai",
               encoder_name: Optional[str] = None)
```

Initialize a RouterConfig from a BaseIndex object.

**Arguments**:

* `index` (`BaseIndex`): The index to initialize the RouterConfig from.
* `encoder_type` (`str, optional`): The type of encoder to use, defaults to "openai".
* `encoder_name` (`Optional[str], optional`): The name of the encoder to use, defaults to None.

#### to\_dict

```python theme={null}
def to_dict() -> Dict[str, Any]
```

Convert the RouterConfig to a dictionary.

**Returns**:

`Dict[str, Any]`: A dictionary representation of the RouterConfig.

#### to\_file

```python theme={null}
def to_file(path: str)
```

Save the routes to a file in JSON or YAML format.

**Arguments**:

* `path` (`str`): The path to save the RouterConfig to.

#### to\_utterances

```python theme={null}
def to_utterances() -> List[Utterance]
```

Convert the routes to a list of Utterance objects.

**Returns**:

`List[Utterance]`: A list of Utterance objects.

#### add

```python theme={null}
def add(route: Route)
```

Add a route to the RouterConfig.

**Arguments**:

* `route` (`Route`): The route to add.

#### get

```python theme={null}
def get(name: str) -> Optional[Route]
```

Get a route from the RouterConfig by name.

**Arguments**:

* `name` (`str`): The name of the route to get.

**Returns**:

`Optional[Route]`: The route if found, otherwise None.

#### remove

```python theme={null}
def remove(name: str)
```

Remove a route from the RouterConfig by name.

**Arguments**:

* `name` (`str`): The name of the route to remove.

#### get\_hash

```python theme={null}
def get_hash() -> ConfigParameter
```

Get the hash of the RouterConfig. Used for syncing.

**Returns**:

`ConfigParameter`: The hash of the RouterConfig.

#### xq\_reshape

```python theme={null}
def xq_reshape(xq: List[float] | np.ndarray) -> np.ndarray
```

Reshape the query vector to be a 2D numpy array.

**Arguments**:

* `xq` (`List[float] | np.ndarray`): The query vector.

**Returns**:

`np.ndarray`: The reshaped query vector.

## BaseRouter Objects

```python theme={null}
class BaseRouter(BaseModel)
```

Base class for all routers.

#### \_\_init\_\_

```python theme={null}
def __init__(encoder: Optional[DenseEncoder] = None,
             sparse_encoder: Optional[SparseEncoder] = None,
             llm: Optional[BaseLLM] = None,
             routes: Optional[List[Route]] = None,
             index: Optional[BaseIndex] = None,
             top_k: int = 5,
             aggregation: str = "mean",
             auto_sync: Optional[str] = None,
             init_async_index: bool = False)
```

Initialize a BaseRouter object. Expected to be used as a base class only,

not directly instantiated.

**Arguments**:

* `encoder` (`Optional[DenseEncoder]`): The encoder to use.
* `sparse_encoder` (`Optional[SparseEncoder]`): The sparse encoder to use.
* `llm` (`Optional[BaseLLM]`): The LLM to use.
* `routes` (`Optional[List[Route]]`): The routes to use.
* `index` (`Optional[BaseIndex]`): The index to use.
* `Optional[DenseEncoder]`0 (`Optional[DenseEncoder]`1): The number of routes to return.
* `Optional[DenseEncoder]`2 (`Optional[DenseEncoder]`3): The aggregation method to use.
* `Optional[DenseEncoder]`4 (`Optional[DenseEncoder]`5): The auto sync mode to use.

#### check\_for\_matching\_routes

```python theme={null}
def check_for_matching_routes(top_class: str) -> Optional[Route]
```

Check for a matching route in the routes list.

**Arguments**:

* `top_class` (`str`): The top class to check for.

**Returns**:

`Optional[Route]`: The matching route if found, otherwise None.

#### \_\_call\_\_

```python theme={null}
def __call__(text: Optional[str] = None,
             vector: Optional[List[float] | np.ndarray] = None,
             simulate_static: bool = False,
             route_filter: Optional[List[str]] = None,
             limit: int | None = 1) -> RouteChoice | List[RouteChoice]
```

Call the router to get a route choice.

**Arguments**:

* `text` (`Optional[str]`): The text to route.
* `vector` (`Optional[List[float] | np.ndarray]`): The vector to route.
* `simulate_static` (`bool`): Whether to simulate a static route.
* `route_filter` (`Optional[List[str]]`): The route filter to use.
* `limit` (`int | None`): The number of routes to return, defaults to 1. If set to None, no
  limit is applied and all routes are returned.

**Returns**:

`Optional[str]`0: The route choice.

#### acall

```python theme={null}
async def acall(
    text: Optional[str] = None,
    vector: Optional[List[float] | np.ndarray] = None,
    limit: int | None = 1,
    simulate_static: bool = False,
    route_filter: Optional[List[str]] = None
) -> RouteChoice | list[RouteChoice]
```

Asynchronously call the router to get a route choice.

**Arguments**:

* `text` (`Optional[str]`): The text to route.
* `vector` (`Optional[List[float] | np.ndarray]`): The vector to route.
* `simulate_static` (`bool`): Whether to simulate a static route (ie avoid dynamic route
  LLM calls during fit or evaluate).
* `route_filter` (`Optional[List[str]]`): The route filter to use.

**Returns**:

`RouteChoice`: The route choice.

#### sync

```python theme={null}
def sync(sync_mode: str, force: bool = False, wait: int = 0) -> List[str]
```

Runs a sync of the local routes with the remote index.

**Arguments**:

* `sync_mode` (`str`): The mode to sync the routes with the remote index.
* `force` (`bool, optional`): Whether to force the sync even if the local and remote
  hashes already match. Defaults to False.
* `wait` (`int`): The number of seconds to wait for the index to be unlocked
  before proceeding with the sync. If set to 0, will raise an error if
  index is already locked/unlocked.

**Returns**:

`List[str]`: A list of diffs describing the addressed differences between
the local and remote route layers.

#### async\_sync

```python theme={null}
async def async_sync(sync_mode: str,
                     force: bool = False,
                     wait: int = 0) -> List[str]
```

Runs a sync of the local routes with the remote index.

**Arguments**:

* `sync_mode` (`str`): The mode to sync the routes with the remote index.
* `force` (`bool, optional`): Whether to force the sync even if the local and remote
  hashes already match. Defaults to False.
* `wait` (`int`): The number of seconds to wait for the index to be unlocked
  before proceeding with the sync. If set to 0, will raise an error if
  index is already locked/unlocked.

**Returns**:

`List[str]`: A list of diffs describing the addressed differences between
the local and remote route layers.

#### from\_json

```python theme={null}
@classmethod
def from_json(cls, file_path: str)
```

Load a RouterConfig from a JSON file.

**Arguments**:

* `file_path` (`str`): The path to the JSON file.

**Returns**:

`RouterConfig`: The RouterConfig object.

#### from\_yaml

```python theme={null}
@classmethod
def from_yaml(cls, file_path: str)
```

Load a RouterConfig from a YAML file.

**Arguments**:

* `file_path` (`str`): The path to the YAML file.

**Returns**:

`RouterConfig`: The RouterConfig object.

#### from\_config

```python theme={null}
@classmethod
def from_config(cls, config: RouterConfig, index: Optional[BaseIndex] = None)
```

Create a Router from a RouterConfig object.

**Arguments**:

* `config` (`RouterConfig`): The RouterConfig object.
* `index` (`Optional[BaseIndex]`): The index to use.

#### add

```python theme={null}
def add(routes: List[Route] | Route)
```

Add a route to the local SemanticRouter and index.

**Arguments**:

* `route` (`Route`): The route to add.

#### aadd

```python theme={null}
async def aadd(routes: List[Route] | Route)
```

Add a route to the local SemanticRouter and index asynchronously.

**Arguments**:

* `route` (`Route`): The route to add.

#### update

```python theme={null}
def update(name: str,
           threshold: Optional[float] = None,
           utterances: Optional[List[str]] = None)
```

Updates the route specified in name. Allows the update of

threshold and/or utterances. If no values are provided via the
threshold or utterances parameters, those fields are not updated.
If neither field is provided raises a ValueError.

The name must exist within the local SemanticRouter, if not a
KeyError will be raised.

**Arguments**:

* `name` (`str`): The name of the route to update.
* `threshold` (`Optional[float]`): The threshold to update.
* `utterances` (`Optional[List[str]]`): The utterances to update.

#### delete

```python theme={null}
def delete(route_name: str)
```

Deletes a route given a specific route name.

**Arguments**:

* `route_name`: the name of the route to be deleted

#### adelete

```python theme={null}
async def adelete(route_name: str)
```

Deletes a route given a specific route name asynchronously.

**Arguments**:

* `route_name`: the name of the route to be deleted

#### is\_synced

```python theme={null}
def is_synced() -> bool
```

Check if the local and remote route layer instances are

synchronized.

**Returns**:

`bool`: True if the local and remote route layers are synchronized,
False otherwise.

#### async\_is\_synced

```python theme={null}
async def async_is_synced() -> bool
```

Check if the local and remote route layer instances are

synchronized asynchronously.

**Returns**:

`bool`: True if the local and remote route layers are synchronized,
False otherwise.

#### get\_utterance\_diff

```python theme={null}
def get_utterance_diff(include_metadata: bool = False) -> List[str]
```

Get the difference between the local and remote utterances. Returns

a list of strings showing what is different in the remote when compared
to the local. For example:

\["  route1: utterance1",
"  route1: utterance2",
"- route2: utterance3",
"- route2: utterance4"]

Tells us that the remote is missing "route2: utterance3" and "route2:
utterance4", which do exist locally. If we see:

\["  route1: utterance1",
"  route1: utterance2",
"+ route2: utterance3",
"+ route2: utterance4"]

This diff tells us that the remote has "route2: utterance3" and
"route2: utterance4", which do not exist locally.

**Arguments**:

* `include_metadata` (`bool`): Whether to include metadata in the diff.

**Returns**:

`List[str]`: A list of strings showing the difference between the local and remote
utterances.

#### aget\_utterance\_diff

```python theme={null}
async def aget_utterance_diff(include_metadata: bool = False) -> List[str]
```

Get the difference between the local and remote utterances asynchronously.

Returns a list of strings showing what is different in the remote when
compared to the local. For example:

\["  route1: utterance1",
"  route1: utterance2",
"- route2: utterance3",
"- route2: utterance4"]

Tells us that the remote is missing "route2: utterance3" and "route2:
utterance4", which do exist locally. If we see:

\["  route1: utterance1",
"  route1: utterance2",
"+ route2: utterance3",
"+ route2: utterance4"]

This diff tells us that the remote has "route2: utterance3" and
"route2: utterance4", which do not exist locally.

**Arguments**:

* `include_metadata` (`bool`): Whether to include metadata in the diff.

**Returns**:

`List[str]`: A list of strings showing the difference between the local and remote
utterances.

#### get

```python theme={null}
def get(name: str) -> Optional[Route]
```

Get a route by name.

**Arguments**:

* `name` (`str`): The name of the route to get.

**Returns**:

`Optional[Route]`: The route.

#### group\_scores\_by\_class

```python theme={null}
def group_scores_by_class(query_results: List[Dict]) -> Dict[str, List[float]]
```

Group the scores by class.

**Arguments**:

* `query_results` (`List[Dict]`): The query results to group. Expected format is a list of
  dictionaries with "route" and "score" keys.

**Returns**:

`Dict[str, List[float]]`: A dictionary of route names and their associated scores.

#### set\_threshold

```python theme={null}
def set_threshold(threshold: float, route_name: str | None = None)
```

Set the score threshold for a specific route or all routes. A `threshold` of 0.0

will mean that the route will be returned no matter how low it scores whereas
a threshold of 1.0 will mean that a route must contain an exact utterance match
to be returned.

**Arguments**:

* `threshold` (`float`): The threshold to set.
* `route_name` (`str | None`): The name of the route to set the threshold for. If None, the
  threshold will be set for all routes.

#### to\_config

```python theme={null}
def to_config() -> RouterConfig
```

Convert the router to a RouterConfig object.

**Returns**:

`RouterConfig`: The RouterConfig object.

#### to\_json

```python theme={null}
def to_json(file_path: str)
```

Convert the router to a JSON file.

**Arguments**:

* `file_path` (`str`): The path to the JSON file.

#### to\_yaml

```python theme={null}
def to_yaml(file_path: str)
```

Convert the router to a YAML file.

**Arguments**:

* `file_path` (`str`): The path to the YAML file.

#### get\_thresholds

```python theme={null}
def get_thresholds() -> Dict[str, float]
```

Get the score thresholds for each route.

**Returns**:

`Dict[str, float]`: A dictionary of route names and their associated thresholds.

#### fit

```python theme={null}
def fit(X: List[str],
        y: List[str],
        batch_size: int = 500,
        max_iter: int = 500,
        local_execution: bool = False)
```

Fit the router to the data. Works best with a large number of examples for each

route and with many `None` utterances.

**Arguments**:

* `X` (`List[str]`): The input data.
* `y` (`List[str]`): The output data.
* `batch_size` (`int`): The batch size to use for fitting.
* `max_iter` (`int`): The maximum number of iterations to use for fitting.
* `local_execution` (`X`0): Whether to execute the fitting locally.

#### evaluate

```python theme={null}
def evaluate(X: List[str], y: List[str], batch_size: int = 500) -> float
```

Evaluate the accuracy of the route selection.

**Arguments**:

* `X` (`List[str]`): The input data.
* `y` (`List[str]`): The output data.
* `batch_size` (`int`): The batch size to use for evaluation.

**Returns**:

`float`: The accuracy of the route selection.

#### threshold\_random\_search

```python theme={null}
def threshold_random_search(
        route_layer: BaseRouter,
        search_range: Union[int, float]) -> Dict[str, float]
```

Performs a random search iteration given a route layer and a search range.

**Arguments**:

* `route_layer` (`BaseRouter`): The route layer to search.
* `search_range` (`Union[int, float]`): The search range to use.

**Returns**:

`Dict[str, float]`: A dictionary of route names and their associated thresholds.