Merge pull request #569 from aurelio-labs/james/migration-doc2

feat: add note on top_k to migration doc

Author: jamescalam

docs/user-guide/guides/migration-to-v1.md

@@ -44,7 +44,7 @@ The v0.1 release of semantic router introduces several breaking changes to impro
   query_results = semantic_router._query(query_text)
   multiple_routes = semantic_router._semantic_classify_multiple_routes(query_results)
 
-  # After (v0.1.4+)
+  # 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)
@@ -59,6 +59,14 @@ The v0.1 release of semantic router introduces several breaking changes to impro
   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.
+  >
+  > ```python
+  > # 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")`.