semantic-router 0.2.0.dev1__tar.gz → 0.3.1__tar.gz

{semantic_router-0.2.0.dev1 → semantic_router-0.3.1}/.gitignore

@@ -12,6 +12,8 @@ venv/
 
 
 # local env files
+**/*.env
+*.env
 .env*.local
 .env
 my.secrets
@@ -34,3 +36,6 @@ test_sync.ipynb
 
 # docs
 docs/build
+
+# fastembed model cache used by CI
+.fastembed_cache/

{semantic_router-0.2.0.dev1 → semantic_router-0.3.1}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Aurelio AI
+Copyright (c) 2026 Aurelio AI
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{semantic_router-0.2.0.dev1 → semantic_router-0.3.1}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.5
 Name: semantic-router
-Version: 0.2.0.dev1
+Version: 0.3.1
 Summary: Super fast semantic router for AI decision making
 Author-email: Aurelio AI <hello@aurelio.ai>
 License-Expression: MIT
 License-File: LICENSE
-Requires-Python: <3.14,>=3.9
+Requires-Python: <3.14,>=3.10
 Requires-Dist: aiohttp<4,>=3.10.11
 Requires-Dist: aurelio-sdk>=0.0.19
 Requires-Dist: cohere<6.00,>=5.9.4
@@ -24,61 +24,30 @@ Requires-Dist: voyageai>=0.4.1
 Provides-Extra: all
 Requires-Dist: boto3<2,>=1.34.98; extra == 'all'
 Requires-Dist: botocore<2,>=1.34.110; extra == 'all'
-Requires-Dist: dagger-io>=0.1.1; (python_version >= '3.11') and extra == 'all'
-Requires-Dist: fastembed<0.4,>=0.3.0; (python_version < '3.13') and extra == 'all'
+Requires-Dist: fastembed<1,>=0.7.0; extra == 'all'
 Requires-Dist: google-cloud-aiplatform<2,>=1.45.0; extra == 'all'
-Requires-Dist: ipykernel<7,>=6.25.0; extra == 'all'
-Requires-Dist: litellm>=1.83.7; extra == 'all'
+Requires-Dist: litellm>=1.84.0; extra == 'all'
 Requires-Dist: llama-cpp-python<0.2.86,>=0.2.28; (python_version < '3.13') and extra == 'all'
-Requires-Dist: mypy<2,>=1.7.1; extra == 'all'
 Requires-Dist: ollama>=0.1.7; extra == 'all'
-Requires-Dist: pillow<11.0.0,>=10.2.0; (python_version < '3.13') and extra == 'all'
+Requires-Dist: pillow>=10.2.0; (python_version < '3.13') and extra == 'all'
 Requires-Dist: pinecone[asyncio]<8.0.0,>=7.0.0; extra == 'all'
 Requires-Dist: psycopg[binary]<4,>=3.1.0; extra == 'all'
-Requires-Dist: pytest-asyncio<0.25,>=0.24.0; extra == 'all'
-Requires-Dist: pytest-cov<5,>=4.1.0; extra == 'all'
-Requires-Dist: pytest-mock<4,>=3.12.0; extra == 'all'
-Requires-Dist: pytest-timeout; extra == 'all'
-Requires-Dist: pytest-xdist<4,>=3.5.0; extra == 'all'
-Requires-Dist: pytest~=8.2; extra == 'all'
-Requires-Dist: python-dotenv<2,>=1.0.0; extra == 'all'
 Requires-Dist: qdrant-client<2,>=1.11.1; extra == 'all'
-Requires-Dist: requests-mock<2,>=1.12.1; extra == 'all'
-Requires-Dist: ruff<0.12,>=0.11.2; extra == 'all'
+Requires-Dist: redis<7,>=5.0.0; extra == 'all'
 Requires-Dist: sentence-transformers>=5.0.0; (python_version < '3.13') and extra == 'all'
 Requires-Dist: tokenizers>=0.19; (python_version < '3.13') and extra == 'all'
 Requires-Dist: torch>=2.6.0; (python_version < '3.13') and extra == 'all'
 Requires-Dist: torchvision>=0.17.0; (python_version < '3.13') and extra == 'all'
 Requires-Dist: transformers>=4.36.2; (python_version < '3.13') and extra == 'all'
-Requires-Dist: types-pyyaml<7,>=6.0.12.12; extra == 'all'
-Requires-Dist: types-requests<3,>=2.31.0; extra == 'all'
 Provides-Extra: bedrock
 Requires-Dist: boto3<2,>=1.34.98; extra == 'bedrock'
 Requires-Dist: botocore<2,>=1.34.110; extra == 'bedrock'
-Provides-Extra: dev
-Requires-Dist: dagger-io>=0.1.1; (python_version >= '3.11') and extra == 'dev'
-Requires-Dist: ipykernel<7,>=6.25.0; extra == 'dev'
-Requires-Dist: litellm>=1.83.7; extra == 'dev'
-Requires-Dist: mypy<2,>=1.7.1; extra == 'dev'
-Requires-Dist: pytest-asyncio<0.25,>=0.24.0; extra == 'dev'
-Requires-Dist: pytest-cov<5,>=4.1.0; extra == 'dev'
-Requires-Dist: pytest-mock<4,>=3.12.0; extra == 'dev'
-Requires-Dist: pytest-timeout; extra == 'dev'
-Requires-Dist: pytest-xdist<4,>=3.5.0; extra == 'dev'
-Requires-Dist: pytest~=8.2; extra == 'dev'
-Requires-Dist: python-dotenv<2,>=1.0.0; extra == 'dev'
-Requires-Dist: requests-mock<2,>=1.12.1; extra == 'dev'
-Requires-Dist: ruff<0.12,>=0.11.2; extra == 'dev'
-Requires-Dist: types-pyyaml<7,>=6.0.12.12; extra == 'dev'
-Requires-Dist: types-requests<3,>=2.31.0; extra == 'dev'
-Provides-Extra: docs
-Requires-Dist: pydoc-markdown>=4.8.2; (python_version < '3.12') and extra == 'docs'
 Provides-Extra: fastembed
-Requires-Dist: fastembed<0.4,>=0.3.0; (python_version < '3.13') and extra == 'fastembed'
+Requires-Dist: fastembed<1,>=0.7.0; extra == 'fastembed'
 Provides-Extra: google
 Requires-Dist: google-cloud-aiplatform<2,>=1.45.0; extra == 'google'
 Provides-Extra: litellm
-Requires-Dist: litellm>=1.83.7; extra == 'litellm'
+Requires-Dist: litellm>=1.84.0; extra == 'litellm'
 Provides-Extra: local
 Requires-Dist: llama-cpp-python<0.2.86,>=0.2.28; (python_version < '3.13') and extra == 'local'
 Requires-Dist: sentence-transformers>=5.0.0; (python_version < '3.13') and extra == 'local'
@@ -93,8 +62,10 @@ Provides-Extra: postgres
 Requires-Dist: psycopg[binary]<4,>=3.1.0; extra == 'postgres'
 Provides-Extra: qdrant
 Requires-Dist: qdrant-client<2,>=1.11.1; extra == 'qdrant'
+Provides-Extra: redis
+Requires-Dist: redis<7,>=5.0.0; extra == 'redis'
 Provides-Extra: vision
-Requires-Dist: pillow<11.0.0,>=10.2.0; (python_version < '3.13') and extra == 'vision'
+Requires-Dist: pillow>=10.2.0; (python_version < '3.13') and extra == 'vision'
 Requires-Dist: torch>=2.6.0; (python_version < '3.13') and extra == 'vision'
 Requires-Dist: torchvision>=0.17.0; (python_version < '3.13') and extra == 'vision'
 Requires-Dist: transformers>=4.36.2; (python_version < '3.13') and extra == 'vision'
@@ -109,7 +80,6 @@ Description-Content-Type: text/markdown
 <img alt="" src="https://img.shields.io/github/repo-size/aurelio-labs/semantic-router" />
 <a href="https://github.com/aurelio-labs/semantic-router/issues"><img alt="GitHub Issues" src="https://img.shields.io/github/issues/aurelio-labs/semantic-router" />
 <a href="https://github.com/aurelio-labs/semantic-router/pulls"><img alt="GitHub Pull Requests" src="https://img.shields.io/github/issues-pr/aurelio-labs/semantic-router" />
-<img src="https://codecov.io/gh/aurelio-labs/semantic-router/graph/badge.svg?token=H8OOMV2TUF" />
 <a href="https://github.com/aurelio-labs/semantic-router/blob/main/LICENSE"><img alt="Github License" src="https://img.shields.io/badge/License-MIT-yellow.svg" />
 </p>
 
@@ -119,6 +89,18 @@ Semantic Router is a superfast decision-making layer for your LLMs and agents. R
 
 ---
 
+## Versions
+
+Semantic Router has two release lines. The **0.x line** (`v0` branch) is the current stable library and finishes at 0.3.0, after which it receives bug fixes only. The **1.x line** (`main` branch) is a breaking rewrite of the routing layer and ships as 1.0.0. Pin to the line you are on:
+
+```
+pip install "semantic-router<1"   # 0.x
+```
+
+Details, and the docs for each line, are on the [versions page](https://docs.aurelio.ai/semantic-router/v0/get-started/versions).
+
+---
+
 ## Quickstart
 
 To get started with _semantic-router_ we install it like so:

{semantic_router-0.2.0.dev1 → semantic_router-0.3.1}/README.md

@@ -7,7 +7,6 @@
 <img alt="" src="https://img.shields.io/github/repo-size/aurelio-labs/semantic-router" />
 <a href="https://github.com/aurelio-labs/semantic-router/issues"><img alt="GitHub Issues" src="https://img.shields.io/github/issues/aurelio-labs/semantic-router" />
 <a href="https://github.com/aurelio-labs/semantic-router/pulls"><img alt="GitHub Pull Requests" src="https://img.shields.io/github/issues-pr/aurelio-labs/semantic-router" />
-<img src="https://codecov.io/gh/aurelio-labs/semantic-router/graph/badge.svg?token=H8OOMV2TUF" />
 <a href="https://github.com/aurelio-labs/semantic-router/blob/main/LICENSE"><img alt="Github License" src="https://img.shields.io/badge/License-MIT-yellow.svg" />
 </p>
 
@@ -17,6 +16,18 @@ Semantic Router is a superfast decision-making layer for your LLMs and agents. R
 
 ---
 
+## Versions
+
+Semantic Router has two release lines. The **0.x line** (`v0` branch) is the current stable library and finishes at 0.3.0, after which it receives bug fixes only. The **1.x line** (`main` branch) is a breaking rewrite of the routing layer and ships as 1.0.0. Pin to the line you are on:
+
+```
+pip install "semantic-router<1"   # 0.x
+```
+
+Details, and the docs for each line, are on the [versions page](https://docs.aurelio.ai/semantic-router/v0/get-started/versions).
+
+---
+
 ## Quickstart
 
 To get started with _semantic-router_ we install it like so:

{semantic_router-0.2.0.dev1 → semantic_router-0.3.1}/pyproject.toml

@@ -1,9 +1,9 @@
 [project]
 name = "semantic-router"
-version = "0.2.0.dev1"
+version = "0.3.1"
 description = "Super fast semantic router for AI decision making"
 authors = [{ name = "Aurelio AI", email = "hello@aurelio.ai" }]
-requires-python = ">=3.9,<3.14"
+requires-python = ">=3.10,<3.14"
 readme = "README.md"
 license = "MIT"
 dependencies = [
@@ -27,8 +27,9 @@ dependencies = [
 [project.optional-dependencies]
 # only required by LiteLLMEncoder; the provider-specific encoders use their own SDKs
 litellm = [
-    # https://www.cve.org/CVERecord?id=CVE-2026-42208 explains >=1.83.7
-    "litellm>=1.83.7",
+    # 1.84.0 fixes an authentication bypass via Host header injection
+    # (GHSA-4xpc-pv4p-pm3w); 1.83.7 was the previous floor for CVE-2026-42208
+    "litellm>=1.84.0",
 ]
 ollama = ["ollama>=0.1.7"]
 local = [
@@ -42,10 +43,11 @@ pinecone = ["pinecone[asyncio]>=7.0.0,<8.0.0"]
 vision = [
     "torchvision>=0.17.0 ; python_version < '3.13'",
     "transformers>=4.36.2 ; python_version < '3.13'",
-    "pillow>=10.2.0,<11.0.0 ; python_version < '3.13'",
+    "pillow>=10.2.0 ; python_version < '3.13'",
     "torch>=2.6.0 ; python_version < '3.13'"
 ]
 qdrant = ["qdrant-client>=1.11.1,<2"]
+redis = ["redis>=5.0.0,<7"]
 google = ["google-cloud-aiplatform>=1.45.0,<2"]
 bedrock = [
     "boto3>=1.34.98,<2",
@@ -54,8 +56,24 @@ bedrock = [
 postgres = [
     "psycopg[binary]>=3.1.0,<4",
 ]
-fastembed = ["fastembed>=0.3.0,<0.4 ; python_version < '3.13'"]
-docs = ["pydoc-markdown>=4.8.2 ; python_version < '3.12'"]
+fastembed = ["fastembed>=0.7.0,<1"]
+all = [
+    "semantic-router[local]",
+    "semantic-router[pinecone]",
+    "semantic-router[vision]",
+    "semantic-router[qdrant]",
+    "semantic-router[redis]",
+    "semantic-router[google]",
+    "semantic-router[bedrock]",
+    "semantic-router[postgres]",
+    "semantic-router[fastembed]",
+    "semantic-router[litellm]",
+    "semantic-router[ollama]",
+]
+
+# Development tooling. `uv sync` and `uv run` install the `dev` group by default,
+# so a fresh clone gets pytest, ruff and mypy without asking for any extra.
+[dependency-groups]
 dev = [
     "ipykernel>=6.25.0,<7",
     "ruff>=0.11.2,<0.12",
@@ -69,25 +87,9 @@ dev = [
     "types-pyyaml>=6.0.12.12,<7",
     "requests-mock>=1.12.1,<2",
     "types-requests>=2.31.0,<3",
-    "dagger-io>=0.1.1 ; python_version >= '3.11'",
     "python-dotenv>=1.0.0,<2",
-    # needed so `mypy semantic_router/` can resolve the LiteLLMEncoder import
-    "semantic-router[litellm]",
-]
-all = [
-    "semantic-router[local]",
-    "semantic-router[pinecone]",
-    "semantic-router[vision]",
-    "semantic-router[qdrant]",
-    "semantic-router[google]",
-    "semantic-router[bedrock]",
-    "semantic-router[postgres]",
-    "semantic-router[fastembed]",
-    "semantic-router[litellm]",
-    "semantic-router[dev]",
-    "semantic-router[ollama]",
-    "pytest-timeout",
 ]
+docs = ["pydoc-markdown>=4.8.2 ; python_version < '3.12'"]
 
 [tool.hatch.build.targets.sdist]
 include = ["semantic_router"]
@@ -105,6 +107,9 @@ build-backend = "hatchling.build"
 [tool.ruff]
 line-length = 88
 
+[tool.ruff.format]
+exclude = ["*.ipynb"]
+
 [tool.ruff.lint]
 select = ["E", "F", "I", "T201", "NPY201"]
 ignore = ["E501"]
@@ -132,3 +137,10 @@ torchvision = [
     { index = "pytorch-nightly", marker = "python_version >= '3.13' and sys_platform == 'darwin'"  },
     { index = "pytorch-cpu", marker = "python_version < '3.13' or sys_platform != 'darwin'" },
 ]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--strict-markers"
+markers = [
+    "live: calls a paid third-party API (OpenAI, Cohere, ...). Needs real keys; excluded from the default `make test` run.",
+]

semantic_router-0.3.1/semantic_router/__init__.py

@@ -0,0 +1,11 @@
+from semantic_router.route import Route
+from semantic_router.routers import HybridRouter, RouterConfig, SemanticRouter
+
+__all__ = ["SemanticRouter", "HybridRouter", "Route", "RouterConfig"]
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("semantic-router")
+except PackageNotFoundError:  # running from a checkout that was never installed
+    __version__ = "0.0.0"

{semantic_router-0.2.0.dev1 → semantic_router-0.3.1}/semantic_router/encoders/bm25.py

@@ -26,12 +26,52 @@ class BM25Encoder(SparseEncoder, FittableMixin, AsymmetricSparseMixin):
     - we train a BM25 encoder's normalization parameters on a sufficiently large corpus to capture target language distribution
     - these trained parameter allow us to balance TF & IDF of query & documents for retrieval (read more on how BM25 fixes issues with TF-IDF)
 
+    The reference formula is section 4.1 of the ATIRE paper:
+
+        RSV_d = Σ_{t ∈ q} log(N / df_t) · (k1 + 1) · tf_td
+                           / (k1 · ((1 - b) + b · L_d / L_avg) + tf_td)
+
+    Deviations from the paper
+    -------------------------
+    This implementation is faithful to the formula above on the document side,
+    but deviates from it in three documented ways. Each is deliberate; see the
+    inline comments at the point of use for the details.
+
+    1. IDF smoothing. We compute `log((N + 1) / (df_t + 0.5))` rather than
+       `log(N / df_t)`, to avoid a division by zero for unseen terms. This
+       preserves the strictly-positive IDF that the ATIRE variant exists for.
+
+    2. Query weight normalization. The paper produces an unbounded relevance
+       score, which is fine for a search engine that only ranks within a single
+       query. A router instead compares scores against a fixed
+       `score_threshold`, so scores must be comparable *across* queries. We
+       therefore L1-normalize the query weights and scale them by
+       `1 / (k1 + 1)`, which bounds the query·document dot product to [0, 1] --
+       the same range as the cosine similarity returned by the dense encoders,
+       so the two can be blended in `HybridRouter` and thresholded alike.
+
+       This is ranking-neutral within a query (it is a single positive constant
+       per query) but it does discard cross-query IDF magnitude: two queries
+       with different total IDF mass can produce the same score.
+
+    3. Parameter defaults. We default to `k1=1.5, b=0.75` rather than the
+       paper's `k1=0.9, b=0.4`. See the `k1` and `b` parameter docs below.
+
     ATIRE Paper: https://www.cs.otago.ac.nz/research/student-publications/atire-opensource.pdf
     Pinecone Implementation: https://github.com/pinecone-io/pinecone-text/blob/8399f9ff28c4652766c35165c0db9b0eff309077/pinecone_text/sparse/bm25_encoder.py
 
-    :param k1: normalizer parameter that limits how much a single query term `q_i ∈ q` can affect score for document `D_n`
+    :param k1: normalizer parameter that limits how much a single query term `q_i ∈ q` can affect score for document `D_n`.
+        Defaults to 1.5, the standard Robertson value, *not* the 0.9 reported in the ATIRE paper. The paper's value was
+        trained on the INEX 2008 Wikipedia collection, whose documents average 878 words (paper table 5), whereas this
+        encoder is fitted on route utterances averaging on the order of ten tokens. Transferring the paper's parameters
+        to utterance-length text is not obviously more correct, and changing the default would silently shift the scores
+        that existing `score_threshold` values were tuned against.
     :type k1: float
-    :param b: normalizer parameter that balances the effect of a single document length compared to the average document length
+    :param b: normalizer parameter that balances the effect of a single document length compared to the average document
+        length. Defaults to 0.75 rather than the paper's 0.4, for the same reason as `k1`. Note that `b` is considerably
+        more influential on short text: over utterances spanning 0.3x to 2.2x the average length, `b=0.75` spreads the
+        document factor by ~2.2x versus ~1.4x for `b=0.4`. Lower it towards the paper's value if length is over-weighted
+        for your route set.
     :type b: float
     :param corpus_size: number of documents in the trained corpus
     :type corpus_size: int, optional
@@ -193,16 +233,55 @@ class BM25Encoder(SparseEncoder, FittableMixin, AsymmetricSparseMixin):
             raise ValueError("No documents provided for encoding")
 
         # Convert queries to token counts
-        queries_ids = self._tokenizer.tokenize(queries)
+        queries_ids = self._tokenizer.tokenize(queries, pad=True)
         df = self._df(queries_ids)  # (batch_size, vocab_size)
         N = self.corpus_size
+
+        # DEVIATION FROM THE ATIRE PAPER: the paper specifies `log(N / df_t)`,
+        # whereas we compute `log((N + 1) / (df_t + 0.5))`. The `+ 0.5` avoids a
+        # division by zero and the `+ 1` keeps the numerator above the
+        # denominator, so the result is strictly positive. This preserves the
+        # property the ATIRE variant was introduced for (IDF is never negative,
+        # see footnote 1 of the paper) and stays monotonically decreasing in
+        # `df_t`, but it is a smoothed variant rather than the paper's formula.
+        # It weights common terms slightly less harshly than `log(N / df_t)`.
         df = df + np.where(df > 0, 0.5, 0)
         idf = np.divide(N + 1, df, out=np.zeros_like(df), where=df != 0)
         idf = np.log(
             idf, out=np.zeros_like(df), where=df != 0
         )  # (batch_size, vocab_size)
+
+        # The paper sums over the query terms `t ∈ q`, so a term repeated in the
+        # query contributes once per occurrence. Weighting IDF by the query term
+        # frequency is equivalent, and keeps the operation vectorised.
+        qtf = self._tf(queries_ids)  # (batch_size, vocab_size)
+        weighted_idf = idf * qtf
+
+        # DEVIATION FROM THE ATIRE PAPER: the paper's RSV is an unbounded sum,
+        # which is fine when only ranking within one query. A router compares
+        # scores against a fixed `score_threshold`, so they must be comparable
+        # across queries too. Two steps make that so:
+        #
+        #   1. L1-normalize, so the weights sum to 1 regardless of how long the
+        #      query is or how rare its terms are.
+        #   2. Divide by `k1 + 1`, so the weights sum to `1 / (k1 + 1)`.
+        #
+        # `encode_documents` returns values in (0, k1 + 1] (it keeps the paper's
+        # `(k1 + 1)` numerator), so the dot product of the two is bounded to
+        # [0, 1] -- the same range as the cosine similarity produced by the
+        # dense encoders. That lets `HybridRouter` blend the two and lets one
+        # threshold apply to both. Without the `k1 + 1` divisor the sparse score
+        # would reach `k1 + 1` (2.5 at the default `k1`) and would dominate the
+        # dense component of the hybrid score.
+        #
+        # Both steps are a single positive constant per query, so neither
+        # changes the ranking of documents for that query.
+        denominator = weighted_idf.sum(axis=1)[:, np.newaxis] * (self.k1 + 1.0)
         idf_norm = np.divide(
-            idf, idf.sum(axis=1)[:, np.newaxis], out=np.zeros_like(idf), where=idf != 0
+            weighted_idf,
+            denominator,
+            out=np.zeros_like(weighted_idf),
+            where=weighted_idf != 0,
         )
 
         return self._array_to_sparse_embeddings(idf_norm)
@@ -215,7 +294,7 @@ class BM25Encoder(SparseEncoder, FittableMixin, AsymmetricSparseMixin):
         r"""Returns document term frequency normed by itself & average trained corpus length
         (This is the right-hand side of the BM25 equation, which gets matmul-ed with the query IDF component)
 
-        LaTeX: $\frac{f(d_i, D)}{f(d_i, D) + k_1 \times (1 - b + b \times \frac{|D|}{avgdl})}$
+        LaTeX: $\frac{(k_1 + 1) \times f(d_i, D)}{f(d_i, D) + k_1 \times (1 - b + b \times \frac{|D|}{avgdl})}$
         where:
             f(d_i, D) is frequency of term `d_i ∈ D`
             |D| is the document length
@@ -244,9 +323,9 @@ class BM25Encoder(SparseEncoder, FittableMixin, AsymmetricSparseMixin):
         queries_ids = self._tokenizer.tokenize(documents, pad=True)
         tf = self._tf(queries_ids)  # (batch_size, vocab_size)
         tf_sum = tf.sum(axis=1)  # (batch_size, 1)
-        tf_normed = tf / (
+        tf_normed = ((self.k1 + 1.0) * tf) / (
             self.k1
-            * (1.0 - self.b * self.b * (tf_sum[:, np.newaxis] / self._avg_doc_len))
+            * ((1.0 - self.b) + self.b * (tf_sum[:, np.newaxis] / self._avg_doc_len))
             + tf
         )  # (batch_size, vocab_size)
 

{semantic_router-0.2.0.dev1 → semantic_router-0.3.1}/semantic_router/encoders/clip.py

@@ -96,20 +96,22 @@ class CLIPEncoder(DenseEncoder):
         :returns: A tuple of the tokenizer, processor, and model.
         :rtype: Tuple[Any, Any, Any]
         """
+        # torch first: transformers >= 5 imports torch itself, so checking it
+        # second would report a missing torch as a missing transformers
         try:
-            from transformers import CLIPModel, CLIPProcessor, CLIPTokenizerFast
+            import torch
         except ImportError:
             raise ImportError(
-                "Please install transformers to use CLIPEncoder. "
+                "Please install Pytorch to use CLIPEncoder. "
                 "You can install it with: "
                 "`pip install semantic-router[vision]`"
             )
 
         try:
-            import torch
+            from transformers import CLIPModel, CLIPProcessor, CLIPTokenizerFast
         except ImportError:
             raise ImportError(
-                "Please install Pytorch to use CLIPEncoder. "
+                "Please install transformers to use CLIPEncoder. "
                 "You can install it with: "
                 "`pip install semantic-router[vision]`"
             )
@@ -166,6 +168,9 @@ class CLIPEncoder(DenseEncoder):
         ).to(self.device)
         with self._torch.no_grad():
             embeds = self._model.get_text_features(**inputs)
+            # transformers >= 5 returns a model output whose pooler_output holds the
+            # projected features; earlier versions return that tensor directly
+            embeds = getattr(embeds, "pooler_output", embeds)
             embeds = embeds.squeeze(0).cpu().detach().numpy()
         return embeds
 
@@ -183,6 +188,7 @@ class CLIPEncoder(DenseEncoder):
         ].to(self.device)
         with self._torch.no_grad():
             embeds = self._model.get_image_features(pixel_values=inputs)
+            embeds = getattr(embeds, "pooler_output", embeds)  # see _encode_text
             embeds = embeds.squeeze(0).cpu().detach().numpy()
         return embeds
 

{semantic_router-0.2.0.dev1 → semantic_router-0.3.1}/semantic_router/encoders/fastembed.py

@@ -1,3 +1,4 @@
+import asyncio
 from typing import Any, List, Optional
 
 import numpy as np
@@ -71,3 +72,17 @@ class FastEmbedEncoder(DenseEncoder):
             return embeddings
         except Exception as e:
             raise ValueError(f"FastEmbed embed failed. Error: {e}") from e
+
+    async def acall(self, docs: List[str]) -> List[List[float]]:
+        """Embed a list of documents asynchronously. Supports text only.
+
+        FastEmbed itself is synchronous, so this offloads the embedding call to a
+        thread to avoid blocking the event loop.
+
+        :param docs: The documents to embed.
+        :type docs: List[str]
+        :raise ValueError: If the embedding fails.
+        :return: The vector embeddings of the documents.
+        :rtype: List[List[float]]
+        """
+        return await asyncio.to_thread(lambda: self.__call__(docs))

{semantic_router-0.2.0.dev1 → semantic_router-0.3.1}/semantic_router/encoders/openai.py

@@ -118,6 +118,27 @@ class OpenAIEncoder(DenseEncoder):
         # get token encoder
         self._token_encoder = tiktoken.encoding_for_model(name)
 
+    def _validate_docs(self, docs: List[str]) -> None:
+        """Raise a clear error for input the embeddings API rejects with a 400.
+        Checked before the call, since a 400 is an OpenAIError and gets retried."""
+        if isinstance(docs, str):
+            raise ValueError("OpenAI encoder input must be a list of strings, got str.")
+        if len(docs) == 0:
+            raise ValueError("OpenAI encoder input cannot be empty.")
+
+        for idx, doc in enumerate(docs):
+            if not isinstance(doc, str):
+                raise ValueError(
+                    "OpenAI encoder input must contain only strings, got "
+                    f"{type(doc).__name__} at index {idx}."
+                )
+            # the API accepts whitespace-only strings, so only "" is rejected, and
+            # docs are sent unchanged: stripping would change their embeddings
+            if doc == "":
+                raise ValueError(
+                    f"OpenAI encoder input contains an empty string at index {idx}."
+                )
+
     def __call__(self, docs: List[str], truncate: bool = True) -> List[List[float]]:
         """Encode a list of text documents into embeddings using OpenAI API.
 
@@ -130,6 +151,8 @@ class OpenAIEncoder(DenseEncoder):
             raise ValueError("OpenAI client is not initialized.")
         embeds = None
 
+        self._validate_docs(docs)
+
         if truncate:
             # check if any document exceeds token limit and truncate if so
             docs = [self._truncate(doc) for doc in docs]
@@ -202,6 +225,8 @@ class OpenAIEncoder(DenseEncoder):
             raise ValueError("OpenAI async client is not initialized.")
         embeds = None
 
+        self._validate_docs(docs)
+
         if truncate:
             # check if any document exceeds token limit and truncate if so
             docs = [self._truncate(doc) for doc in docs]

{semantic_router-0.2.0.dev1 → semantic_router-0.3.1}/semantic_router/encoders/vit.py

@@ -41,21 +41,23 @@ class VitEncoder(DenseEncoder):
         :return: The processor and model.
         :rtype: tuple
         """
+        # torch first: transformers >= 5 imports torch itself, so checking it
+        # second would report a missing torch as a missing transformers
         try:
-            from transformers import ViTImageProcessor, ViTModel
+            import torch
+            import torchvision.transforms as T
         except ImportError:
             raise ImportError(
-                "Please install transformers to use VitEncoder. "
+                "Please install Pytorch to use VitEncoder. "
                 "You can install it with: "
                 "`pip install semantic-router[vision]`"
             )
 
         try:
-            import torch
-            import torchvision.transforms as T
+            from transformers import ViTImageProcessor, ViTModel
         except ImportError:
             raise ImportError(
-                "Please install Pytorch to use VitEncoder. "
+                "Please install transformers to use VitEncoder. "
                 "You can install it with: "
                 "`pip install semantic-router[vision]`"
             )

{semantic_router-0.2.0.dev1 → semantic_router-0.3.1}/semantic_router/index/__init__.py

@@ -4,6 +4,7 @@ from semantic_router.index.local import LocalIndex
 from semantic_router.index.pinecone import PineconeIndex
 from semantic_router.index.postgres import PostgresIndex
 from semantic_router.index.qdrant import QdrantIndex
+from semantic_router.index.redis import RedisIndex
 
 __all__ = [
     "BaseIndex",
@@ -12,4 +13,5 @@ __all__ = [
     "QdrantIndex",
     "PineconeIndex",
     "PostgresIndex",
+    "RedisIndex",
 ]

{semantic_router-0.2.0.dev1 → semantic_router-0.3.1}/semantic_router/index/local.py

@@ -43,6 +43,10 @@ class LocalIndex(BaseIndex):
         :param metadata_list: List of metadata to add to the index.
         :type metadata_list: List[Dict[str, Any]]
         """
+        if metadata_list and len(metadata_list) != len(embeddings):
+            raise ValueError(
+                f"metadata_list length ({len(metadata_list)}) must match embeddings length ({len(embeddings)})."
+            )
         embeds = np.array(embeddings)  # type: ignore
         routes_arr = np.array(routes)
         if isinstance(utterances[0], str):
@@ -191,7 +195,7 @@ class LocalIndex(BaseIndex):
                     filtered_index.append(vec)
                     filtered_routes.append(route)
             if not filtered_routes:
-                raise ValueError("No routes found matching the filter criteria.")
+                return np.array([]), []
             sim = similarity_matrix(vector, np.array(filtered_index))
             scores, idx = top_scores(sim, top_k)
             route_names = [filtered_routes[i] for i in idx]
@@ -231,7 +235,7 @@ class LocalIndex(BaseIndex):
                     filtered_index.append(vec)
                     filtered_routes.append(route)
             if not filtered_routes:
-                raise ValueError("No routes found matching the filter criteria.")
+                return np.array([]), []
             sim = similarity_matrix(vector, np.array(filtered_index))
             scores, idx = top_scores(sim, top_k)
             route_names = [filtered_routes[i] for i in idx]