Semantic router

Semantic router implementation with pluggable backends.

This module provides the SemanticRouter class, which is backend-agnostic and supports multiple semantic routing strategy through pluggable backends.

SemanticRouter(backend, default_route, valid_routes)

Bases: BaseRouter

A backend-agnostic router using semantic similarity.

This router delegates all routing logic to a pluggable backend implementation, supporting multiple semantic routing algorithms (Aurelio, Similarity-based, etc.).

The router provides a unified interface regardless of the underlying algorithm, allowing users to switch backends without changing their code.

Supported backends

1. BackendType.AURELIO: Aurelio Labs semantic router (via SemanticRouter.aurelio).
2. BackendType.NATIVE: Native GLLM semantic router (via SemanticRouter.native).

Attributes:

Name	Type	Description
backend	BaseAdapter	The backend implementation handling routing logic.
default_route	str	The default route to be used if no similar route is found.
valid_routes	set[str]	A set of valid routes for the router.

Initialize the SemanticRouter.

Parameters:

Name	Type	Description	Default
backend	BaseAdapter	The backend implementation for routing.	required
default_route	str	The default route to be used if no similar route is found.	required
valid_routes	set[str]	A set of valid routes for the router.	required

Raises:

Type	Description
ValueError	If backend is not a BaseAdapter instance.

aurelio(default_route, valid_routes, encoder, strategy=SemanticRouterStrategy.SIMILARITY, similarity_threshold=DEFAULT_SIMILARITY_THRESHOLD, route_examples=None, index=None, **kwargs) classmethod

Create semantic router with Aurelio backend similarity routing.

Uses Aurelio Labs semantic router for advanced semantic similarity routing. Supports custom encoders and vector store indexes.

Examples:

from gllm_inference.em_invoker import build_em_invoker
em_invoker = build_em_invoker("openai/text-embedding-3-small", credentials="sk-")
router = SemanticRouter.aurelio(
    default_route="general",
    valid_routes={"greeting", "help", "general"},
    encoder=em_invoker,
    route_examples={
        "greeting": ["hi", "hello", "hey"],
        "help": ["help me", "assist", "support"],
    }
)

Parameters:

Name	Type	Description	Default
default_route	str	Default route if no match found.	required
valid_routes	set[str]	Set of valid route names.	required
encoder	DenseEncoder | BaseEMInvoker	Dense encoder or EM invoker (required).	required
strategy	SemanticRouterStrategy	Routing strategy. Defaults to SIMILARITY.	SIMILARITY
similarity_threshold	float	Similarity threshold for routing. Defaults to DEFAULT_SIMILARITY_THRESHOLD.	DEFAULT_SIMILARITY_THRESHOLD
route_examples	dict[str, list[str | bytes]] | None	Route examples. Defaults to None.	None
index	BaseAurelioIndex | None	Custom vector store index. Defaults to None.	None
**kwargs	Any	Additional Aurelio-specific arguments (e.g., auto_sync).	{}

Returns:

Name	Type	Description
SemanticRouter	SemanticRouter	Initialized router instance.

Raise

ValueError: If strategy is not supported for Aurelio backend.

from_file(backend_type, strategy, file_path, default_route, valid_routes, **kwargs) classmethod

Create a new SemanticRouter instance from a file.

Parameters:

Name	Type	Description	Default
backend_type	BackendType	Type of backend (BackendType.AURELIO or BackendType.NATIVE).	required
strategy	SemanticRouterStrategy	Routing strategy (e.g., SIMILARITY).	required
file_path	str	The path to the file containing the routes. Must be JSON or YAML.	required
default_route	str	The default route to be used if no similar route is found.	required
valid_routes	set[str]	A set of valid routes for the router.	required
**kwargs	Any	Additional arguments for backend initialization (e.g., encoder, em_invoker).	{}

Returns:

Name	Type	Description
SemanticRouter	SemanticRouter	A new instance of the SemanticRouter class.

Raises:

Type	Description
ValueError

from_preset(backend, preset_name, modality=ModalityType.IMAGE, strategy=SemanticRouterStrategy.SIMILARITY, default_route=None, valid_routes=None, **kwargs) classmethod

Create router from preset configuration.

Uses the adapter's from_preset method to initialize the backend with preset route data, then wraps it in a SemanticRouter.

Examples:

router = SemanticRouter.from_preset(
    backend=BackendType.AURELIO,
    modality="image",
)

Args: backend (BackendType | str): Backend to use. Currently only BackendType.AURELIO (or the string "aurelio") is supported. preset_name (str): Name of the preset to use. modality (ModalityType | str, optional): Modality type for the preset. Defaults to ModalityType.IMAGE. strategy (SemanticRouterStrategy | None, optional): Routing strategy (e.g., SemanticRouterStrategy.SIMILARITY). Defaults to SemanticRouterStrategy.SIMILARITY. default_route (str | None, optional): Default route if no match found. If not provided, the first key of the preset routes is used. Defaults to None. valid_routes (set[str] | None, optional): Set of valid route names. If not provided, the keys of the preset routes are used. Defaults to None. **kwargs (Any): Backend and preset-specific arguments. May include encoder and routes.

Returns:

Name	Type	Description
SemanticRouter	SemanticRouter	Initialized router instance.

Raises:

Type	Description
ValueError	If the backend does not support preset initialization.

native(default_route, valid_routes, em_invoker, strategy=SemanticRouterStrategy.SIMILARITY, similarity_threshold=DEFAULT_SIMILARITY_THRESHOLD, route_examples=None, route_embeddings=None) classmethod

Create semantic router with native backend similarity routing.

Uses native gllm-inference cosine similarity for fast, simple routing. No training required. Best for small to medium-sized route sets.

Parameters:

Name	Type	Description	Default
default_route	str	Default route if no match found.	required
valid_routes	set[str]	Set of valid route names.	required
em_invoker	BaseEMInvoker	EM invoker for vectorization.	required
strategy	SemanticRouterStrategy	Routing strategy. Defaults to SemanticRouterStrategy.SIMILARITY.	SIMILARITY
similarity_threshold	float	Minimum similarity score (0-1). Defaults to DEFAULT_SIMILARITY_THRESHOLD.	DEFAULT_SIMILARITY_THRESHOLD
route_examples	dict[str, list[str]] | None	Route examples. Defaults to None.	None
route_embeddings	dict[str, list[list[float]]] | None	Route embeddings. Defaults to None.	None

Returns:

Name	Type	Description
SemanticRouter	SemanticRouter	Initialized router instance.

Examples:

from gllm_inference.em_invoker import build_em_invoker
em_invoker = build_em_invoker(...)
router = SemanticRouter.native(
    default_route="general",
    valid_routes={"greeting", "help", "general"},
    em_invoker=em_invoker,
    route_examples={
        "greeting": ["hi", "hello", "hey"],
        "help": ["help me", "assist", "support"],
    },
    similarity_threshold=0.7
)

Raise

ValueError: If strategy is not supported for Native backend.