feat(async): Provide a new atop_n_routes() function for async contexts

Author: stronk7

README.md

@@ -49,6 +49,9 @@ router = SemanticRouter(config)
 # Start making queries (explore options in the SemanticRouter class)
 matches = router.top_n_routes(query="Hi!")
 
+# Or, for async contexts:
+matches = await router.atop_n_routes(query="Hi!")
+
 # Print the top matches (route, score, depth, leaf)
 [print(match) for match in matches]
 ```

asero/main.py

@@ -2,12 +2,13 @@
 #  SPDX-License-Identifier: BSD-3-Clause
 
 """Main module, demonstration purposes, for asero semantic router."""
+import asyncio
 
 from asero.config import get_config
 from asero.router import SemanticRouter
 
 
-def main():
+async def main():
     """Demonstrate the SemanticRouter functionality."""
     config = get_config()
     router = SemanticRouter(config)  # Defaults to router_example.yaml
@@ -17,8 +18,8 @@ def main():
     while True:
         try:
             print(f"Type a query to see top-{top} semantic routes (ctrl-C to exit):")
-            q = input("You: ").strip()
-            matches = router.top_n_routes(q, top_n=top)
+            q = (await asyncio.to_thread(input, "You: ")).strip()
+            matches = await router.atop_n_routes(q, top_n=top)
             print("")
             print(f"Query: {q}")
             print("Top nodes:")
@@ -33,4 +34,4 @@ def main():
 
 
 if __name__ == "__main__":
-    main()
+    asyncio.run(main())

asero/router.py

@@ -2,7 +2,7 @@
 #  SPDX-License-Identifier: BSD-3-Clause
 
 """Main asero semantic router classes."""
-
+import asyncio
 import logging
 import re
 
@@ -448,7 +448,7 @@ def top_n_routes(
         only_leaves: bool = True,
         allowed_paths: list[str] | None = None
     ) -> list[tuple[str, float, int, bool]]:
-        """For a given query, return the top-N most similar semantic routes in the hierarchy.
+        """Get (synchronously) for a given query, the top-N most similar semantic routes in the hierarchy.
 
         Args:
             query (str): User query string.
@@ -469,6 +469,28 @@ def top_n_routes(
             allowed_paths=allowed_paths,
         )
 
+    async def atop_n_routes(
+        self,
+        query: str,
+        top_n: int = 3,
+        only_leaves: bool = True,
+        allowed_paths: list[str] | None = None
+    ) -> list[tuple[str, float, int, bool]]:
+        """Get (asynchronously) for a given query, the top-N most similar semantic routes in the hierarchy.
+
+        Args:
+            query (str): User query string.
+            top_n (int): Number of top routes to return.
+            only_leaves (bool): If True, only return leaf nodes.
+            allowed_paths (list[str]): List of allowed paths to filter results.
+
+        Returns:
+            list[tuple[str, float, int, bool]]: List of tuples:
+                (route_path, similarity_score, depth, is_leaf)
+
+        """
+        return await asyncio.to_thread(self.top_n_routes, query, top_n, only_leaves, allowed_paths)
+
     def add_utterance(
         self,
         path: list[str],

pyproject.toml

@@ -28,6 +28,7 @@ dependencies = [
     "colorlog ~= 6.9.0",
     "numpy ~= 2.3.3",
     "openai ~= 1.106.1",
+    "python-dotenv ~= 1.1.1",
 ]
 
 [project.optional-dependencies]