Compatibility
Resolver constraints, accepted ranges, and exact validation evidence.
This matrix distinguishes three different claims: dependency resolution, adapter acceptance, and checks executed on exact versions. A successful install does not prove that an adapter accepted the framework. An accepted version does not prove every operation or model works.
Registry baseline, checked 16 September 2026: SDK 1.1.0, TypeScript middleware 0.1.0-alpha.2, Python middleware 0.1.0a1. Both client families require a compatible runtime; these docs exercised signed bin-v1.1.7.
Evidence levels#
- Engine loop: published packages, real native framework, signed local runtime, compression/reuse, actual recovery tool execution, exact paginated recovery, and unchanged-history assertions. No provider requests.
- Import: clean isolated install and import of the published adapter and its documentation integration module. This checks assembly only. No model call or compression claim.
- Source tests: code-owner tests on an unreleased checkout. Useful for assessing a candidate, not proof about a registry artifact.
The real Engine checks passed for TypeScript AI SDK and synchronous Python LangChain. Every other row below has import evidence only from this documentation validation. No paid provider, browser/edge, Linux container, or native Windows run was performed here.
TypeScript#
Use Node.js 22.13+ and ESM. Published middleware installs @caveman-ai/sdk ^1.1.0; it does not install the framework packages or enforce their ranges as peer dependencies. Install each selected native framework explicitly. The exact-version column records independent clean imports; only the AI SDK row also has Engine-loop evidence.
| Adapter | Published accepted range | Exact versions imported | Evidence |
|---|---|---|---|
| AI SDK | ai >=7.0.94 <8; provider >=4.0.11 <5 | ai 7.0.94, @ai-sdk/provider 4.0.11, zod 4.4.3 | Engine loop |
| OpenAI | openai >=7.12 <8 | 7.12.1 | Import |
| Anthropic | @anthropic-ai/sdk >=0.124 <1 | 0.124.0 | Import |
@google/genai >=2.21 <3 | 2.21.0 | Import | |
| LangChain | langchain >=1.5 <2; core >=1.2 <2; graph >=1.4 <2 | 1.5.10, 1.2.9, 1.4.14 | Import |
| Strands | @strands-agents/sdk >=1.17 <2 | 1.17.0 | Import |
| Mastra | @mastra/core >=1.65 <2 | 1.65.0 | Import |
| MCP | @modelcontextprotocol/sdk >=1.30 <2 | 1.30.0 | Import |
The published manifest calls semver ranges testedFrameworkVersions. That name is misleading: a range is not an exhaustive test result. Source changes separate supportedFrameworkVersions from exact pins and add a compatibility inspection export, but those changes are not in this published alpha. The broad published Anthropic guard is also not certification of every pre-1.0 minor version.
Version detection reads installed package metadata and resolves public framework entries. Bundlers must preserve accessible metadata and dependencies. ESM resolution behavior differs by Node version and loader configuration; an import can succeed while a later adapter gate declines. Inspect final reports. Keep framework dependencies external to server bundles; do not assume a single-file bundle or an edge isolate works because TypeScript compiles.
A clean combined install of Strands 1.17.0 and AI SDK V4 failed: Strands declares optional @ai-sdk/provider ^3.0.0, which conflicts with V4. Use separate projects or a framework-supported compatible dependency layout. Do not use --force to convert a resolver failure into a support claim.
Python#
Use Python 3.13+. Published middleware depends on caveman-sdk >=1.1 <2. Each extra selects its native family. Exact versions below came from separate clean environments, not one environment containing every framework.
| Extra | Published resolver requirements | Published adapter guard | Exact versions imported | Evidence |
|---|---|---|---|---|
| openai | openai >=2.20 <4 | openai >=3.10 <4 | openai 3.14.1 | Import |
| anthropic | anthropic >=1.4 <2 | Same range | anthropic 1.6.0 | Import |
google-genai >=2.22 <3 | Same range | google-genai 2.23.0 | Import | |
| langchain | langchain >=1.4 <2; core >=1.6 <2; graph >=1.2 <2 | Same ranges | langchain 1.4.1; core 1.6.3; graph 1.2.11 | Engine loop, sync |
| litellm | litellm >=1.100 <2 | Same range | litellm 1.101.0 | Import |
| strands | strands-agents >=1.55 <2 | Same range | strands-agents 1.56.0 | Import |
| agno | agno >=3.0 <4 | Same range | agno 3.0.10 | Import |
| crewai | crewai >=1.15 <2 | Same range | crewai 1.15.21 | Import |
| autogen | core, agentchat, ext each >=0.7 <0.8 | Same three ranges | all three 0.7.5 | Import |
| pydantic-ai | pydantic-ai >=2.42 <3 | pydantic-ai-slim >=2.42 <3 | pydantic-ai and slim 2.43.0 | Import |
| llama-index | llama-index-core >=0.14 <0.15 | Core range plus recognized provider guards | llama-index-core 0.14.24 | Import |
| asgi | fastapi >=0.141 <1; starlette >=1.6 <2 | Same two ranges | fastapi 0.141.1; starlette 1.6.0 | Import |
| mcp | mcp >=2.2 <3 | Same range | mcp 2.2.0 | Import |
The direct OpenAI extra can resolve an SDK the adapter declines. Pin OpenAI >=3.10,<4 for that adapter; the source manifest fixes this mismatch but has not been released. Provider dependencies selected transitively by another framework do not automatically satisfy the direct provider adapter.
LiteLLM may fetch its public model cost map on import and fall back to its bundled map if unavailable. That is not a model inference call. Model cost metadata is not billing verification.
Conflicting Python environments#
Inspect your resolved versions rather than copying an old universal list of conflicts. At this validation:
- Strands
1.56.0requiresmcp >=1.23 <2.2; the Caveman MCP extra requires>=2.2 <3. - CrewAI
1.15.21requiresmcp ~=1.28.1andopenai >=2.30 <3; those conflict with the MCP extra and the direct OpenAI adapter's accepted>=3.10 <4range. - Strands' optional
openaiprovider extra requires OpenAI<3; its optional LiteLLM provider extra caps LiteLLM at1.96.0, below the direct Caveman LiteLLM adapter's>=1.100guard. - Historical Agno/CrewAI LiteLLM conflicts depend on upstream versions and optional extras. The current base extras do not establish that blanket conflict. Resolve your exact provider extras and lockfile before combining them.
Use one virtual environment/container per incompatible family. Do not install every extra into one application or bypass the resolver. A service boundary can separate incompatible framework dependencies while each application still calls its own compatible runtime client.
Operation and transport support#
The TypeScript guide and Python guide specify native operations, sync/async boundaries, streaming, recovery ownership, and transport setup for every family. Adapter acceptance is narrower than a provider's entire API: unknown shapes, nontext blocks, unsupported providers, server-held history, signed payloads, or missing executors can bypass optimization.
Published Python LangChain/OpenAI async stream cancellation and receipt behavior has candidate fixes in the code workstream. Do not infer those fixes shipped because a local source test passed. Consume streams fully for the documented released baseline, and test cancellation under your exact versions before rollout.
Reproduce and upgrade#
Run the AI SDK or LangChain commands in a fresh directory. The framework guides provide an independent import reproduction command for each secondary module. Record node --version, npm ls, or python --version and python -m pip freeze with results.
For candidate code, code owners separately ran native-framework protocol-fixture tests and a packed Node ESM consumer/bundle check. Those used locally packed SDK/middleware, not published packages and not a live provider. They do not change the registry evidence above. See release policy before adopting unreleased APIs.