refactor(python): drop Python 3.9 support (#587)

## Summary

This PR drops Python 3.9 support from RedisVL and makes Python 3.10 the
project minimum. That change is carried through package metadata, the
lockfile, CI configuration, repo-owned documentation, and the codebase’s
type annotations so the stated support policy and the implementation
match.

## Motivation

Supporting Python 3.9 was already imposing ongoing cost in a few
different ways. It required extra compatibility handling, kept the
project split between core-package and MCP-specific runtime messaging,
and forced older annotation syntax across large parts of the repository.
Python 3.9 is also past its official end-of-life, so continuing to carry
support for it no longer has a strong maintenance or ecosystem
justification. The project already targets newer runtimes in practice,
which makes keeping 3.9 mostly maintenance overhead.

## Changes

The support-floor change starts in packaging and CI. `pyproject.toml`,
`uv.lock`, and the GitHub Actions workflows now treat Python 3.10 as the
minimum supported version, while preserving current newer-runtime
coverage, including Python 3.14 in lint and test configuration. This
aligns the declared support policy with the environments the project is
expected to run and validate against.

The library code has also been updated to use Python 3.10-native typing
syntax throughout repo-owned Python sources. Legacy `typing` container
aliases and `Optional`/`Union` forms were replaced with built-in
generics and `|` unions where valid, while runtime-sensitive sites were
adjusted manually so forward references, type checks, and
schema/type-introspection behavior remain valid without adding `from
__future__ import annotations`.

Additional follow-up changes include:
- Moving `Annotated` imports to the standard library where supported
- Keeping `typing_extensions.Self` in place where it is still required
for Python 3.10 compatibility
- Removing the redundant MCP CLI runtime guard that duplicated the
package-level Python requirement
- Updating README content, installation guidance, MCP docs, notebook
prose, and tests that assert exact type-hint shapes so they align with
the new support floor and modernized annotations

## Note for Reviewers

The docs build still reports existing Sphinx warnings that are unrelated
to this PR.

## Testing

The following checks were run during development:
- `make check-sort-imports`
- `make check-format`
- `make check-types`
- `uv run python -m tests.test_imports redisvl`
- `uv run python -m pytest tests/unit/test_validation.py
tests/unit/test_index_schema_type_issue.py
tests/unit/test_base_vectorizer.py tests/unit/test_cli_utils.py
tests/unit/test_hybrid_types.py
tests/unit/test_mcp/test_search_tool_unit.py
tests/unit/test_mcp/test_upsert_tool_unit.py
tests/integration/test_mcp/test_server_startup.py
tests/integration/test_mcp/test_upsert_tool.py -q`
- `make docs-build`

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Medium risk because it is a breaking support-policy change (Python
>=3.10) and touches broad, core surfaces
(index/storage/cache/router/CLI) via widespread type-annotation
refactors that could affect runtime edge cases if any typing changes
leaked into behavior.
> 
> **Overview**
> Drops Python 3.9 support across the project: updates `pyproject.toml`
(`requires-python` >=3.10), removes 3.9 from classifiers/Black targets,
and adjusts optional dependency markers now that the whole package
requires 3.10+.
> 
> Aligns CI and docs with the new minimum by removing 3.9 from the test
matrix, adding 3.14 to lint, and updating installation/MCP documentation
and a notebook to state Python 3.10+.
> 
> Modernizes repo-owned Python sources to Python 3.10 typing syntax
(built-in generics and `|` unions) across caches, message history,
router, and the core `SearchIndex`/storage layer, and removes the
redundant MCP CLI runtime version guard.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
57bb351. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: vishal-bala

.github/workflows/lint.yml

@@ -15,19 +15,12 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        # Only lint on the min and max supported Python versions.
-        # It's extremely unlikely that there's a lint issue on any version in between
-        # that doesn't show up on the min or max versions.
-        #
-        # GitHub rate-limits how many jobs can be running at any one time.
-        # Starting new jobs is also relatively slow,
-        # so linting on fewer versions makes CI faster.
         python-version:
-          - "3.9"
           - "3.10"
           - "3.11"
           - "3.12"
           - "3.13"
+          - "3.14"
 
     steps:
     - name: Check out repository
@@ -62,4 +55,4 @@ jobs:
 
     - name: check-mypy
       run: |
-        make check-types
+        make check-types

.github/workflows/test.yml

@@ -62,7 +62,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
         redis-py-version: ["5.x", "6.x", "7.x"]
         redis-image: ["redis:8.2", "redis:8.4", "redis:latest"]
     steps:

README.md

@@ -45,7 +45,7 @@ Perfect for building **RAG pipelines** with real-time retrieval, **AI agents** w
 
 ## Installation
 
-Install `redisvl` into your Python (>=3.9) environment using `pip`:
+Install `redisvl` into your Python (>=3.10) environment using `pip`:
 
 ```bash
 pip install redisvl
@@ -57,8 +57,6 @@ Install the MCP server extra when you want to expose an existing Redis index thr
 pip install redisvl[mcp]
 ```
 
-The `redisvl[mcp]` extra requires Python 3.10 or newer.
-
 > For more detailed instructions, visit the [installation guide](https://docs.redisvl.com/en/latest/user_guide/installation.html).
 > For MCP concepts and setup, see the [RedisVL MCP docs](https://docs.redisvl.com/en/latest/concepts/mcp.html) and the [MCP how-to guide](https://docs.redisvl.com/en/latest/user_guide/how_to_guides/mcp.html).
 

docs/_extension/gallery_directive.py

@@ -9,7 +9,7 @@
 abstracted into a standalone package if it proves useful.
 """
 from pathlib import Path
-from typing import Any, Dict, List
+from typing import Any
 
 from docutils import nodes
 from docutils.parsers.rst import directives
@@ -54,7 +54,7 @@ class GalleryDirective(SphinxDirective):
         "class-card": directives.unchanged,
     }
 
-    def run(self) -> List[nodes.Node]:
+    def run(self) -> list[nodes.Node]:
         if self.arguments:
             # If an argument is given, assume it's a path to a YAML file
             # Parse it and load it into the directive content
@@ -145,7 +145,7 @@ def run(self) -> List[nodes.Node]:
         return [container]
 
 
-def setup(app: Sphinx) -> Dict[str, Any]:
+def setup(app: Sphinx) -> dict[str, Any]:
     """Add custom configuration to sphinx app.
 
     Args:
@@ -158,4 +158,4 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     return {
         "parallel_read_safe": True,
         "parallel_write_safe": True,
-    }
+    }

docs/user_guide/13_langcache_semantic_cache.ipynb

@@ -14,7 +14,7 @@
     "\n",
     "Before you begin, ensure you have:\n",
     "- Installed RedisVL with the LangCache extra: `pip install redisvl[langcache]`\n",
-    "- Python 3.9+ (same as RedisVL)\n",
+    "- Python 3.10+ (same as RedisVL)\n",
     "- A LangCache service with a **cache ID** and **API key**. You can set up a LangCache service in Redis Cloud [here](https://cloud.redis.io/#/)\n",
     "- Optionally: **attributes** configured on your LangCache cache if you plan to pass `metadata` / `attributes` from RedisVL\n",
     "\n",

docs/user_guide/how_to_guides/mcp.md

@@ -436,10 +436,6 @@ pip install redisvl[mcp]
 
 If the configured vectorizer needs a provider SDK, install that provider extra too.
 
-### Unsupported Python Runtime
-
-RedisVL MCP requires Python 3.10 or newer even though the core package supports Python 3.9. Use a newer interpreter for the MCP server process.
-
 ### Configured Redis Index Does Not Exist
 
 The server only binds to an existing index. Create the index first, then point `indexes.<id>.redis_name` at that index name.

docs/user_guide/installation.md

@@ -11,7 +11,7 @@ There are a few ways to install RedisVL. The easiest way is to use pip.
 
 ## Install RedisVL with Pip
 
-Install `redisvl` into your Python (>=3.9) environment using `pip`:
+Install `redisvl` into your Python (>=3.10) environment using `pip`:
 
 ```bash
 $ pip install -U redisvl
@@ -54,10 +54,6 @@ To install **all** optional dependencies at once:
 $ pip install redisvl[all]
 ```
 
-```{note}
-The core RedisVL package supports Python 3.9+, but the `redisvl[mcp]` extra requires Python 3.10 or newer because the MCP server depends on `fastmcp`.
-```
-
 ## Install RedisVL from Source
 
 To install RedisVL from source, clone the repository and install the package using `pip`:

pyproject.toml

@@ -4,7 +4,7 @@ name = "redisvl"
 version = "0.17.1"
 description = "Python client library and CLI for using Redis as a vector database"
 authors = [{ name = "Redis Inc.", email = "applied.ai@redis.com" }]
-requires-python = ">=3.9.2,<3.15"
+requires-python = ">=3.10,<3.15"
 readme = "README.md"
 license = "MIT"
 keywords = [
@@ -15,7 +15,6 @@ keywords = [
     "vector-search",
 ]
 classifiers = [
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
@@ -36,7 +35,7 @@ dependencies = [
 
 [project.optional-dependencies]
 mcp = [
-    "fastmcp>=2.0.0 ; python_version >= '3.10'",
+    "fastmcp>=2.0.0",
     "pydantic-settings>=2.0",
 ]
 mistralai = ["mistralai>=1.0.0"]
@@ -102,7 +101,7 @@ dev = [
     "types-pyyaml",
     "types-pyopenssl",
     "testcontainers>=4.3.1,<5",
-    "cryptography>=44.0.1 ; python_version > '3.9.1'",
+    "cryptography>=44.0.1",
     "codespell>=2.4.1,<3",
     "langcache>=0.9.0",
 ]
@@ -124,7 +123,7 @@ default-groups = [
 ]
 
 [tool.black]
-target-version = ['py39', 'py310', 'py311', 'py312', 'py313']
+target-version = ['py310', 'py311', 'py312', 'py313', 'py314']
 exclude = '''
 (
   | \.egg

redisvl/cli/mcp.py

@@ -73,7 +73,6 @@ def __init__(self):
     def _run(self, args):
         """Validate the environment, build the server, and serve stdio requests."""
         try:
-            self._ensure_supported_python()
             settings_cls, server_cls = self._load_mcp_components()
             settings = settings_cls.from_env(
                 config=args.config,
@@ -94,20 +93,6 @@ def _run(self, args):
             self._print_error(str(exc))
             raise SystemExit(1)
 
-    @staticmethod
-    def _ensure_supported_python():
-        """Fail fast when the current interpreter cannot support MCP extras."""
-        if sys.version_info < (3, 10):
-            version = "%s.%s.%s" % (
-                sys.version_info.major,
-                sys.version_info.minor,
-                sys.version_info.micro,
-            )
-            raise RuntimeError(
-                "RedisVL MCP CLI requires Python 3.10 or newer. "
-                "Current runtime is Python %s." % version
-            )
-
     @staticmethod
     def _load_mcp_components():
         """Import optional MCP dependencies only on the `rvl mcp` code path."""

redisvl/cli/utils.py

@@ -1,6 +1,5 @@
 import os
 from argparse import ArgumentParser, Namespace
-from typing import Optional
 from urllib.parse import quote, urlparse, urlunparse
 
 from redisvl.redis.constants import REDIS_URL_ENV_VAR
@@ -22,7 +21,7 @@ def _has_explicit_connection_options(args: Namespace) -> bool:
     )
 
 
-def _get_auth_credentials(args: Namespace) -> tuple[Optional[str], Optional[str]]:
+def _get_auth_credentials(args: Namespace) -> tuple[str | None, str | None]:
     return getattr(args, "user", None) or None, getattr(args, "password", None) or None