fix: support CPython 3.10 release parity

Author: n24q02m

.github/workflows/ci.yml

@@ -68,8 +68,12 @@ jobs:
   # Lint & Test (Python)
   # ============================================================================
   lint-and-test:
-    name: Lint & Test
+    name: Lint & Test (Python ${{ matrix.python }})
     if: github.event_name == 'pull_request' || github.event_name == 'push'
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13", "3.14"]
     runs-on: ubuntu-latest
     steps:
       - name: Harden Runner
@@ -81,7 +85,7 @@ jobs:
       - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
       - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
-          python-version: "3.13"
+          python-version: ${{ matrix.python }}
 
       - run: uv sync --locked --group dev
       - run: uv run ruff check .
@@ -91,7 +95,7 @@ jobs:
       - name: Run tests with coverage
         run: |
           if [ -d "tests" ] && [ "$(ls -A tests/*.py 2>/dev/null)" ]; then
-            uv run pytest --tb=short --cov=fastretrieval --cov-report=xml
+            uv run pytest -m "not integration" --tb=short --cov=fastretrieval --cov-report=xml
           else
             echo "No tests found, skipping..."
           fi

AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md - fastretrieval
 
-Fast multi-model retrieval runtime: ONNX and GGUF embeddings, reranking, and a declarative model contract. Python >= 3.11 (tested 3.11-3.14), uv.
+Fast multi-model retrieval runtime: ONNX and GGUF embeddings, reranking, and a declarative model contract. Python 3.10-3.14, uv.
 
 ## Package Identity
 
@@ -48,7 +48,7 @@ mise run fix       # ruff check --fix + ruff format
 - `testpaths = ["tests"]`, `pythonpath = ["."]`
 - Integration marker: `@pytest.mark.integration` (requires model downloads: ONNX ~1.2 GB, Q4F16 ~1 GB, GGUF ~756 MB)
 - Integration test files: `test_integration.py` (ONNX), `test_integration_q4f16.py`, `test_integration_gguf.py`
-- CI runs: `uv run pytest -m "not integration" --tb=short`
+- CI runs: `uv run pytest -m "not integration" --tb=short` on CPython 3.10-3.14.
 
 ## Code Style
 
@@ -57,7 +57,7 @@ mise run fix       # ruff check --fix + ruff format
 - **Line length**: 99
 - **Quotes**: Double quotes
 - **Indent**: 4 spaces
-- **Target**: Python 3.13
+- **Target**: Python 3.10
 
 ### Ruff Rules
 
@@ -92,9 +92,9 @@ from fastretrieval.common.types import PathInput, Device
 ### Type Hints
 
 - Full type hints everywhere: parameters, return types, variables
-- **Python 3.12+ type alias syntax**: `type PathInput = str | Path`
-- **Python 3.12+ generics**: `class ModelManagement[T: BaseModelDescription]:`, `def iter_batch[T](...)`
-- Union types: `str | None` (not `Optional`), `list[str]` (not `List`)
+- Built-in generics: `list[str]` and `dict[str, Any]`
+- Union syntax: `str | None` (Python 3.10+)
+- Do not introduce syntax or standard-library APIs newer than Python 3.10.
 - `py.typed` marker file present
 
 ### Naming Conventions

README.md

@@ -52,6 +52,7 @@ uses a declarative model contract so built-in Qwen3 reference models and custom
 share the same runtime, and supports Matryoshka (MRL) truncation, instruction-aware queries,
 and optional GPU acceleration. It is derived from [fastembed](https://github.com/qdrant/fastembed)
 and keeps Qwen3 model names as model identifiers rather than as the package boundary.
+Supported runtimes are CPython 3.10, 3.11, 3.12, 3.13, and 3.14.
 
 ## What it does
 

fastretrieval/common/compat.py

@@ -0,0 +1,10 @@
+"""Compatibility shims for the oldest supported CPython runtime."""
+
+from enum import Enum
+
+
+class StrEnum(str, Enum):
+    """Backport the small ``enum.StrEnum`` surface used by the package."""
+
+    def __str__(self) -> str:
+        return str(self.value)

fastretrieval/common/model_description.py

@@ -1,7 +1,8 @@
 from dataclasses import dataclass, field
-from enum import StrEnum
 from typing import Any
 
+from fastretrieval.common.compat import StrEnum
+
 
 @dataclass(frozen=True)
 class ModelSource:

fastretrieval/common/types.py

@@ -1,10 +1,11 @@
-from enum import StrEnum
 from pathlib import Path
 from typing import Any, TypeAlias
 
 import numpy as np
 from numpy.typing import NDArray
 
+from fastretrieval.common.compat import StrEnum
+
 
 class Device(StrEnum):
     CPU = "cpu"

fastretrieval/common/utils.py

@@ -5,7 +5,7 @@
 from collections.abc import Iterable
 from itertools import islice
 from pathlib import Path
-from typing import TypeVar
+from typing import TypeVar, cast
 
 import numpy as np
 from numpy.typing import NDArray
@@ -77,7 +77,10 @@ def last_token_pool(input_array: NumpyArray, attention_mask: NDArray[np.int64])
     """
     batch_size, seq_len = attention_mask.shape
     if seq_len == 0:
-        return np.zeros((batch_size,) + input_array.shape[2:], dtype=input_array.dtype)
+        return cast(
+            NumpyArray,
+            np.zeros((batch_size,) + input_array.shape[2:], dtype=input_array.dtype),
+        )
 
     # ⚡ Bolt: Fast path if all samples end with a valid token (e.g. left-padding or no padding)
     # Fast boolean reduction using .all() (~15% faster than .sum() == shape[0])

fastretrieval/convert/onnx.py

@@ -113,16 +113,21 @@ def quantize_q4f16(fp32_path: Path, out_path: Path) -> float:
     require_convert_deps("onnx", "onnxconverter_common", "onnxruntime", "onnx_ir")
     import onnx
     from onnxconverter_common import float16
-    from onnxruntime.quantization.matmul_nbits_quantizer import MatMulNBitsQuantizer
+    from onnxruntime.quantization.matmul_nbits_quantizer import (
+        DefaultWeightOnlyQuantConfig,
+        MatMulNBitsQuantizer,
+    )
 
     out_path.parent.mkdir(parents=True, exist_ok=True)
     logger.info("quantizing to Q4F16: {}", out_path)
     quantizer = MatMulNBitsQuantizer(
         model=str(fp32_path),
-        bits=4,
-        block_size=128,
-        is_symmetric=True,
-        accuracy_level=4,
+        algo_config=DefaultWeightOnlyQuantConfig(
+            block_size=128,
+            is_symmetric=True,
+            accuracy_level=4,
+            bits=4,
+        ),
     )
     quantizer.process()
 

fastretrieval/parallel_processor.py

@@ -3,14 +3,14 @@
 from collections.abc import Iterable
 from copy import deepcopy
 from dataclasses import dataclass
-from enum import StrEnum
 from multiprocessing import Queue, get_context
 from multiprocessing.context import BaseContext
 from multiprocessing.process import BaseProcess
 from multiprocessing.sharedctypes import Synchronized as BaseValue
 from queue import Empty
 from typing import Any
 
+from fastretrieval.common.compat import StrEnum
 from fastretrieval.common.types import Device
 
 # Single item should be processed in less than:

pyproject.toml

@@ -4,14 +4,15 @@ version = "1.0.0"
 description = "Fast multi-model retrieval runtime: ONNX and GGUF embeddings, reranking, and a declarative model contract"
 readme = "README.md"
 license = "Apache-2.0"
-requires-python = ">=3.11"
+requires-python = ">=3.10"
 authors = [{ name = "n24q02m" }]
 keywords = ["vector", "embedding", "reranking", "qwen3", "onnx", "onnxruntime"]
 classifiers = [
     "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: Apache Software License",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
@@ -20,7 +21,10 @@ classifiers = [
 ]
 
 dependencies = [
-    "numpy>=2.4.6,<2.5",
+    "numpy>=2.2.0,<2.5",
+    # ORT 1.24 dropped cp310 wheels; keep the last cp310-compatible line for
+    # Python 3.10 while newer interpreters use the current compatible release.
+    "onnxruntime>=1.23.2,<1.24; python_version == '3.10'",
     "onnxruntime>1.20.0; python_version >= '3.11'",
     "tqdm>=4.70.0",
     "requests>=2.34.2",
@@ -64,6 +68,10 @@ packages = ["fastretrieval"]
 version_toml = ["pyproject.toml:project.version"]
 tag_format = "v{version}"
 commit_message = "chore(release): v{version}"
+build_command = """
+uv lock --upgrade-package "$PACKAGE_NAME"
+uv build
+"""
 major_on_zero = false
 
 [tool.semantic_release.changelog]
@@ -88,7 +96,7 @@ call-non-callable = "warn"
 
 [tool.ruff]
 line-length = 99
-target-version = "py311"
+target-version = "py310"
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "UP", "B", "SIM"]