feat: Support Python 3.14 free-threaded

.github/workflows/_test.yml

@@ -75,6 +75,85 @@ jobs:
           run: |
             ${{ matrix.platform.python_exec }} -m pytest --capture=no python/cocoindex/tests
 
+    build-test-free-threaded:
+        runs-on: ubuntu-latest
+        env:
+          RUSTFLAGS: "-C debuginfo=0"
+          CARGO_INCREMENTAL: "0"
+          SCCACHE_GHA_ENABLED: "true"
+          RUSTC_WRAPPER: "sccache"
+
+        steps:
+        - uses: actions/checkout@v4
+          with:
+            fetch-depth: 1
+
+        - name: Run sccache-cache
+          uses: mozilla-actions/sccache-action@v0.0.9
+
+        - name: Setup Python (3.14 free-threaded)
+          uses: actions/setup-python@v5
+          with:
+            python-version: '3.14'
+            allow-prereleases: true
+            freethreaded: true
+
+        - name: Verify interpreter configuration
+          run: |
+            python - <<'PY'
+import sys
+import sysconfig
+
+print(f"Python version: {sys.version}")
+print(f"GIL enabled? {getattr(sys, '_is_gil_enabled', 'missing')}")
+print(f"SOABI: {sysconfig.get_config_var('SOABI')}")
+if not hasattr(sys, '_is_gil_enabled') or sys._is_gil_enabled():
+    raise SystemExit("Free-threaded interpreter with disabled GIL is required")
+PY
+
+        - run: rustup toolchain install stable --profile minimal
+
+        - name: Rust tests (no default features)
+          run: cargo test --no-default-features --verbose
+
+        - name: Rust tests
+          run: cargo test --verbose
+
+        - name: Setup venv
+          run: |
+            python -m venv .venv
+
+        - name: Install Python toolchains
+          run: |
+            .venv/bin/python -m pip install --upgrade pip
+            .venv/bin/python -m pip install maturin
+
+        - name: Python build (free-threaded)
+          run: |
+            .venv/bin/python -m maturin develop --no-default-features -F free-threaded --strip -E all-ci,free-threaded
+
+        - name: Verify CocoIndex in free-threaded mode
+          run: |
+            .venv/bin/python - <<'PY'
+import sys
+import sysconfig
+import cocoindex
+
+print(f"CocoIndex version: {cocoindex.__version__}")
+print(f"GIL enabled? {getattr(sys, '_is_gil_enabled', 'missing')}")
+print(f"SOABI: {sysconfig.get_config_var('SOABI')}")
+if sys._is_gil_enabled():
+    raise SystemExit("Expected free-threaded interpreter with disabled GIL")
+PY
+
+        - name: Python type check (mypy)
+          run: |
+            .venv/bin/python -m mypy python
+
+        - name: Python tests (free-threaded)
+          run: |
+            .venv/bin/python -m pytest --capture=no python/cocoindex/tests
+
     validate-3p-notices:
         runs-on: ubuntu-latest
         steps:

Cargo.toml

@@ -10,10 +10,10 @@ license = "Apache-2.0"
 
 [workspace.dependencies]
 pyo3 = { version = "0.27.1", features = [
-    "abi3-py311",
     "auto-initialize",
     "chrono",
     "uuid",
+    "extension-module",
 ] }
 pythonize = "0.27.0"
 pyo3-async-runtimes = { version = "0.27.0", features = ["tokio-runtime"] }

pyproject.toml

@@ -82,6 +82,8 @@ all = [
 # This is the set of dependencies that needs to be installed for the CI workflow.
 all-ci = ["pytest", "pytest-asyncio", "mypy", "pydantic>=2.11.9"]
 
+free-threaded = ["sentence-transformers>=3.3.1", "colpali-engine"]
+
 [tool.mypy]
 python_version = "3.11"
 strict = true

rust/cocoindex/Cargo.toml

@@ -11,7 +11,8 @@ crate-type = ["cdylib"]
 
 [features]
 default = ["legacy-states-v0"]
-legacy-states-v0 = []
+legacy-states-v0 = [ "pyo3/abi3-py311"]
+free-threaded = []
 
 [dependencies]
 cocoindex_utils = { path = "../utils", features = [

rust/cocoindex/src/py/mod.rs

@@ -603,7 +603,7 @@ fn seder_roundtrip<'py>(
 }
 
 /// A Python module implemented in Rust.
-#[pymodule]
+#[pymodule(gil_used = false)]
 #[pyo3(name = "_engine")]
 fn cocoindex_engine(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add("__version__", env!("CARGO_PKG_VERSION"))?;