#839
Issues/phaseo/Phaseo/#839

Support Vercel AI SDK 7 as the primary provider with V5/V6 compatibility

OpenDanielButler1opened 4mo ago

Context

Vercel AI SDK 7 is now the current major release line for the ai package. We should make AI SDK 7 the primary target for @ai-stats/ai-sdk-provider, while keeping users on AI SDK 5 and 6 on explicit compatibility paths.

Verified on 2026-06-25:

  • ai@latest is 7.0.0; upstream also publishes ai-v6 and ai-v5 dist-tags.
  • @ai-sdk/provider@latest is 4.0.0; AI SDK 6 uses provider spec v3 and AI SDK 5 uses provider spec v2.
  • @ai-sdk/provider-utils@latest is 5.0.0; AI SDK 6 uses 4.x and AI SDK 5 uses 3.x.
  • AI SDK 7 requires Node.js 22+ and is ESM-only.
  • AI SDK 7 keeps the v7 codemods, but there are provider-facing changes we need to handle ourselves.

Sources:

Current AI Stats State

packages/integrations/ai-sdk-ai-stats is currently a V6 provider package:

  • Package version: @ai-stats/ai-sdk-provider@1.0.1
  • Peer dependency: ai: ^6.0.0
  • Dependencies: @ai-sdk/provider: ^3.0.10, @ai-sdk/provider-utils: ^4.0.23
  • Source implements ProviderV3, LanguageModelV3, EmbeddingModelV3, ImageModelV3, SpeechModelV3, and TranscriptionModelV3.
  • Docs and dashboard snippets still point users at ai@^6 in several places.

Key files:

  • packages/integrations/ai-sdk-ai-stats/package.json
  • packages/integrations/ai-sdk-ai-stats/src/ai-stats-provider.ts
  • packages/integrations/ai-sdk-ai-stats/src/ai-stats-language-model.ts
  • apps/docs/v1/sdk-reference/sdk/ai-sdk.mdx
  • apps/web/src/app/(dashboard)/settings/sdk/page.tsx

Proposal

Make V7 the main/default package line and keep V6/V5 compatibility as deliberate, tested release lanes.

Recommended packaging setup:

  1. Ship the default @ai-stats/ai-sdk-provider package for AI SDK 7.

    • Peer dependency: ai: ^7.0.0
    • Dependency: @ai-sdk/provider: ^4.0.0
    • Dependency: @ai-sdk/provider-utils: ^5.0.0
    • Provider implementation: ProviderV4 / LanguageModelV4 / V4 model interfaces
    • Engine policy: validate whether this package must move to Node >=22 because upstream AI SDK 7 does.

  2. Preserve AI SDK 6 as a compatibility release line.

    • Keep current V3 provider implementation available as a maintained compatibility build.
    • Publish/retain an ai-v6 npm dist-tag for users who need ai@ai-v6.
    • Document install path, e.g. npm install @ai-stats/ai-sdk-provider@ai-v6 ai@ai-v6.

  3. Add AI SDK 5 compatibility explicitly.

    • Implement or backport a provider spec V2 adapter if we do not already have a working V5-compatible package.
    • Publish an ai-v5 npm dist-tag or a clearly named compatibility package if dist-tags are not enough for user clarity.
    • Document install path, e.g. npm install @ai-stats/ai-sdk-provider@ai-v5 ai@ai-v5.

  4. Avoid pretending one provider build supports all majors unless a spike proves it.

    • Provider specs are structurally different across V2/V3/V4.
    • A broad peer range like ai: ^5 || ^6 || ^7 is risky without matrix tests, because source types, stream parts, model interfaces, provider-utils, and runtime requirements differ.

V7 Implementation Plan

Provider Package

  • Update the main provider implementation to ProviderV4 and specificationVersion: 'v4'.
  • Convert language model implementation from LanguageModelV3 to LanguageModelV4.
  • Update embeddings, images, speech, transcription, and any newly supported model types to V4 interfaces.
  • Decide whether to implement V7 rerankingModel, files, and skills interfaces now or explicitly leave them unsupported.
  • Update provider metadata and warning types from shared V3 shapes to shared V4 shapes.
  • Update usage mapping to V4 shape:
    • inputTokens.total/noCache/cacheRead/cacheWrite
    • outputTokens.total/text/reasoning
    • preserve raw provider usage where available.
  • Update prompt conversion for V4 message/content parts:
    • file parts replace older image/media-specific parts.
    • reasoning and reasoning-file parts need safe handling.
    • tool result and approval response parts need explicit conversion behavior.
  • Update tool support for V4:
    • inputSchema remains the provider-facing tool schema field.
    • verify tool input/output handling for regular tools, provider-executed tools, dynamic tools, and tool approvals.
  • Update streaming to V4 stream parts:
    • include stream-start warnings.
    • support text-start, text-delta, text-end.
    • support tool-input-start, tool-input-delta, tool-input-end, and final tool-call parts.
    • return finish with V4 usage and finish reason.
    • emit raw chunks only when requested.
  • Check request/response body inclusion. AI SDK 7 excludes request/response bodies by default in higher-level APIs, so we should verify our provider result/debug metadata does not surprise users.
  • Ensure all imports are ESM-compatible and no CommonJS assumptions remain.

Compatibility Lines

  • Split the provider implementation into versioned adapters or maintain versioned release branches:
    • V7: provider spec V4, ai@^7, Node 22+.
    • V6: provider spec V3, ai@^6, current behavior preserved.
    • V5: provider spec V2, ai@^5, compatibility adapter or tagged release.
  • Add package release guidance for latest, ai-v6, and ai-v5 tags.
  • Add a compatibility support policy: which bug fixes are backported, for how long, and which features are V7-only.

Test Matrix

Add CI coverage for the provider package across AI SDK majors:

  • V7 latest:
    • ai@latest
    • @ai-sdk/provider@latest
    • @ai-sdk/provider-utils@latest
  • V6 compatibility:
    • ai@ai-v6
    • @ai-sdk/provider@ai-v6
    • @ai-sdk/provider-utils@ai-v6
  • V5 compatibility:
    • ai@ai-v5
    • @ai-sdk/provider@ai-v5
    • @ai-sdk/provider-utils@ai-v5

Each lane should test:

  • generateText
  • streamText
  • tool calling and streamed tool input
  • structured output / object output path for the relevant major
  • embeddings and batch embeddings
  • image generation
  • transcription and speech if supported in that major
  • error handling and provider metadata
  • usage mapping
  • docs examples compile against the intended major

Docs and Examples

  • Update docs to make AI SDK 7 the default install path.
  • Add compatibility tabs or sections for AI SDK 6 and AI SDK 5.
  • Update dashboard setup snippets to default to npm install @ai-stats/ai-sdk-provider ai or ai@^7.
  • Document Node.js 22+ for the V7 provider path.
  • Add migration notes for users moving from our current V6 package to the V7 package.
  • Update README examples to avoid deprecated AI SDK 6 names where applicable.

Release Work

  • Add a changeset for the V7 provider package release.
  • Decide if this is a major package release for @ai-stats/ai-sdk-provider.
  • Publish latest as the V7-compatible provider.
  • Preserve/publish ai-v6 and ai-v5 compatibility tags.
  • Add release notes describing default V7 support and compatibility install commands.

Acceptance Criteria

  • @ai-stats/ai-sdk-provider works with ai@7.x as the default documented path.
  • AI SDK 6 users have a tested, documented compatibility install path.
  • AI SDK 5 users have a tested, documented compatibility install path or a clearly scoped follow-up issue if V5 needs a separate adapter PR.
  • Provider package tests pass for V7, V6, and V5 lanes.
  • Docs, README, dashboard snippets, and release notes are updated.
  • No existing V6 users are silently pushed onto V7 without a documented migration path.

Activity

7
linear-code[bot]4mo ago

AI-201

opencode-agent[bot]4mo ago
Issue understanding This is a feature request to upgrade `@ai-stats/ai-sdk-provider` from supporting AI SDK 6 (provider spec V3) to making AI SDK 7 (provider spec V4) the default/main package line, while preserving V6 and V5 compatibility as explicit release lanes. The issue covers packaging, implementation changes (ProviderV4/LanguageModelV4, V4 stream parts, usage shapes, ESM-only), maintaining compatibility builds, CI matrix testing, and doc updates. Key files are in `packages/integrations/ai-sdk-ai-stats/`.

AI Agent Prompt (Copy/Paste)

Implement AI SDK 7 support for @ai-stats/ai-sdk-provider as the default package line, while preserving V6/V5 compatibility lanes.

Tasks:
1. Upgrade the main provider in packages/integrations/ai-sdk-ai-stats to ProviderV4 / LanguageModelV4 (spec V4) with peer dep ai: ^7.0.0, @ai-sdk/provider: ^4.0.0, @ai-sdk/provider-utils: ^5.0.0. Update all model interfaces (embeddings, images, speech, transcription). Check Node 22+ requirement.
2. Update streaming to V4 stream parts (stream-start, text-start/delta/end, tool-input-start/delta/end, tool-call, finish with V4 usage). Update prompt conversion for V4 message parts (file parts, reasoning, tool result, approval). Update usage mapping to V4 shape (inputTokens.total/noCache/cacheRead/cacheWrite, outputTokens.total/text/reasoning).
3. Decide and implement (or explicitly skip) rerankingModel, files, and skills V4 interfaces.
4. Ensure ESM-only compatibility — no CommonJS assumptions.
5. Create/retain V6 compatibility lane: current V3 provider as @ai-v6 dist-tag, package.json pointing to ai@^6 and provider-utils@^4.x.
6. Create V5 compatibility lane: V2 provider adapter or tagged release for ai@^5 / provider-utils@^3.x.
7. Add CI matrix tests for V7 (ai@latest), V6 (ai@ai-v6), V5 (ai@ai-v5) covering generateText, streamText, tool calling, structured output, embeddings, image gen, speech/transcription, error handling, usage mapping, docs examples.
8. Update docs (apps/docs/v1/sdk-reference/sdk/ai-sdk.mdx), dashboard snippets (apps/web/src/app/(dashboard)/settings/sdk/page.tsx), and README to default to V7 with compatibility tabs.
9. Add changeset (major bump for @ai-stats/ai-sdk-provider) and npm dist-tag release plan (latest=V7, ai-v6, ai-v5).

Inspect packages/integrations/ai-sdk-ai-stats thoroughly — read all source files, package.json, tests. Also check current dashboard snippet and docs files. Do not rely solely on issue text; verify current provider implementation against V7 migration guide at https://ai-sdk.dev/v7/docs/migration-guides/migration-guide-7-0 and the V4 provider spec.

opencode session  |  github run

admin assigned danielbutler12mo ago
admin added status/stalestatus/stalestatus/stalestatus/stale labels2mo ago