Upgrade to Python 3.14

Summary

Python 3.14 is scheduled for release on October 7, 2025. We should upgrade policyengine-api to support Python 3.14 and take advantage of its performance improvements and new features.

Key Benefits for PolicyEngine API

Performance Improvements

• 3-5% geometric mean performance improvement - faster API response times
• Up to 30% faster for certain workloads with newer compilers
• Incremental garbage collection with reduced pause times
• Better throughput for concurrent requests

Free-Threaded Python (No GIL)

• Free-threaded mode is now officially supported
• Could enable true parallel request processing in Flask
• Potential to remove reliance on worker processes for concurrency
• Better utilization of multi-core systems
• Performance penalty in single-threaded mode reduced to just 5-10%

Concurrency Features

• InterpreterPoolExecutor for parallel policy calculations
• Multiple interpreters in standard library
• Could improve API performance for batch calculations
• Better context variable and threading support

Type System Improvements

• Deferred evaluation of type annotations reduces import overhead
• Better type hint performance for API validation
• New annotationlib module for annotation introspection

Other Improvements

• Native Zstandard compression for faster data serialization/deserialization
• Improved error messages for better API debugging
• Enhanced HMAC implementation using verified code (security benefit)
• Simpler exception handling syntax (PEP 758)

Implementation Plan

1. Wait for upstream dependencies - Ensure policyengine-core and country models support Python 3.14 first
2. Update pyproject.toml to include Python 3.14 in supported versions
3. Add Python 3.14 to CI/CD test matrix
4. Test API endpoints with Python 3.14
5. Evaluate free-threaded mode for production deployment
6. Update Google Cloud App Engine runtime configuration
7. Update documentation

Priority

Medium-High - The API will benefit significantly from performance improvements and free-threaded mode. However, should wait for:

• PolicyEngine/policyengine-core#399
• PolicyEngine/policyengine-us#6626
• PolicyEngine/policyengine-uk#1353

References

• Python 3.14 Release Schedule
• What's New in Python 3.14
• PEP 703: Free-threaded CPython

First check policyengine-core#399, policyengine-us#6626, and policyengine-uk#1353 for Python 3.14 support. Then inspect pyproject.toml, the CI/CD test matrix, Google Cloud App Engine runtime configuration, API endpoint tests, and documentation. Done means the API supports Python 3.14 across these surfaces and its endpoints pass under that version.