Repository navigation
Commit a58e68f
authored
feat(router): add async aroute and aroute_many to SemanticRouter (redis#784)
## Motivation
Closes redis#783.
`SemanticRouter` had no async query path, so routing from async apps
(LangGraph nodes, FastAPI handlers, MCP servers) blocked the event loop
twice per call: on the embedding and on the `FT.AGGREGATE` round trip.
`SemanticCache` already has async lookups; the router had none.
## Changes
### `aroute()` and `aroute_many()`
Async counterparts of `router(...)` and `route_many(...)`. They embed
with `vectorizer.aembed` and run the same aggregate request on an
`AsyncSearchIndex` over the same index, so they return exactly what the
sync methods return. Everything after `vector` is keyword-only, so a
positional `distance_threshold` (deprecated in `route_many`) can't be
read as an aggregation method.
- `_get_route_matches` is split into request building
(`_route_matches_request`) and row processing
(`_route_matches_from_result`), shared by the sync and async paths so
the two cannot drift. `_build_aggregate_request` is untouched, so this
does not collide with redis#766.
- The async index is created on first use (same pattern as
`SemanticCache`), derived from the sync `SearchIndex`: when the sync
index owns its client and has a URL, the async index connects from that
URL, connection kwargs and `lib_name`; otherwise the caller's client is
converted with `RedisConnectionFactory.sync_to_async_redis`.
`from_existing(redis_url=...)` builds an owned client from the URL, so
it takes the URL branch too.
- `adisconnect()` closes the async connection; `aindex` exposes the
async index (None before first use).
- Mutating methods (`add_route`, `remove_route`, ...) stay sync to keep
the change small.
## Release Notes
`SemanticRouter` gains `aroute()`, `aroute_many()`, `adisconnect()` and
an `aindex` property. The async index is created on first use. Routers
given an SSL, unix-socket, Sentinel or `RedisCluster` client can't
convert it to async; pass `redis_url` to the router for async routing in
those setups. Vectorizers without a native `aembed` (e.g. the default
`HFTextVectorizer`) still embed synchronously; the Redis call is
non-blocking either way. The async client is bound to the event loop
that made the first call; call `adisconnect()` before switching loops.
## Reviewer Brief
**Start here:** `redisvl/extensions/router/semantic.py`,
`_get_async_index`. It decides how the async index reaches Redis, and
every `aroute` / `aroute_many` call goes through it.
**Where it could fail**
- `redisvl/extensions/router/semantic.py:557`: the URL branch is taken
only when the sync index owns its client *and* has a URL. Check that a
router built with `redis_client=` plus `redis_url=` (both given)
converts the client rather than connecting from the URL, since the
client is what the sync path uses.
- `redisvl/extensions/router/semantic.py:567`: the client-conversion
branch raises on the first async call for SSL, unix-socket, Sentinel and
Cluster clients (`sync_to_async_redis` limitation, pre-existing). The
docstrings say to pass `redis_url` instead; nothing prevents the
mismatch at construction.
**Not verified:** cluster mode (async path unsupported for
`RedisCluster` clients); non-blocking embedding with a native-async
vectorizer (the tests use `HFTextVectorizer`, which embeds
synchronously, so only the Redis call is exercised async); Redis < 7
error mapping (shared code, unreachable on the test container).
**Beyond CI:** `test_async_routing_matches_sync`
(`tests/integration/test_semantic_router.py:822`) fails with
`AssertionError: the async path made a blocking call` when `aroute` is
changed to call the sync `embed`, and passes on this branch;
`test_aroute_from_existing_url_connects_from_url` passes with the async
index derived from the sync one, so the earlier `from_existing` patch is
no longer needed.
**Since the last brief:** `8a70416` applies the review: the async index
is derived from `self._index` (no router-side copies of
URL/kwargs/`lib_name`, no `from_existing` change), keyword-only
arguments after `vector`, the three docstring notes, and the six async
tests replaced by one that blocks the sync paths.
<sub>Reviewed `8a70416` · Claude Code (claude-fable-5-1) · lenses:
correctness, tests. Ran: `pytest
tests/integration/test_semantic_router.py` (42 passed, 1 skipped; Redis
via the repo's testcontainers compose), `pytest tests/unit -k "router or
create_index"` (50 passed), `make check-types` (120 files, no issues),
`make format`.</sub>
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> **Low Risk**
> New async API reuses the existing FT.AGGREGATE flow and
SemanticCache-style connection setup; main caveats are documented
(cluster client conversion, event-loop binding), not new security or
data paths.
>
> **Overview**
> Adds **non-blocking routing** for async apps via `aroute()` and
`aroute_many()`, mirroring `router()` / `route_many()` by using
`vectorizer.aembed` and a lazily created `AsyncSearchIndex` on the same
Redis index.
>
> The sync lookup path is refactored so request building
(`_route_matches_request`), Redis error handling
(`_raise_aggregate_error`), and result parsing
(`_route_matches_from_result`) are shared with `_aget_route_matches`,
reducing drift between sync and async. **`adisconnect()`** and an
**`aindex`** property manage the optional async client (URL-based when
the router owns its connection, otherwise `sync_to_async_redis`).
>
> Integration tests assert async results match sync, that the async path
does not call blocking `embed`/`aggregate`, and that routers loaded with
**`from_existing(redis_url=...)`** wire async Redis from the URL.
>
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
8a70416. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->1 parent 1da1234 commit a58e68f
2 files changed
Lines changed: 253 additions & 30 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | | - | |
| 2 | + | |
3 | 3 | | |
4 | 4 | | |
5 | 5 | | |
| |||
20 | 20 | | |
21 | 21 | | |
22 | 22 | | |
23 | | - | |
| 23 | + | |
24 | 24 | | |
25 | 25 | | |
26 | 26 | | |
| |||
52 | 52 | | |
53 | 53 | | |
54 | 54 | | |
| 55 | + | |
55 | 56 | | |
56 | 57 | | |
57 | 58 | | |
| |||
459 | 460 | | |
460 | 461 | | |
461 | 462 | | |
| 463 | + | |
| 464 | + | |
| 465 | + | |
| 466 | + | |
| 467 | + | |
| 468 | + | |
| 469 | + | |
| 470 | + | |
| 471 | + | |
| 472 | + | |
| 473 | + | |
| 474 | + | |
| 475 | + | |
| 476 | + | |
| 477 | + | |
| 478 | + | |
| 479 | + | |
| 480 | + | |
462 | 481 | | |
463 | 482 | | |
464 | 483 | | |
| |||
483 | 502 | | |
484 | 503 | | |
485 | 504 | | |
| 505 | + | |
486 | 506 | | |
487 | | - | |
488 | | - | |
489 | | - | |
| 507 | + | |
| 508 | + | |
| 509 | + | |
| 510 | + | |
| 511 | + | |
490 | 512 | | |
491 | | - | |
492 | | - | |
493 | | - | |
494 | | - | |
495 | | - | |
496 | | - | |
| 513 | + | |
497 | 514 | | |
| 515 | + | |
| 516 | + | |
| 517 | + | |
498 | 518 | | |
499 | 519 | | |
500 | 520 | | |
| |||
509 | 529 | | |
510 | 530 | | |
511 | 531 | | |
512 | | - | |
| 532 | + | |
513 | 533 | | |
514 | 534 | | |
515 | 535 | | |
516 | | - | |
517 | | - | |
| 536 | + | |
| 537 | + | |
| 538 | + | |
| 539 | + | |
| 540 | + | |
| 541 | + | |
| 542 | + | |
| 543 | + | |
| 544 | + | |
| 545 | + | |
| 546 | + | |
| 547 | + | |
| 548 | + | |
| 549 | + | |
| 550 | + | |
| 551 | + | |
| 552 | + | |
| 553 | + | |
| 554 | + | |
| 555 | + | |
| 556 | + | |
| 557 | + | |
| 558 | + | |
| 559 | + | |
| 560 | + | |
| 561 | + | |
| 562 | + | |
| 563 | + | |
| 564 | + | |
| 565 | + | |
| 566 | + | |
| 567 | + | |
| 568 | + | |
| 569 | + | |
| 570 | + | |
518 | 571 | | |
519 | | - | |
520 | | - | |
| 572 | + | |
| 573 | + | |
| 574 | + | |
| 575 | + | |
| 576 | + | |
| 577 | + | |
| 578 | + | |
| 579 | + | |
| 580 | + | |
521 | 581 | | |
| 582 | + | |
| 583 | + | |
| 584 | + | |
| 585 | + | |
| 586 | + | |
| 587 | + | |
| 588 | + | |
| 589 | + | |
| 590 | + | |
| 591 | + | |
522 | 592 | | |
523 | 593 | | |
524 | 594 | | |
| |||
529 | 599 | | |
530 | 600 | | |
531 | 601 | | |
532 | | - | |
| 602 | + | |
533 | 603 | | |
534 | 604 | | |
| 605 | + | |
| 606 | + | |
| 607 | + | |
| 608 | + | |
| 609 | + | |
| 610 | + | |
| 611 | + | |
| 612 | + | |
| 613 | + | |
| 614 | + | |
| 615 | + | |
| 616 | + | |
| 617 | + | |
| 618 | + | |
| 619 | + | |
| 620 | + | |
| 621 | + | |
| 622 | + | |
| 623 | + | |
| 624 | + | |
| 625 | + | |
| 626 | + | |
| 627 | + | |
| 628 | + | |
| 629 | + | |
535 | 630 | | |
536 | 631 | | |
537 | 632 | | |
| |||
541 | 636 | | |
542 | 637 | | |
543 | 638 | | |
544 | | - | |
545 | | - | |
546 | | - | |
547 | | - | |
548 | | - | |
549 | | - | |
550 | | - | |
551 | | - | |
552 | | - | |
553 | | - | |
554 | | - | |
555 | | - | |
556 | | - | |
| 639 | + | |
557 | 640 | | |
558 | 641 | | |
559 | 642 | | |
| |||
625 | 708 | | |
626 | 709 | | |
627 | 710 | | |
| 711 | + | |
| 712 | + | |
| 713 | + | |
| 714 | + | |
| 715 | + | |
| 716 | + | |
| 717 | + | |
| 718 | + | |
| 719 | + | |
| 720 | + | |
| 721 | + | |
| 722 | + | |
| 723 | + | |
| 724 | + | |
| 725 | + | |
| 726 | + | |
| 727 | + | |
| 728 | + | |
| 729 | + | |
| 730 | + | |
| 731 | + | |
| 732 | + | |
| 733 | + | |
| 734 | + | |
| 735 | + | |
| 736 | + | |
| 737 | + | |
| 738 | + | |
| 739 | + | |
| 740 | + | |
| 741 | + | |
| 742 | + | |
| 743 | + | |
| 744 | + | |
| 745 | + | |
| 746 | + | |
| 747 | + | |
| 748 | + | |
| 749 | + | |
| 750 | + | |
| 751 | + | |
| 752 | + | |
| 753 | + | |
| 754 | + | |
| 755 | + | |
| 756 | + | |
| 757 | + | |
| 758 | + | |
| 759 | + | |
| 760 | + | |
| 761 | + | |
| 762 | + | |
| 763 | + | |
| 764 | + | |
| 765 | + | |
| 766 | + | |
| 767 | + | |
| 768 | + | |
| 769 | + | |
| 770 | + | |
| 771 | + | |
| 772 | + | |
| 773 | + | |
| 774 | + | |
| 775 | + | |
| 776 | + | |
| 777 | + | |
| 778 | + | |
| 779 | + | |
| 780 | + | |
| 781 | + | |
| 782 | + | |
| 783 | + | |
| 784 | + | |
| 785 | + | |
| 786 | + | |
| 787 | + | |
| 788 | + | |
| 789 | + | |
| 790 | + | |
| 791 | + | |
| 792 | + | |
| 793 | + | |
| 794 | + | |
| 795 | + | |
| 796 | + | |
| 797 | + | |
| 798 | + | |
628 | 799 | | |
629 | 800 | | |
630 | 801 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
850 | 850 | | |
851 | 851 | | |
852 | 852 | | |
| 853 | + | |
| 854 | + | |
| 855 | + | |
| 856 | + | |
| 857 | + | |
| 858 | + | |
| 859 | + | |
| 860 | + | |
| 861 | + | |
| 862 | + | |
| 863 | + | |
| 864 | + | |
| 865 | + | |
| 866 | + | |
| 867 | + | |
| 868 | + | |
| 869 | + | |
| 870 | + | |
| 871 | + | |
| 872 | + | |
| 873 | + | |
| 874 | + | |
| 875 | + | |
| 876 | + | |
| 877 | + | |
| 878 | + | |
| 879 | + | |
| 880 | + | |
| 881 | + | |
| 882 | + | |
| 883 | + | |
| 884 | + | |
| 885 | + | |
| 886 | + | |
| 887 | + | |
| 888 | + | |
| 889 | + | |
| 890 | + | |
| 891 | + | |
| 892 | + | |
| 893 | + | |
| 894 | + | |
| 895 | + | |
| 896 | + | |
| 897 | + | |
| 898 | + | |
| 899 | + | |
| 900 | + | |
| 901 | + | |
| 902 | + | |
| 903 | + | |
| 904 | + | |
0 commit comments