gllm-pipeline-binary 0.4.19__cp312-cp312-win_amd64.whl → 0.4.21__cp312-cp312-win_amd64.whl

gllm_pipeline/alias.pyi

@@ -1,5 +1,7 @@
 from gllm_pipeline.steps.pipeline_step import BasePipelineStep as BasePipelineStep
 from gllm_pipeline.types import Val as Val
+from typing import TypeAlias
 
-PipelineSteps = BasePipelineStep | list[BasePipelineStep]
-InputMapSpec = dict[str, str | Val] | list[str | dict[str, str] | dict[str, Val]]
+PipelineSteps: TypeAlias
+PipelineState: TypeAlias
+InputMapSpec: TypeAlias

gllm_pipeline/pipeline/pipeline.pyi

@@ -1,12 +1,15 @@
 from _typeshed import Incomplete
 from gllm_datastore.cache.cache import BaseCache as BaseCache
+from gllm_pipeline.alias import PipelineState as PipelineState
 from gllm_pipeline.exclusions import ExclusionManager as ExclusionManager, ExclusionSet as ExclusionSet
+from gllm_pipeline.pipeline.composer import Composer as Composer
 from gllm_pipeline.pipeline.states import RAGState as RAGState
 from gllm_pipeline.steps.pipeline_step import BasePipelineStep as BasePipelineStep
 from gllm_pipeline.steps.terminator_step import TerminatorStep as TerminatorStep
 from gllm_pipeline.utils.graph import create_edge as create_edge
 from gllm_pipeline.utils.mermaid import MERMAID_HEADER as MERMAID_HEADER, combine_mermaid_diagrams as combine_mermaid_diagrams, extract_step_diagrams as extract_step_diagrams
 from langgraph.graph import StateGraph
+from langgraph.graph.state import CompiledStateGraph as CompiledStateGraph
 from pydantic import BaseModel
 from typing import Any, TypedDict
 
@@ -102,10 +105,10 @@ class Pipeline:
         pipeline.exclusions.exclude("parallel_step.retrieval_b")  # Skip retrieval_b step
         ```
     '''
+    name: Incomplete
     steps: Incomplete
     recursion_limit: Incomplete
-    name: Incomplete
-    def __init__(self, steps: list[BasePipelineStep] | None = None, state_type: TypedDict | type[BaseModel] = ..., input_type: TypedDict | type[BaseModel] | None = None, output_type: TypedDict | type[BaseModel] | None = None, recursion_limit: int = 30, name: str | None = None, cache_store: BaseCache | None = None, cache_config: dict[str, Any] | None = None) -> None:
+    def __init__(self, steps: list[BasePipelineStep] | None = None, state_type: TypedDict | type[BaseModel] = ..., input_type: TypedDict | type[BaseModel] | None = None, output_type: TypedDict | type[BaseModel] | None = None, context_schema: TypedDict | type[BaseModel] | None = None, recursion_limit: int = 30, name: str | None = None, cache_store: BaseCache | None = None, cache_config: dict[str, Any] | None = None) -> None:
         '''Initializes the Pipeline with the given steps and state type.
 
         Args:
@@ -121,6 +124,8 @@ class Pipeline:
                 This state should be compatible with the pipeline\'s `state_type`.
                 Could be a TypedDict or a Pydantic BaseModel. Defaults to None, in which case the output state type
                 will be the same as the pipeline\'s `state_type`.
+            context_schema (TypedDict | type[BaseModel] | None, optional): The type of pipeline\'s runtime context.
+                Defaults to None, in which case no context schema will be used.
             recursion_limit (int, optional): The maximum number of steps allowed. Defaults to 30.
             name (str | None, optional): A name for this pipeline. Used when this pipeline is included as a subgraph.
                 Defaults to None, in which case the name will be "Subgraph" followed by a unique identifier.
@@ -194,17 +199,17 @@ class Pipeline:
         invalidating any built graph or compiled app. Useful for reusing a pipeline
         instance with different configurations.
         """
-    async def invoke(self, initial_state: dict[str, Any] | BaseModel, config: dict[str, Any] | None = None) -> dict[str, Any]:
+    async def invoke(self, initial_state: PipelineState, config: dict[str, Any] | None = None) -> dict[str, Any]:
         '''Runs the pipeline asynchronously with the given initial state and configuration.
 
         Args:
-            initial_state (dict[str, Any] | BaseModel): The initial state to start the pipeline with.
+            initial_state (PipelineState): The initial state to start the pipeline with.
                 This initial state should comply with the state type of the pipeline.
             config (dict[str, Any], optional): Additional configuration for the pipeline. User-defined config should not
                 have "langraph_" prefix as it should be reserved for internal use. Defaults to None.
 
         Returns:
-            dict[str, Any] | BaseModel: The final state after the pipeline execution.
+            dict[str, Any]: The final state after the pipeline execution.
                 If \'debug_state\' is set to True in the config, the state logs will be included
                 in the final state with the key \'__state_logs__\'.
 

gllm_pipeline/router/__init__.pyi

@@ -0,0 +1,6 @@
+from gllm_pipeline.router.aurelio_semantic_router import AurelioSemanticRouter as AurelioSemanticRouter
+from gllm_pipeline.router.lm_based_router import LMBasedRouter as LMBasedRouter
+from gllm_pipeline.router.rule_based_router import RuleBasedRouter as RuleBasedRouter
+from gllm_pipeline.router.similarity_based_router import SimilarityBasedRouter as SimilarityBasedRouter
+
+__all__ = ['AurelioSemanticRouter', 'LMBasedRouter', 'RuleBasedRouter', 'SimilarityBasedRouter']

gllm_pipeline/router/aurelio_semantic_router/__init__.pyi

@@ -0,0 +1,3 @@
+from gllm_pipeline.router.aurelio_semantic_router.aurelio_semantic_router import AurelioSemanticRouter as AurelioSemanticRouter
+
+__all__ = ['AurelioSemanticRouter']

gllm_pipeline/router/aurelio_semantic_router/aurelio_semantic_router.pyi

@@ -0,0 +1,86 @@
+from _typeshed import Incomplete
+from gllm_pipeline.router.aurelio_semantic_router.bytes_compat_route import BytesCompatRoute as BytesCompatRoute
+from gllm_pipeline.router.aurelio_semantic_router.index.aurelio_index import BaseAurelioIndex as BaseAurelioIndex
+from gllm_pipeline.router.preset.preset_loader import get_preset as get_preset
+from gllm_pipeline.router.router import BaseRouter as BaseRouter
+from semantic_router import Route
+from semantic_router.encoders.base import DenseEncoder as DenseEncoder
+from typing import Any
+
+manager: Incomplete
+logger: Incomplete
+semantic_router_logger: Incomplete
+
+class AurelioSemanticRouter(BaseRouter):
+    """A router that utilizes the Aurelio Labs library to route the input source to the appropriate path.
+
+    The `AurelioSemanticRouter` utilizes the Aurelio Labs library to route a given input source to an appropriate path
+    based on the similarity with existing samples. If the determined route is not valid, it defaults to a predefined
+    route.
+
+    Attributes:
+        route_layer (RouteLayer): The Aurelio Labs route layer that handles the routing logic.
+        default_route (str): The default route to be used if the input source is not similar to any of the routes.
+        valid_routes (set[str]): A set of valid routes for the router.
+
+    Notes:
+        For more information about the Aurelio Labs library, please refer to
+        https://github.com/aurelio-labs/semantic-router
+    """
+    route_layer: Incomplete
+    def __init__(self, default_route: str, valid_routes: set[str], encoder: DenseEncoder, routes: list[Route] | dict[str, list[str | bytes]] | None = None, index: BaseAurelioIndex | None = None, auto_sync: str = ..., **kwargs: Any) -> None:
+        '''Initializes a new instance of the AurelioSemanticRouter class.
+
+        To define the routes, at least one of the `routes` or `index` parameters must be provided.
+        When both parameters are provided, the `routes` parameter is ignored.
+
+        Args:
+            default_route (str): The default route to be used if the input source is not similar to any of the routes.
+            valid_routes (set[str]): A set of valid routes for the router.
+            encoder (DenseEncoder): An Aurelio Labs dense encoder to encode the input source and the samples.
+                The encoded vectors are used to calculate the similarity between the input source and the samples.
+            routes (list[Route] | dict[str, list[str | bytes]] | None, optional): A list of Aurelio Labs Routes
+                or a dictionary mapping route names to the list of samples. Ignored if `index` is provided.
+                Defaults to None.
+            index (BaseAurelioIndex | None, optional): A router index to retrieve the routes.
+                If provided, it is prioritized over `routes`. Defaults to None.
+            auto_sync (str, optional): The auto-sync mode for the router. Defaults to "local".
+            kwargs (Any): Additional keyword arguments to be passed to the Aurelio Labs Route Layer.
+
+        Raises:
+            ValueError:
+                1. If neither `routes` nor `index` is provided.
+                2. If the parsed routes contains routes that are not in the set of valid routes.
+                3. If the provided default route is not in the set of valid routes.
+        '''
+    @classmethod
+    def from_preset(cls, modality: str, preset_name: str, preset_kwargs: dict | None = None, **kwargs) -> AurelioSemanticRouter:
+        """Initialize the Aurelio semantic based router component using preset model configurations.
+
+        Args:
+            modality (str): type of modality input.
+            preset_name (str): Name of the preset to use.
+            preset_kwargs (dict | None): placeholder for preset additional arguments.
+            **kwargs (Any): Additional arguments to pass for this class.
+
+        Returns:
+            AurelioSemanticRouter: Initialized aurelio semantic based router component using preset model.
+        """
+    @classmethod
+    def from_file(cls, default_route: str, valid_routes: set[str], file_path: str) -> AurelioSemanticRouter:
+        '''Creates a new instance of the AurelioSemanticRouter class from a file.
+
+        This method creates a new instance of the AurelioSemanticRouter class from a file. It supports JSON and YAML
+        file extensions.
+
+        Args:
+            default_route (str): The default route to be used if the input source is not similar to any of the routes.
+            valid_routes (set[str]): A set of valid routes for the router.
+            file_path (str): The path to the file containing the routes. The file extension must be either JSON or YAML.
+
+        Returns:
+            AurelioSemanticRouter: A new instance of the AurelioSemanticRouter class.
+
+        Raises:
+            ValueError: If the file extension is not ".json" or ".yaml".
+        '''

gllm_pipeline/router/aurelio_semantic_router/bytes_compat_route.pyi

@@ -0,0 +1,40 @@
+from gllm_pipeline.router.utils import encode_bytes as encode_bytes
+from semantic_router.route import Route
+from typing import Any
+
+class BytesCompatRoute(Route):
+    """A subclass of `Route` that provides JSON-serializable support for `bytes` in utterances.
+
+    The primary motivation for this override is to prevent errors when `bytes`-based utterances are hashed
+    during `semantic_router.routers.base.BaseRouter._write_hash`.
+
+    `ByteCompatRoute` extends the standard `Route` class from the `semantic-router` library by ensuring that
+    all `bytes` values in the `utterances` field are safely encoded using base64 when converting to a dictionary.
+    This is essential for serializing routes containing binary data to formats like JSON, which does not
+    support raw bytes.
+
+    Use this class as a drop-in replacement when dealing with routes that include `bytes`-based utterances but still
+    need to be serialized (e.g., for configuration exports or caching).
+    """
+    def to_dict(self) -> dict[str, Any]:
+        '''Convert the route instance to a dictionary with all `bytes` in the `utterances`.
+
+        This overrides the default `Route.to_dict()` to handle nested `bytes` inside lists or dictionaries.
+
+        Returns:
+            dict[str, Any]: A dictionary representation of the route, with all `bytes` values in `utterances`
+            converted to base64-encoded UTF-8 strings.
+
+        Example:
+            >>> route = ByteCompatRoute(name="example", utterances=[b"binary1", "text"])
+            >>> route.to_dict()
+            {
+                "name": "example",
+                "utterances": ["YmluYXJ5MQ==", "text"],
+                ...
+            }
+
+        Notes:
+            - Only the `utterances` field is altered for byte safety; other fields remain untouched.
+            - If the utterances contain nested lists or dicts with bytes, they will be recursively encoded.
+        '''

gllm_pipeline/router/aurelio_semantic_router/encoders/__init__.pyi

@@ -0,0 +1,5 @@
+from gllm_pipeline.router.aurelio_semantic_router.encoders.em_invoker_encoder import EMInvokerEncoder as EMInvokerEncoder
+from gllm_pipeline.router.aurelio_semantic_router.encoders.langchain_encoder import LangchainEmbeddingsEncoder as LangchainEmbeddingsEncoder
+from gllm_pipeline.router.aurelio_semantic_router.encoders.tei_encoder import TEIEncoder as TEIEncoder
+
+__all__ = ['TEIEncoder', 'LangchainEmbeddingsEncoder', 'EMInvokerEncoder']

gllm_pipeline/router/aurelio_semantic_router/encoders/em_invoker_encoder.pyi

@@ -0,0 +1,46 @@
+from gllm_inference.em_invoker.em_invoker import BaseEMInvoker as BaseEMInvoker
+from semantic_router.encoders.base import DenseEncoder
+from typing import Any
+
+class EMInvokerEncoder(DenseEncoder):
+    """The gllm-inference EM Invoker-compatible Encoder.
+
+    This encoder is for use with gllm-inference's EM Invokers.
+    Includes handling of synchronous cases, since gllm-inference's EM Invokers are asynchronous.
+
+    Attributes:
+        name (str): The name of the encoder.
+        score_threshold (float): The score threshold for the encoder.
+    """
+    def __init__(self, em_invoker: BaseEMInvoker, name: str = 'em-invoker-encoder', score_threshold: float = 0.0) -> None:
+        '''Initialize the EM Invoker Encoder.
+
+        Args:
+            em_invoker (BaseEMInvoker): The EM Invoker to use.
+            name (str, optional): The name of the encoder. Defaults to "em-invoker-encoder".
+            score_threshold (float, optional): The score threshold for the encoder. Defaults to 0.0.
+        '''
+    def __call__(self, docs: list[Any]) -> list[list[float]]:
+        """Call the EM Invoker.
+
+        Handles both async and sync contexts by checking for existing event loop.
+        If an event loop is not found, we run the invoke method in the current thread.
+        If an event loop is found, we run the invoke method in a thread pool.
+        In the case of a RuntimeError, we run the invoke method in the current thread.
+
+        Args:
+            docs (list[Any]): List of documents to be embedded.
+
+        Returns:
+            list[list[float]]: List of embeddings for each document.
+        """
+    async def acall(self, docs: list[Any], **kwargs: Any) -> list[list[float]]:
+        """Call the EM Invoker, which is already an async function.
+
+        Args:
+            docs (list[Any]): List of documents to be embedded.
+            **kwargs (Any): Additional keyword arguments. Not used, but required by the DenseEncoder interface.
+
+        Returns:
+            list[list[float]]: List of embeddings for each document.
+        """

gllm_pipeline/router/aurelio_semantic_router/encoders/langchain_encoder.pyi

@@ -0,0 +1,50 @@
+from langchain_core.embeddings import Embeddings as Embeddings
+from semantic_router.encoders.base import DenseEncoder
+from typing import Any
+
+class LangchainEmbeddingsEncoder(DenseEncoder):
+    """A wrapper encoder for LangChain-compatible embedding models.
+
+    This encoder adapts any LangChain-compatible Embeddings instance to the
+    Semantic Router interface by wrapping its `embed_documents` and `aembed_documents` methods.
+
+    It supports both synchronous and asynchronous embedding calls and is useful
+    when integrating LangChain embeddings with a semantic router pipeline.
+
+    Attributes:
+        name (str): The name of the encoder.
+        score_threshold (float): Threshold for similarity scoring.
+    """
+    def __init__(self, embeddings: Embeddings, name: str = 'langchain-embeddings-encoder', score_threshold: float = 0.5) -> None:
+        '''Initialize the LangchainEmbeddingsEncoder.
+
+        Args:
+            embeddings (Embeddings): A LangChain-compatible Embeddings instance.
+            name (str, optional): Identifier for the encoder. Defaults to "langchain-embeddings-encoder".
+            score_threshold (float, optional): Minimum similarity score to consider matches. Defaults to 0.5.
+        '''
+    def __call__(self, docs: list[Any]) -> list[list[float]]:
+        """Synchronously embed a list of documents.
+
+        Automatically handles execution context:
+        1. If called inside an active asyncio loop, it runs the embedding call in a background thread.
+        2. If no active loop is present, it runs the embedding call normally.
+        3. If an event loop cannot be retrieved, falls back to `asyncio.run`.
+
+        Args:
+            docs (list[Any]): The documents to embed.
+
+        Returns:
+            list[list[float]]: A list of vector embeddings for each document.
+        """
+    async def acall(self, docs: list[Any]) -> list[list[float]]:
+        """Asynchronously embed a list of documents.
+
+        Calls the `aembed_documents` method of the underlying LangChain embeddings.
+
+        Args:
+            docs (list[Any]): The documents to embed.
+
+        Returns:
+            list[list[float]]: A list of vector embeddings for each document.
+        """

gllm_pipeline/router/aurelio_semantic_router/encoders/tei_encoder.pyi

@@ -0,0 +1,49 @@
+from semantic_router.encoders.huggingface import HFEndpointEncoder
+from typing import Any
+
+class TEIEncoder(HFEndpointEncoder):
+    """TEI Endpoint Encoder.
+
+    This encoder is used to encode documents into embeddings using the TEI endpoint.
+
+    Attributes:
+        name (str): The name of the encoder.
+        huggingface_url (str): The base URL of the TEI endpoint, which is a HuggingFace endpoint.
+        huggingface_api_key (str): The API key for the TEI endpoint.
+        score_threshold (float): The score threshold for the encoder.
+    """
+    def __init__(self, base_url: str, name: str = 'tei-encoder', api_key: str = '<empty>', score_threshold: float = 0.0) -> None:
+        '''Initialize the TEI Endpoint Encoder.
+
+        Args:
+            base_url (str): The base URL of the TEI endpoint, which is a HuggingFace endpoint.
+            name (str, optional): The name of the encoder. Defaults to "tei-encoder".
+            api_key (str, optional): The API key for the TEI endpoint. Defaults to "<empty>".
+                Only do this if the endpoint does not require an API key.
+            score_threshold (float, optional): The score threshold for the encoder. Defaults to 0.0.
+        '''
+    async def acall(self, docs: list[str], **kwargs: Any) -> list[list[float]]:
+        """Asynchronously encodes a list of documents into embeddings.
+
+        Args:
+            docs (list[str]): A list of documents to encode.
+            **kwargs (Any): Additional keyword arguments. Not used, but required by the BaseEncoder interface.
+
+        Returns:
+            list[list[float]]: A list of embeddings for the given documents.
+
+        Raises:
+            ValueError: If no embeddings are returned for a document.
+        """
+    def __call__(self, docs: list[str]) -> list[list[float]]:
+        """Encodes a list of documents into embeddings using the Hugging Face API.
+
+        Args:
+            docs (list[str]): A list of documents to encode.
+
+        Returns:
+            list[list[float]]: A list of embeddings for the given documents.
+
+        Raises:
+            ValueError: If no embeddings are returned for a document.
+        """

gllm_pipeline/router/aurelio_semantic_router/index/__init__.pyi

@@ -0,0 +1,4 @@
+from gllm_pipeline.router.aurelio_semantic_router.index.azure_ai_search_aurelio_index import AzureAISearchAurelioIndex as AzureAISearchAurelioIndex
+from gllm_pipeline.router.aurelio_semantic_router.index.vector_store_adapter_index import VectorStoreAdapterIndex as VectorStoreAdapterIndex
+
+__all__ = ['AzureAISearchAurelioIndex', 'VectorStoreAdapterIndex']

gllm_pipeline/router/aurelio_semantic_router/index/aurelio_index.pyi

@@ -0,0 +1,65 @@
+import abc
+import numpy as np
+from abc import ABC, abstractmethod
+from semantic_router.index import BaseIndex
+from typing import Any
+
+class BaseAurelioIndex(BaseIndex, ABC, metaclass=abc.ABCMeta):
+    """An abstract base class for the router index to be loaded by the AurelioSemanticRouter.
+
+    The `BaseAurelioIndex` extends the `BaseIndex` class from the semantic router library.
+    It can be used as a base class for a router index implementation that can be used with the assumption that
+    the routes are already in the index. Therefore, the index will solely be used for retrieval purposes.
+
+    Attributes:
+        sync (bool): Flag to indicate that the index should be synchronized with the routes mapping.
+            In this implementation, it's set to `True` by default to make sure that the RouteLayer object initialized
+            with this index will perform the syncing process instead of blindly adding the routes to the index.
+
+    Notes:
+        To use this class, you need to implement the `get_routes` and `query` methods:
+        1. `get_routes`: Retrieve a list of routes and their associated utterances from the index.
+        2. `query`: Search the index for the query_vector and return top_k results.
+    """
+    sync: bool
+    @abstractmethod
+    def get_routes(self) -> dict[str, list[str]]:
+        """Retrieves a dictionary of routes and their associated utterances from the index.
+
+        Returns:
+            dict[str, list[str]]: A dictionary where the key is the route name and the value is a list of utterances.
+
+        Raises:
+            NotImplementedError: If the method is not implemented by the subclass.
+        """
+    @abstractmethod
+    def query(self, vector: np.ndarray, top_k: int = 5, route_filter: list[str] | None = None) -> tuple[np.ndarray, list[str]]:
+        """Search the index with the input query vector and return top_k results.
+
+        Args:
+            vector (np.ndarray): The input vector to query.
+            top_k (int, optional): The number of results to return. Defaults to 5.
+            route_filter (list[str] | None, optional): The list of routes to filter the results by. Defaults to None.
+
+        Returns:
+            tuple[np.ndarray, list[str]]: A tuple containing the query vector and the list of results.
+
+        Raises:
+            NotImplementedError: If the method is not implemented by the subclass.
+        """
+    def add(self, embeddings: list[list[float]], routes: list[str], utterances: list[Any], function_schemas: list[dict[str, Any]] | None = None, metadata_list: list[dict[str, Any]] | None = None) -> None:
+        """Add embeddings to the index.
+
+        This method doesn't need to add any routes to the index since it's assumed that the routes are already in
+        the index. Therefore, this method is left empty intentionally.
+
+        Args:
+            embeddings (list[list[float]]): A list of embedded vectors for the documents.
+            routes (list[str]): A list of route names for the documents.
+            utterances (list[Any]): A list of utterances for the documents.
+            function_schemas (list[dict[str, Any]]): List of function schemas to add to the index.
+            metadata_list (list[dict[str, Any]]): List of metadata to add to the index.
+
+        Returns:
+            None
+        """

gllm_pipeline/router/aurelio_semantic_router/index/azure_ai_search_aurelio_index.pyi

@@ -0,0 +1,71 @@
+import numpy as np
+from azure.search.documents import SearchClient
+from gllm_pipeline.router.aurelio_semantic_router.index.aurelio_index import BaseAurelioIndex as BaseAurelioIndex
+
+class AzureAISearchAurelioIndexConstants:
+    """Defines Azure AI Search Aurelio index related constants."""
+    CONTENT_FIELD: str
+    SCORE_FIELD: str
+    VECTOR_FIELD: str
+    VECTOR_SEARCH_TYPE: str
+
+class AzureAISearchAurelioIndexDefaults:
+    """Defines default values for the AzureAISearchAurelioIndex class."""
+    ROUTE_FIELD_NAME: str
+    MAX_TOP_K: int
+    MAX_SEARCH_ITERATIONS: int
+
+class AzureAISearchAurelioIndex(BaseAurelioIndex):
+    """A router index implementation for Azure AI Search to be used by the AurelioSemanticRouter.
+
+    The `AzureAISearchAurelioIndex` class extends the `BaseAurelioIndex` class. It allows an Azure AI Search index to be
+    used as a router index by the `AurelioSemanticRouter` class. Just like the `BaseAurelioIndex` class, this class also
+    assumes that the routes are already in the index. Therefore, the index will solely be used for retrieval purposes.
+
+    Attributes:
+        client (SearchClient | None): The client to interact with the Azure AI Search index.
+        route_field_name (str): The name of the field that contains the route name.
+        max_top_k (int): The maximum number of results to return.
+        max_search_iterations (int): The maximum number of search iterations to perform.
+        sync (bool): Flag to indicate that the index should be synchronized with the routes mapping.
+            In this implementation, it's set to `True` by default to make sure that the RouteLayer object initialized
+            with this index will perform the syncing process instead of blindly adding the routes to the index.
+    """
+    client: SearchClient | None
+    route_field_name: str
+    max_top_k: int
+    max_search_iterations: int
+    def __init__(self, endpoint: str, index_name: str, api_key: str, route_field_name: str = ..., max_top_k: int = ..., max_search_iterations: int = ...) -> None:
+        """Initialize the AzureAISearchIndex with the given service endpoint, index name, and API key.
+
+        Args:
+            endpoint (str): The endpoint of the Azure AI Search service.
+            index_name (str): The name of the Azure AI Search index.
+            api_key (str): The API key for the Azure AI Search service.
+            route_field_name (str, optional): The name of the field that contains the route name.
+                Defaults to AzureAISearchAurelioIndexDefaults.ROUTE_FIELD_NAME.
+            max_top_k (int, optional): The maximum number of results to return.
+                Defaults to AzureAISearchAurelioIndexDefaults.MAX_TOP_K.
+            max_search_iterations (int, optional): The maximum number of search iterations to perform.
+                Defaults to AzureAISearchAurelioIndexDefaults.MAX_SEARCH_ITERATIONS.
+
+        Returns:
+            None
+        """
+    def get_routes(self) -> dict[str, list[str]]:
+        """Retrieves a dictionary of routes and their associated utterances from the Azure AI Search index.
+
+        Returns:
+            dict[str, list[str]]: A dictionary where the key is the route name and the value is a list of utterances.
+        """
+    def query(self, vector: np.ndarray, top_k: int = 5, route_filter: list[str] | None = None) -> tuple[np.ndarray, list[str]]:
+        """Search the Azure AI Search index with the input query vector and return top_k results.
+
+        Args:
+            vector (np.ndarray): The input vector to query.
+            top_k (int, optional): The number of results to return. Defaults to 5.
+            route_filter (list[str] | None, optional): The list of routes to filter the results by. Defaults to None.
+
+        Returns:
+            tuple[np.ndarray, list[str]]: A tuple containing the query vector and the list of results.
+        """

gllm_pipeline/router/aurelio_semantic_router/index/vector_store_adapter_index.pyi

@@ -0,0 +1,119 @@
+import numpy as np
+from gllm_datastore.vector_data_store.vector_data_store import BaseVectorDataStore as BaseVectorDataStore
+from gllm_pipeline.router.aurelio_semantic_router.index.aurelio_index import BaseAurelioIndex as BaseAurelioIndex
+from gllm_pipeline.router.utils import encode_bytes as encode_bytes
+from semantic_router import Route
+from typing import Any, Callable, TypeVar
+
+ROUTE_PAYLOAD_KEY: str
+UTTERANCE_PAYLOAD_KEY: str
+T = TypeVar('T')
+
+class VectorStoreAdapterIndex(BaseAurelioIndex):
+    """A vector store-backed implementation of BaseAurelioIndex for use with AurelioSemanticRouter.
+
+    This index performs similarity search over a backend vector store to retrieve relevant
+    route payloads. The vector store must implement the BaseVectorDataStore interface and support
+    async methods for querying by vector and filtering by metadata.
+    """
+    index: BaseVectorDataStore
+    def __init__(self, index: BaseVectorDataStore, **kwargs: Any) -> None:
+        """Initialize the VectorStoreAdapterIndex.
+
+        Args:
+            index (BaseVectorDataStore): The vector store instance used for retrieval.
+            **kwargs: Additional keyword arguments forwarded to the BaseAurelioIndex.
+        """
+    def __len__(self) -> int:
+        """Returns the total number of vectors in the index.
+
+        If the index is not initialized returns 0.
+
+        Returns:
+            int: The total number of vectors.
+        """
+    def add(self, routes: list[str], utterances: list[str | bytes], **_):
+        """Add route-utterance pairs into the vector store.
+
+        Each utterance is associated with its route and encoded as a Chunk. Binary strings
+        are automatically base64-encoded for safe storage.
+
+        Args:
+            routes (list[str]): List of route identifiers.
+            utterances (list[str | bytes]): List of utterance strings or bytes.
+            **_: Ignored. Included for interface compatibility.
+
+        Raises:
+            AssertionError: If `routes` and `utterances` have different lengths.
+        """
+    def get_routes(self) -> dict[str, list]:
+        """Retrieve all routes and their corresponding utterances from the vector store.
+
+        Returns:
+            dict[str, list]: A dictionary where each key is a route and the value is a
+            list of associated utterance strings.
+        """
+    def query(self, vector: np.ndarray, top_k: int = 5, route_filter: list[str] | None = None, retrieval_params: dict | None = None) -> tuple[np.ndarray, list[str]]:
+        """Perform a similarity query using the provided vector, optionally filtering by route.
+
+        Args:
+            vector (np.ndarray): Query vector to search against stored vectors.
+            top_k (int, optional): Maximum number of top matching results to return. Defaults to 5.
+            route_filter (list[str] | None, optional): Optional list of route names to filter
+                the search results by. If None, all routes are considered.
+            retrieval_params (dict | None, optional): Filter parameters to narrow the search. Defaults to None.
+
+        Returns:
+            tuple[np.ndarray, list[str]]: A tuple containing:
+                - A NumPy array of similarity scores.
+                - A list of corresponding route names for each match.
+        """
+    def is_ready(self):
+        """Checks if the index is ready to be used.
+
+        This is a mandatory method to be implemented from `BaseIndex`.
+
+        Returns:
+            bool: True if the index has one or more vectors; False otherwise.
+        """
+    async def ais_ready(self) -> None:
+        """Checks if the index is ready to be used in async.
+
+        Returns:
+            bool: True if the index has one or more vectors; False otherwise.
+        """
+    def load_routes_from_json(self, file_path: str, transform_utterance: Callable[[str], str | bytes] | None = None):
+        """Load route-utterance pairs from a JSON file and insert them into the vector store.
+
+        The JSON file must contain a dictionary mapping route names to lists of utterances.
+        Each utterance can optionally be transformed before storage.
+
+        Args:
+            file_path (str): Path to a `.json` file containing routes and utterances.
+            transform_utterance (Callable[[str], str | bytes] | None): Optional function to
+                preprocess each utterance before storage. Must return `str` or `bytes`.
+
+        Raises:
+            ValueError: If the provided file is not a JSON file.
+        """
+    def load_routes_from_dict(self, routes: list[Route] | dict[str, list[str | bytes]], transform_utterance: Callable[[str], str | bytes] | None = None):
+        """Load route-utterance pairs from a list of `Route` or a dictionary and insert into the vector store.
+
+        This method supports two input formats:
+            1. A list of `Route` objects from `semantic_router`, where each route has a `name` and `utterances`.
+            2. A dictionary mapping route names (str) to lists of utterances (list[str]).
+
+        Optionally, a `transform_utterance` function can be provided to process each utterance before storage.
+        Utterances can be any type; use `transform_utterance` to ensure the final result is str or bytes.
+
+        Args:
+            routes (list[Route] | dict[str, list]): Route data in either list or dictionary format.
+            transform_utterance (Callable[[str], str | bytes] | None): Optional function to transform
+                each utterance before storage. Must return `str` or `bytes`.
+
+        Raises:
+            ValueError: If `routes` is not a list of `Route` objects or a dictionary,
+                if route names are invalid,
+                if utterances are not lists of non-empty strings,
+                or if transformed utterances are not `str` or `bytes`.
+        """