feat(core): add NEAR AI model provider

[PierreLeGuen]

PR Checklist

• The commit message follows the contribution guidelines
• Related issue(s) linked
• Tests for the changes have been added
• Docs have been added / updated
• Changesets have been added

What is the current behavior?

NEAR AI Cloud is not included in VoltAgent's bundled model router registry, so users need to configure it manually as an OpenAI-compatible provider.

What is the new behavior?

Adds nearai as an OpenAI-compatible model router provider with NEARAI_API_KEY and the default base URL https://cloud-api.near.ai/v1. The change also adds NEAR model and embedding type entries, provider docs, and a focused registry test.

For the NEAR route, the OpenAI-compatible request body is adjusted to avoid unsupported strict/advanced fields while keeping the existing adapter path.

Notes for reviewers

The model list follows the current nearai entry from the models.dev registry source used by VoltAgent's bundled provider snapshot. I did not run a live NEAR request locally.

Testing:

• pnpm --filter @voltagent/internal build
• pnpm --filter @voltagent/core exec vitest run src/registries/model-provider-registry-nearai.spec.ts src/registries/model-provider-registry-minimax.spec.ts
• pnpm --filter @voltagent/core typecheck
• pnpm biome check packages/core/src/registries/model-provider-registry.ts packages/core/src/registries/model-provider-registry-nearai.spec.ts packages/core/src/registries/model-provider-registry.generated.ts packages/core/src/registries/model-provider-types.generated.ts packages/core/src/registries/embedding-model-router-types.generated.ts
• pnpm exec prettier --check website/models-docs/providers/nearai.md website/models-docs/providers/overview.md website/models-docs/overview.md website/docs/getting-started/providers-models.md .changeset/nearai-provider.md

Summary by CodeRabbit

• New Features

  • Added NEAR AI Cloud provider (OpenAI‑compatible) with support for numerous model families (Qwen, Anthropic, FLUX.2, Gemini, OpenAI, Whisper, GLM). Use nearai/ routing.

• Configuration

  • Introduced NEARAI_API_KEY for authentication and optional NEARAI_BASE_URL to override the default API endpoint.

• Documentation

  • Added NEAR AI Cloud provider docs and updated providers/models overview and counts.

[changeset-bot]

🦋 Changeset detected

Latest commit: 9ddf824

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@voltagent/core	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 65a36d47-6c59-4e6d-a444-1e96157d2de3

📥 Commits

Reviewing files that changed from the base of the PR and between 13c0f9c and 9ddf824.

📒 Files selected for processing (1)

• packages/core/src/registries/model-provider-registry-nearai.spec.ts

---

📝 Walkthrough

Walkthrough

Adds NEAR AI Cloud (nearai) as a new OpenAI-compatible model provider: updates provider/type registries, implements NearAI-specific request sanitization and adapter configuration, adds Vitest coverage for registration/config/transform/error cases, and publishes user documentation and a changeset.

Changes

NEAR AI Cloud Provider Integration

Layer / File(s)	Summary
Provider types and registry metadata packages/core/src/registries/model-provider-types.generated.ts, packages/core/src/registries/embedding-model-router-types.generated.ts, packages/core/src/registries/model-provider-registry.generated.ts, .changeset/nearai-provider.md	Extends provider and embedding maps with nearai, adds nearai entry to MODEL_PROVIDER_REGISTRY, and records the change in a changeset.
Request sanitization and adapter integration packages/core/src/registries/model-provider-registry.ts	Adds sanitizeNearAIRequestBody to remove reasoning_effort/store, normalize developer→system, strip strict from tool functions and response_format.json_schema; applies transform and disables structured outputs for nearai in the OpenAI-compatible adapter.
Test suite for NEAR AI Cloud provider packages/core/src/registries/model-provider-registry-nearai.spec.ts	Vitest suite mocking @ai-sdk/openai-compatible, verifying registry includes nearai, adapter init/config (including NEARAI_BASE_URL override), transform behavior, and error when NEARAI_API_KEY is missing.
User-facing documentation website/models-docs/providers/nearai.md, website/models-docs/providers/overview.md, website/docs/getting-started/providers-models.md, website/models-docs/overview.md	Adds nearai provider page (quick start, env var, base URL override, models list), updates providers table and getting-started env var examples, and updates models counts.

Sequence Diagram — model resolution and request flow:

sequenceDiagram
  participant Caller
  participant Registry as ModelProviderRegistry
  participant Adapter as OpenAICompatibleAdapter
  participant NearAI as NEAR_AI_Cloud
  Caller->>Registry: request resolveLanguageModel("nearai/<model>")
  Registry->>Adapter: createOpenAICompatible(config with NEARAI_API_KEY, NEARAI_BASE_URL?)
  Adapter->>Adapter: apply transformRequestBody(sanitizeNearAIRequestBody)
  Caller->>Adapter: send inference request (messages, tools, response_format)
  Adapter->>Adapter: transformRequestBody -> sanitizedRequest
  Adapter->>NearAI: HTTP call with sanitizedRequest
  NearAI-->>Adapter: response
  Adapter-->>Caller: normalized response

Loading

🎯 3 (Moderate) | ⏱️ ~25 minutes

🐰 A new cloud from NEAR arrives,
With models aplenty, the spirit revives!
Request fields scrubbed, roles normalized bright,
VoltAgent adapts to the OpenAI light. 🚀

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding NEAR AI as a model provider to the core package.
Description check	✅ Passed	The description comprehensively covers current/new behavior, includes testing details, and notes that tests and docs were added; however, the related issues checkbox remains unchecked.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/core/src/registries/model-provider-registry-nearai.spec.ts`:
- Around line 5-7: The current vi.mock of "`@voltagent/internal`" replaces
safeStringify with plain JSON.stringify which breaks expected safeStringify
behavior; update the mock inside the vi.mock call to provide a safeStringify
implementation that matches the real utility (handles circular references and
non-JSON values) — e.g., implement a serializer that tracks a seen Set to avoid
circular recursion and returns stable string representations for
functions/undefined/BigInt instead of throwing, or import and re-export the real
safeStringify implementation if available; ensure the mock exports the symbol
safeStringify used by the tests (the vi.mock call and the safeStringify symbol).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: da327098-4811-42e4-86fd-d41bce80963c

📥 Commits

Reviewing files that changed from the base of the PR and between 08414ed and 13c0f9c.

📒 Files selected for processing (10)

• .changeset/nearai-provider.md
• packages/core/src/registries/embedding-model-router-types.generated.ts
• packages/core/src/registries/model-provider-registry-nearai.spec.ts
• packages/core/src/registries/model-provider-registry.generated.ts
• packages/core/src/registries/model-provider-registry.ts
• packages/core/src/registries/model-provider-types.generated.ts
• website/docs/getting-started/providers-models.md
• website/models-docs/overview.md
• website/models-docs/providers/nearai.md
• website/models-docs/providers/overview.md

[cubic-dev-ai]

No issues found across 10 files

_{Re-trigger cubic}