Next major: require Python 3.11 and retire legacy integration versions

Start with py/pyproject.toml, .github/workflows/checks.yaml, py/nox_session_constraints.py, and the integration patchers and tests named in the issue. First map the Python version matrices and existing integration floor tests, then validate each proposed minimum against its relevant tracing behavior and migration constraints. Done means the Python 3.11 floor and CI changes are covered, compatibility cleanup is verified, and every adopted integration floor has dedicated tests and migration guidance.

Goal and scope

For the next major SDK release, raise the minimum supported Python version from 3.10 to 3.11 and retire integration version ranges where doing so removes identifiable compatibility cost.

Python 3.11 is the agreed floor. Integration version drops below are a researched proposal for that release, not changes already implemented. Top-level namespace/import-path cleanup from #956 is out of scope.

Research baseline: repository commit dec33a82b2b6387c9fc4b1f0a7122c434e113acb and published upstream metadata inspected on 2026-10-16. latest in the matrix is a pinned test version, not a permanent support policy. No customer-version telemetry was available for this review; package age/download counts are not evidence that customers can migrate without impact.

1. Python: require 3.11+, retain CI coverage through 3.15

• Change py/pyproject.toml to requires-python = ">=3.11.0"; remove the Python 3.10 classifier.
• Remove 3.10 from all three Python CI matrices: static checks, installation/import smoke tests, and sharded nox tests. Keep 3.11, 3.12, 3.13, 3.14, and 3.15.
• This removes 15 configured jobs: 1 static-check job, 2 smoke jobs, and 12 nox shard jobs. Those matrices go from 90 jobs to 75; this is not a claim of a 17% wall-clock speedup.
• Update contributing/install docs, the pytest-plugin requirements, and examples that resolve the local SDK. Audit deprecated ADK/LangChain packages' local-source links, .python-version files, and lockfiles so their compatibility CI does not try to run the new SDK on 3.10. Their historical published-package compatibility is a separate decision.
• Regenerate affected lockfiles without an intentional general dependency upgrade.

Python 3.10 reached upstream end of life on 2026-10-01. Python 3.11 remains security-supported until October 2027. See the Python lifecycle table.

Compatibility cleanup enabled by 3.11

• Replace direct uses of the exceptiongroup backport in the logger, Harbor plugin, and tests with built-in ExceptionGroup / BaseExceptionGroup; remove the SDK's direct dependency. Transitive dependencies may still install the package.
• Import tomllib directly in nox and remove the tomli fallback.
• Remove 3.10-only dependency resolution workarounds, including the lint onnxruntime<1.24 marker and unnecessary Python >=3.11 markers/gates.
• Make the existing TaskGroup/context test unconditional on supported Python versions. Audit other 3.10-only comments/fallbacks individually; do not rewrite unrelated async code merely because newer primitives are available.

Python 3.11 added exception groups, tomllib, and TaskGroup.

Compatibility code that remains

• Keep the import-lock workaround guarded by sys.version_info < (3, 12): it still covers Python 3.11.
• Keep MarkAsyncWrapper / the custom async marker: inspect.markcoroutinefunction arrived in 3.12.
• Keep typing_extensions where the supported typing surface needs it; raising the Python floor does not justify removing it wholesale.
• Preserve integration-specific Python/platform restrictions. AI SDK and Harbor still require Python 3.12+; upstream wheel/dependency gaps on 3.14/3.15 do not disappear when 3.10 is dropped.

Sources: SDK metadata and dependency groups, CI matrices, Python/platform routing, import-lock compatibility, async marker.

2. Integration versions proposed for retirement

The strongest cuts below remove a concrete implementation or dependency-era split. New minimum versions not already in the matrix must pass dedicated floor tests before this proposal becomes a release support promise. Python 3.11 itself does not force these provider-version cuts.

Integration	Current historical matrix pins to retire	Proposed supported floor / retained lines	Why this cutoff
Mistral	1.12.4	mistralai>=2.10.1; retain 2.x and 3.x coverage	2.10.1 is already an explicitly configured test point. The v2 module layout removes 32 duplicated old-layout patcher classes, test import fallbacks, and 29 old cassettes.
AgentScope	1.0.0	agentscope>=2.0.9; add a fixed floor entry alongside rolling latest	Removes 1.x agent/tool entry points and special stream-usage interception. 2.0.9 is the currently tested 2.x point and the TeamPipeline streaming capability boundary.
Pipecat	1.3.0	pipecat-ai>=1.12.0; freeze this as an explicit floor	1.12.0 provides native observer frame deduplication. Remove the older manual seen-frame-ID set and version branches; audit the old websockets test dependency.
Pydantic AI	Direct/logfire: 1.10.0; OpenAI-wrapping path: 0.1.9, 1.0.1	Candidate ranges: 1.x >=1.107.6 and 2.x >=2.44.0, retaining current 2.55.0 coverage; both new baseline pins require validation	Avoid forcing V1 users onto V2 merely to simplify our matrix. The newer V1 baseline uses OTel logs instead of removed _events and the newer ToolManager entry point. It should let us retire the old OTel/genai-prices constraints after validating the replacement baseline across all three sessions.
Claude Agent SDK	0.1.10	Conservative already-configured baseline 0.2.165, fixed separately from rolling latest	Retires the old transport/API combination requiring an explicit MCP v1 test constraint. This is a known modern test point, not a claim that every earlier 0.2 release has been validated.
Agno	2.1.0, 2.4.0	Candidate 2.5.0 floor; retain 3.x coverage	Upstream 2.5 refactored Agent/Team internals. It is a meaningful candidate boundary for removing eight private run/stream patchers and using public run/arun wrappers. Raising only to 2.4 would save a matrix entry while retaining the compatibility implementation. New floor cassettes/tests are required.
DSPy	2.6.0	dspy>=3.4.0; freeze the already configured newer release as a floor	Removes old image serialization handling and test workarounds. This deliberately excludes early 3.x too: metadata/source inspection does not establish that 3.0 has the serialization shape our tracing expects.
LiveKit Agents	1.3.1	livekit-agents>=1.8.6; freeze the already configured newer release as a floor	Removes the OTel <1.39 test environment and nox's special orphan-package uninstall. This is dependency/CI simplification; do not assume every old session patcher becomes obsolete.
OpenTelemetry API/SDK/OTLP HTTP exporter	1.16.0 across all three keys	Candidate 1.34.0 floor; retain explicit 1.44.0 plus rolling latest	Removes the ancient encoder import fallback and old-version Python skip without forcing the whole ecosystem onto OTel 1.44. Add a real 1.34.0 baseline; keep pre/post-1.45 exporter coverage and filtering still required by 1.34 encoders. Replacing 1.16 with 1.34 keeps three OTel test variants, so this saves compatibility code rather than CI parameters.

Evidence and migration implications

• Mistral: the official v1→v2 migration guide documents moving imports to mistralai.client and renamed request/response types. The SDK duplicates old/new module targets in Mistral patchers. Users must migrate their provider imports/types, not only update a dependency constraint.

• AgentScope: our patchers explicitly distinguish the 1.x/2.x agent and toolkit APIs and gate TeamPipeline at 2.0.9. Preserve tracing behavior for the retained API. Dropping AgentScope 1.x plus Claude 0.1.10 can remove the explicit test-mcp-v1 workaround group, but does not mean the ecosystem no longer uses MCP 1.x.

• Pipecat: 1.12.0 release notes document first-push observer behavior. Our tracing code has the exact >=1.12.0 branch. Preserve terminal-frame handling, observer shutdown, and single-span behavior when simplifying it. Its local-smart-turn/moondream extras now require Transformers >=5.10.0 and its MCP extra requires MCP 2; include these application dependency changes in migration guidance.

• Pydantic AI: 1.107.6 is an official V1 maintenance release carrying security backports; V1 is still maintained as of this audit, so this is not an upstream-EOL argument; recheck that policy when scheduling the major release. The same fixes landed in V2 at 2.44.0. If adopting security-patch support floors, document 1.x >=1.107.6 and 2.x >=2.44.0 separately and validate a 2.44.0 floor too; a single >=1.107.6 comparison also admits older, unpatched V2 releases. The current shared min/max gate cannot express the disjoint policy by itself, so implementation must handle the ranges explicitly. Keep optional-feature gates such as conversation= requiring 2.55.0. Do not remove alternate wrapping approaches merely because old provider versions are retired.

• OpenTelemetry: CrewAI 1.13.0 metadata requires OTel ~=1.34.0; ADK 2.11.0 metadata requires >=1.39,<=1.42.1. A global minimum of 1.44 would unnecessarily exclude both retained integrations. The proposed 1.34.0 baseline is a new test target, not an existing tested floor. Retain the encoder null-value filtering and both sides of the 1.45 exporter-header change.

• Agno: the 2.5 release and tagged Agent/Team sources identify the internal refactor. Validate sync/async streaming, continuation/HITL, workflows and evals at the proposed floor. Keep model invoke/response patchers and feature gates for later 2.x/3.x additions: these are not all old-version shims.

• DSPy: compare the serializer in 3.0 with 3.3; do not infer early 3.x compatibility from the current 3.4 test point. Our image normalization identifies the old 2.6 representation. Audit Pillow usage before deleting that test dependency.

• LiveKit: the 1.3.1 and 1.8.6 packages span the removed LogData / newer ReadableLogRecord API generation. Review the nox setup and remove old constraints only after the final installed environment passes dependency checks. Keep LiveKit's current Python/platform restrictions until upstream installation support is verified.

3. Smaller or conditional cuts: separate from the core retirement list

These are reasonable follow-ups, but do not have the same implementation savings or established new baseline coverage. Do not silently bundle them into the Python change.

Integration	Possible drop / new floor	Research conclusion
OpenAI	Retire 1.71.0/1.77.0; floor 1.92.0	Modest matrix/cassette reduction: two primary variants and 110 old cassettes. Keep OpenAI 1.x; add explicit 2.x coverage alongside 3.x because retained integrations span those dependency eras. HTTP/2 and BTX floor variants must move to the new oldest pin, not disappear.
Google GenAI	Retire 1.30.0; floor 1.75.0	One variant and 31 cassettes removed. Keep 1.x/2.x; raising to 2.x would impose upstream behavior changes without eliminating most tracing code.
OpenAI Agents	Candidate 0.14.0 floor, retiring 0.0.19 and 0.13.6	Actual TaskSpanData/TurnSpanData capability boundary, but small implementation savings. Requires new floor coverage; raising only to 0.13.6 retains the optional-type guards.
Instructor	Candidate 1.13.0 floor, retiring 1.11.0	Real OpenAI dependency-era boundary: 1.12 requires OpenAI <2, 1.13 requires >=2,<3. New baseline coverage required. May let us refresh the old auxiliary OpenAI/jiter constraints.
LangChain core	Retire 0.3.28 / 0.x; candidate 1.4.6 floor	A major released around/after December 2026 is a reasonable point to drop the 0.3 line. Current helper requirements motivate 1.4.6, but it needs truthful new floor validation. See the coverage problem below. Application migration can be substantial.
Google ADK	Retire 1.14.1; floor 2.6.3, retaining latest 2.x	Mainly removes an old GenAI dependency generation and 11 large cassettes. Runtime savings are modest. A 2.6.3 floor does not remove workflow feature gates requiring 2.10+.
Transformers + Hugging Face Hub	Consider dropping Transformers 4.x and Hub 0.x together, with new explicit 5.x / 1.x baseline tests	A separate product/migration decision: Transformers 5 removed question-answering, text2text, summarization and translation pipelines. Dropping them can remove four patchers/helpers, but users must migrate APIs/models. Do not require Hub 2.x: retained LiteLLM requires Hub <2.

Relevant upstream sources: OpenAI Agents 0.14, Instructor 1.12 metadata, Instructor 1.13 metadata, LangChain release policy, LangChain v1 migration, ADK 2.6.3 metadata, Transformers v5 migration, Hub migration.

4. Keep these existing floors by default

The audit did not find sufficient compatibility-code savings to force these upgrades solely because a new SDK major is available. Keep numeric floor coverage plus rolling latest; do not replace each floor with whatever latest happens to mean that week.

Package / integration	Retain minimum	Reason
Anthropic	0.48.0	Requiring SDK 1.x introduces an upstream transport migration; retaining 0.x is not the same as retaining an obsolete API.
Cohere	5.0.0	SDK major versions and Cohere API v1/v2 are different boundaries. New SDKs still expose both API clients, so dropping SDK 5 does not remove v1 patchers.
LiteLLM	1.74.0	No separate old tracing implementation identified; choose a later floor only with a deliberate dependency/platform refresh. Do not choose 1.92 blindly: the matrix records wheel gaps.
OpenRouter	0.6.0	Both beta and GA response targets still exist in the newer SDK.
boto3 + botocore / Bedrock	1.34.116, updated together	Meaningful Converse/ConverseStream service-model baseline; no substantial old implementation fork.
AutoGen agentchat + ext	0.7.0, kept in sync	No material old-version runtime fork found.
Strands	1.20.0	Shared native tracing lifecycle; no clear obsolete implementation to remove.
AI SDK	0.4.0; own Python >=3.12	Shared callback adapter; Python 3.11 SDK support does not lower the provider's requirement.
Cursor SDK	1.0.25	Deliberate bridge-token bugfix floor already documented in the matrix.
LlamaIndex core	0.13.0	An old plugin dependency group exists, but tracing-code savings are limited; latest-only is not a justified policy.
DeepAgents	0.6.0	Already Python >=3.11; reuses LangChain callbacks without a distinct old tracing layer.
CrewAI	1.13.0	Deliberate causal-ID/usage feature baseline. Keep upstream Python limits and its supported OTel range.
Temporal	1.19.0	1.19 and 1.20 have the same upstream plugin interface. We can prune the 1.20 test point without claiming a runtime support drop; it does not remove old interceptor-keyword compatibility.
Harbor	0.16.0; own Python >=3.12	First AGENT_END lifecycle event needed by the plugin. Resume/backfill compatibility is not proven obsolete by a version bump.
Autoevals / braintrust-core	0.0.129 / 0.0.59	Scorer interoperability includes other libraries and user classes; preserve the shared contract.
pytest plugin	pytest 8.4.2	Both tested major lines work with Python 3.11; no obsolete hook implementation identified.
Discovery Engine / TypeSafe	Runtime floors 0.20.3 / 0.6.0	Each currently has only a latest matrix entry (0.20.5 / 0.7.4). No historical test point to remove; add baseline coverage rather than claim a support reduction.

The exact configured versions, runtime declarations, session mappings and cassette ownership are in pyproject.toml, noxfile.py, and the corresponding integrations/<provider>/integration.py / patcher files. All 41 matrix keys (including paired packages and test infrastructure) were inventoried.

5. Dependency and coverage findings that affect the rollout

Assert which provider version actually runs

test_langchain(0.3.28) installs old core, then installs the locked test-langchain group. A read-only export of that group currently contains langchain-core==1.6.9:

cd py
mise exec -- uv export --frozen --only-group test-langchain \
  --no-hashes --no-emit-project --no-header --no-annotate

The group includes langchain-openai 1.1.14 (core >=1.2.31) and langchain-anthropic 1.4.6 (core >=1.4.6). Installing it later replaces the older core. The session name therefore does not establish real 0.3.28 coverage. Add an installed-version assertion after all session setup, and use compatible auxiliary groups for whichever floors remain. Nox installation order.

Keep multiple dependency eras where needed

Current auxiliary groups preinstall OpenAI 1.99.9 for LiteLLM/Instructor and 2.31.0 for OpenAI Agents. Published metadata for configured newer releases says:

• LiteLLM 1.105.0: OpenAI >=2.20,<3 and Hub >=0.34,<2.
• Instructor 1.17.0: OpenAI >=2,<4.
• OpenAI Agents 0.23.1: OpenAI >=3,<4; older retained/candidate Agents baselines require OpenAI 2.x.

These are stale shared setup assumptions, not proof that newer LiteLLM/Instructor inherently need OpenAI 1.x. Provider installation happens later and can replace an earlier auxiliary pin. Audit the final resolved environment, use version-appropriate auxiliary constraints, and run dependency checks; do not infer a current CI failure without reproducing it. A blanket OpenAI 3.x minimum is incompatible with retained LiteLLM.

Similarly, Transformers 4.42 requires Hub <1, while LiteLLM's current metadata requires Hub <2. Hub-only floor increases must account for these combinations. Retained integrations are tested in separate environments; this proposal does not claim every upstream extra/package combination can be co-installed.

6. Rollout and acceptance criteria

• Publish an explicit support/deprecation table for the next major: Python 3.11 minimum, approved integration floors, unchanged floors, exact migration guidance, and removal release. Confirm customer impact before finalizing conditional cuts.
• Land Python metadata, CI, docs, local-source example/compatibility-package setup, and lockfile changes together. Keep the Python 3.11 compatibility paths identified above.
• For each approved integration cut, update documented/runtime support policy, relevant extras, auto-instrumentation and manual setup/wrap paths together. Removing a nox parameter alone only removes coverage. Provide actionable unsupported-version diagnostics rather than accidentally losing tracing silently.
• Add fixed numeric floor pins plus rolling latest, preserving meaningful dependency/major eras. Initially equal floor/latest pins must not let future weekly updates move the floor. New candidate floors in this issue are not validated support promises yet.
• Assert the installed provider version after all auxiliary dependency setup; check final dependency consistency. Cover paired packages (AutoGen, boto3/botocore, OTel) together.
• Validate retained/new minimums on Python 3.11 wherever upstream supports it, and run the remaining supported Python/platform CI combinations. Run test_core, test_types, and pylint using the authoritative nox sessions. Keep AI SDK/Harbor tests on Python >=3.12 and respect remaining provider caps.
• Re-run all retained affected provider versions in replay mode, not only latest. Pydantic needs direct, OpenAI-wrap and Logfire coexistence coverage; Agno needs sync/async/streams/continuations/workflows/evals; Pipecat needs frame dedup/terminal/shutdown; Claude needs transport-cassette playback and subprocess auto-instrumentation.
• Add/record new baseline cassettes where required under the repository's provider/subprocess workflow. Retiring a version does not itself justify re-recording retained cassettes. Preserve entry-point behavior, span shapes and lifecycle guarantees.
• Delete only retired version cassette directories and proven obsolete branches. Run make check-stale-cassettes; run affected check-unused-cassettes audits when deleting/renaming tests. Do not remove tracing functionality or later-version feature gates under the label of version cleanup.

Research performed: three parallel repository/upstream audits, versioned PyPI metadata and tagged-source inspection, enumeration of 94 configured nox sessions, cassette inventory, and the read-only LangChain dependency export above. No SDK implementation changes, provider test runs, or cassette recordings were made for this issue. New baseline behavior remains an implementation acceptance requirement.