​
is_valid

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

class RouterConfig()

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

​
__init__

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

@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

@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

@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

def to_dict() -> Dict[str, Any]

Convert the RouterConfig to a dictionary.

Returns:

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

​
to_file

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

def to_utterances() -> List[Utterance]

Convert the routes to a list of Utterance objects.

Returns:

List[Utterance]: A list of Utterance objects.

​
add

def add(route: Route)

Add a route to the RouterConfig.

Arguments:

  • route (Route): The route to add.

​
get

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

def remove(name: str)

Remove a route from the RouterConfig by name.

Arguments:

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

​
get_hash

def get_hash() -> ConfigParameter

Get the hash of the RouterConfig. Used for syncing.

Returns:

ConfigParameter: The hash of the RouterConfig.

​
xq_reshape

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

class BaseRouter(BaseModel)

Base class for all routers.

​
__init__

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

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__

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

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

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

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

@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

@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

@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

def add(routes: List[Route] | Route)

Add a route to the local SemanticRouter and index.

Arguments:

  • route (Route): The route to add.

​
aadd

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

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

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

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

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

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

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

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

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

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

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

def to_config() -> RouterConfig

Convert the router to a RouterConfig object.

Returns:

RouterConfig: The RouterConfig object.

​
to_json

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

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

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

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 (X0): Whether to execute the fitting locally.

​
evaluate

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.

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.