feat: support Python 3.14+ via pyo3 abi3 stable ABI (#516)

## Description

Sets pyo3 params to support python above 3.13

Fixes #(408

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- Updated Cargo.toml

## Testing

Describe the tests you ran to verify your changes:

- [ ] Unit tests pass (`pytest`)
- [ ] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [ ] New tests added for new functionality
- [x] Manual testing performed

## Test Output

```
Compiles
```

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [ ] I have updated the CHANGELOG.md if applicable

Co-authored-by: Tejas Chopra <chopratejas@gmail.com>

.github/workflows/release.yml

@@ -603,6 +603,22 @@ jobs:
                 *) echo "ERROR: unknown wheel target $WHEEL_TARGET" >&2; exit 1 ;;
               esac
               whl=$(find /wheels -maxdepth 1 -type f -name "headroom_ai-*-${py_tag}-${py_tag}-${arch_tag}.whl" -print -quit)
+              if [ -z "$whl" ]; then
+                # No version-specific wheel — fall back to a stable-ABI
+                # (abi3) wheel. A cp3<floor>-abi3 wheel installs on any
+                # CPython >= floor, which is what makes a single wheel
+                # forward-compatible to 3.14+ (Cargo.toml pyo3 abi3-py310).
+                # Pick the abi3 wheel whose floor is <= the interpreter.
+                py_minor=${PYTHON_VERSION#*.}
+                abi3=$(find /wheels -maxdepth 1 -type f -name "headroom_ai-*-abi3-${arch_tag}.whl" -print -quit)
+                if [ -n "$abi3" ]; then
+                  abi3_base=${abi3##*/}
+                  abi3_floor=${abi3_base#*-cp3}
+                  abi3_floor=${abi3_floor%%-*}
+                  case "$abi3_floor" in *[!0-9]*) abi3_floor= ;; esac
+                  if [ -n "$abi3_floor" ] && [ "$abi3_floor" -le "$py_minor" ]; then whl="$abi3"; fi
+                fi
+              fi
               if [ -z "$whl" ]; then
                 echo "ERROR: no wheel matching python=$PYTHON_VERSION arch=$arch_tag in /wheels/" >&2
                 find /wheels -maxdepth 1 -type f -printf "%f\n" >&2
@@ -632,6 +648,19 @@ jobs:
           py_tag=cp$(echo "$PYTHON_VERSION" | tr -d .)
           # macOS wheels are tagged macosx_*_arm64 (Apple Silicon only).
           whl=$(find dist -maxdepth 1 -type f -name "headroom_ai-*-${py_tag}-${py_tag}-macosx_*_arm64.whl" -print -quit)
+          if [ -z "$whl" ]; then
+            # Stable-ABI (abi3) fallback — see the Linux path above. A
+            # cp3<floor>-abi3 wheel installs on any CPython >= floor.
+            py_minor=${PYTHON_VERSION#*.}
+            abi3=$(find dist -maxdepth 1 -type f -name "headroom_ai-*-abi3-macosx_*_arm64.whl" -print -quit)
+            if [ -n "$abi3" ]; then
+              abi3_base=${abi3##*/}
+              abi3_floor=${abi3_base#*-cp3}
+              abi3_floor=${abi3_floor%%-*}
+              case "$abi3_floor" in *[!0-9]*) abi3_floor= ;; esac
+              if [ -n "$abi3_floor" ] && [ "$abi3_floor" -le "$py_minor" ]; then whl="$abi3"; fi
+            fi
+          fi
           if [ -z "$whl" ]; then
             echo "ERROR: no macOS wheel matching python=$PYTHON_VERSION"
             find dist -maxdepth 1 -type f -exec basename {} \;

Cargo.toml

@@ -55,7 +55,7 @@ tokio = { version = "1", features = ["macros", "rt-multi-thread", "signal"] }
 axum = "0.7"
 tower = "0.5"
 reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] }
-pyo3 = "0.22"
+pyo3 = { version = "0.22", features = ["abi3-py310"] }
 # Phase D PR-D1: AWS SigV4 signing for native Bedrock InvokeModel route.
 # `aws-sigv4` provides the canonical-request + signing-key implementation;
 # `aws-config` resolves credentials from the standard provider chain

pyproject.toml

@@ -39,6 +39,8 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Typing :: Typed",