Migration to v1

​

Key API Changes

​

Module Imports and Class Renaming

• from semantic_router import RouteLayer → from semantic_router.routers import SemanticRouter The RouteLayer class has been renamed to SemanticRouter and moved to the routers module to better reflect its purpose and fit into the modular architecture.

​

Method Signatures

• SemanticRouter.add(route: Route) → SemanticRouter.add(routes: List[Route]) The add method now accepts a list of routes, making it easier to add multiple routes at once. However, it still supports adding a single route for backward compatibility.
  # Before
  route_layer = RouteLayer(encoder=encoder)
  route_layer.add(route1)
  route_layer.add(route2)
  
  # After
  semantic_router = SemanticRouter(encoder=encoder)
  semantic_router.add([route1, route2])  # Add multiple routes at once
  semantic_router.add(route3)  # Still works for a single route
  
• RouteLayer.retrieve_multiple_routes() → SemanticRouter.__call__(limit=None) or SemanticRouter.acall(limit=None) The retrieve_multiple_routes method has been removed. If you need similar functionality:
  • In versions 0.1.0-0.1.2: You can use the deprecated _semantic_classify_multiple_routes method
  • In version 0.1.3+ (0.1.5+ is recommended): Use the __call__ or acall methods with appropriate limit parameter.
  # Before (v0.0.x)
  route_layer = RouteLayer(encoder=encoder, routes=routes)
  multiple_routes = route_layer.retrieve_multiple_routes(query_text)
  
  # Transitional (v0.1.0-0.1.2)
  # Using deprecated method (not recommended)
  semantic_router = SemanticRouter(encoder=encoder, routes=routes, auto_sync="local")
  query_results = semantic_router._query(query_text)
  multiple_routes = semantic_router._semantic_classify_multiple_routes(query_results)
  
  # After (v0.1.3+)
  semantic_router = SemanticRouter(encoder=encoder, routes=routes, auto_sync="local")
  # Return all routes that pass their score thresholds
  all_routes = semantic_router(query_text, limit=None)
  # Or return top N routes that pass their score thresholds
  top_routes = semantic_router(query_text, limit=3)
  
  # To get scores for all routes regardless of threshold
  semantic_router.set_threshold(threshold=0.0)  # Set all route thresholds to 0
  all_route_scores = semantic_router(query_text, limit=None)
  
  When limit=1 (the default), a single RouteChoice object is returned. When limit=None or limit > 1, a list of RouteChoice objects is returned.

  Important Note About top_k: The top_k parameter (default: 5) can still limit the number of routes returned, regardless of the limit parameter. When using limit > 1, we recommend setting top_k to a higher value such as 100 or more. If you’re using limit=None to get all possible results, make sure to set top_k to be equal to or greater than the total number of utterances shared across all of your routes.

  # Example: Setting top_k higher when retrieving multiple routes
  semantic_router = SemanticRouter(encoder=encoder, routes=routes, top_k=100)
  all_routes = semantic_router(query_text, limit=None)
  

​

Synchronization Strategy

• If expecting routes to sync between local and remote on initialization, use SemanticRouter(..., auto_sync="local"). The auto_sync parameter provides control over how routes are synchronized between local and remote indexes. Read more about auto_sync and synchronization strategies. Available synchronization modes:
  • error: Raise an error if local and remote are not synchronized.
  • remote: Take remote as the source of truth and update local to align.
  • local: Take local as the source of truth and update remote to align.
  • merge-force-local: Merge both local and remote keeping local as the priority.
  • merge-force-remote: Merge both local and remote keeping remote as the priority.
  • merge: Merge both local and remote, with local taking priority for conflicts.
  # Example: Initialize with synchronization strategy
  semantic_router = SemanticRouter(
      encoder=encoder,
      routes=routes,
      index=PineconeIndex(...),
      auto_sync="local"  # Local routes will be used to update the remote index
  )
  

​

Other Important Changes

​

Router Configuration

from semantic_router.routers import RouterConfig

# Create configuration for your router
config = RouterConfig(
    routes=[route1, route2],
    encoder_type="openai",
    encoder_name="text-embedding-3-small"
)

# Initialize a router from config
semantic_router = SemanticRouter.from_config(config)

​

Advanced Router Options

• SemanticRouter: The standard router that replaces the old RouteLayer
• HybridRouter: A router that can combine dense and sparse embedding methods
• BaseRouter: An abstract base class for creating custom routers

​

Migration Example

# Before (v0.0.x)
from semantic_router import RouteLayer, Route
from semantic_router.encoders import OpenAIEncoder

route = Route(name="example", utterances=["sample utterance"])
layer = RouteLayer(encoder=OpenAIEncoder())
layer.add(route)
result = layer("query text")

# After (v0.1.x)
from semantic_router import Route
from semantic_router.routers import SemanticRouter
from semantic_router.encoders import OpenAIEncoder

route = Route(name="example", utterances=["sample utterance"])
router = SemanticRouter(encoder=OpenAIEncoder())
router.add(route)  # Still works for a single route
result = router("query text")