Clarify that modelName: 'provider/model-name' + apiKey is preferred format for v3 API

[pirate]

why

what changed

test plan

---

Summary by cubic

Clarifies the preferred v3 model config format: use model.modelName as 'provider/model-name' with optional model.apiKey or model.baseURL. OpenAPI shows only the recommended object format and deprecates the legacy top-level provider. Adds support for 'ollama' and 'deepseek' prefixes.

• Refactors

  • Added an OpenAPI override to ModelConfigSchema to keep runtime flexibility (string or object) while OpenAPI documents the object format only; removed provider from docs.
  • Switched Act, Extract, Observe, and Agent configs to the simplified ModelConfig; marked agent.provider as deprecated in OpenAPI.

• Migration

  • Use model.modelName with a provider prefix (openai, anthropic, google, microsoft, ollama, deepseek); prefix is required.
  • Optionally include model.apiKey; it overrides the x-model-api-key header.
  • Optionally include model.baseURL for custom provider endpoints (e.g., Bedrock or Azure OpenAI).
  • Avoid the top-level provider field; it’s deprecated but still accepted at runtime.

^{Written for commit 7c1934e. Summary will update on new commits.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 7c1934e

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[github-actions]

✱ Stainless preview builds

This PR will update the stagehand SDKs with the following commit message.

feat: Clarify that `modelName: 'provider/model-name' + apiKey` is preferred format for v3 API

Edit this comment to update it. It will appear in the SDK's changelogs.

❗ stagehand-ruby studio

Code was not generated because there was a fatal error.

New diagnostics (1 fatal)

❗ OpenAPISpecFatalError: Failed to parse OpenAPI spec

❗ stagehand-java studio

Code was not generated because there was a fatal error.

New diagnostics (1 fatal)

❗ OpenAPISpecFatalError: Failed to parse OpenAPI spec

❗ stagehand-typescript studio

Code was not generated because there was a fatal error.

New diagnostics (1 fatal)

❗ OpenAPISpecFatalError: Failed to parse OpenAPI spec

❗ stagehand-php studio

Code was not generated because there was a fatal error.

New diagnostics (1 fatal)

❗ OpenAPISpecFatalError: Failed to parse OpenAPI spec

❗ stagehand-go studio

Code was not generated because there was a fatal error.

New diagnostics (1 fatal)

❗ OpenAPISpecFatalError: Failed to parse OpenAPI spec

❗ stagehand-python studio

Code was not generated because there was a fatal error.

New diagnostics (1 fatal)

❗ OpenAPISpecFatalError: Failed to parse OpenAPI spec

❗ stagehand-kotlin studio

Code was not generated because there was a fatal error.

New diagnostics (1 fatal)

❗ OpenAPISpecFatalError: Failed to parse OpenAPI spec

❗ stagehand-csharp studio

Code was not generated because there was a fatal error.

New diagnostics (1 fatal)

❗ OpenAPISpecFatalError: Failed to parse OpenAPI spec

❗ stagehand-cli studio

Code was not generated because there was a fatal error.

New diagnostics (1 fatal)

❗ OpenAPISpecFatalError: Failed to parse OpenAPI spec

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
Last updated: 2026-01-13 01:44:14 UTC

[greptile-apps]

Greptile Summary

Introduces a documentation-only improvement to clarify the preferred model configuration format in the v3 API. The PR adds ModelConfigWithOverrideSchema that uses metadata overrides to show only the recommended object format { modelName: 'provider/model-name', apiKey: 'key' } in OpenAPI documentation, while runtime continues accepting both string and object formats for backward compatibility.

Key changes:

• Created ModelConfigWithOverrideSchema with OpenAPI override logic to simplify generated docs
• Replaced ModelConfigSchema with ModelConfigWithOverrideSchema in ActOptionsSchema, ExtractOptionsSchema, ObserveOptionsSchema, and AgentConfigSchema
• Marked legacy provider field as deprecated in AgentConfigSchema
• Updated generated OpenAPI YAML to reflect the recommended format across all endpoints
• Removed confusing ModelConfig union type from OpenAPI output (moved to end of file for backward compatibility)

Confidence Score: 5/5

• This PR is safe to merge with no risk - it's a documentation-only change that improves API clarity without affecting runtime behavior
• The changes only affect OpenAPI documentation generation through metadata overrides. Runtime type validation remains unchanged, preserving backward compatibility. The implementation correctly uses the override metadata field to modify generated schema without changing actual validation logic. All changes are consistent across TypeScript definitions and generated YAML.
• No files require special attention

Important Files Changed

Filename	Overview
packages/core/lib/v3/types/public/api.ts	Added ModelConfigWithOverrideSchema to display recommended object format in OpenAPI docs while preserving runtime flexibility for both string and object formats
packages/server/openapi.v3.yaml	Updated generated OpenAPI spec to show only the recommended object format for model config, marked legacy provider field as deprecated, and fixed formatting inconsistencies

Sequence Diagram

sequenceDiagram
    participant Dev as Developer
    participant API as Stagehand API
    participant Zod as Zod Validator
    participant Gen as OpenAPI Generator
    participant Docs as API Documentation

    Note over Dev,Docs: Configuration Flow

    Dev->>API: Pass model config (string or object)
    API->>Zod: Validate with ModelConfigWithOverrideSchema
    Zod->>Zod: Check union: ModelNameSchema OR ModelConfigObjectSchema
    Zod-->>API: ✓ Both formats accepted at runtime

    Note over Gen,Docs: Documentation Generation

    Gen->>Zod: Request OpenAPI schema
    Zod->>Zod: Apply metadata override()
    Zod->>Zod: Delete anyOf/oneOf/ref
    Zod->>Zod: Set type: object with modelName + apiKey
    Zod-->>Gen: Return simplified object schema
    Gen->>Docs: Generate YAML with recommended format only
    
    Note over Docs: Shows: { modelName: 'provider/model', apiKey: 'key' }
    Note over API: Accepts: 'provider/model' OR { modelName, apiKey, ... }

Loading

[cubic-dev-ai]

No issues found across 2 files

[cubic-dev-ai]

1 issue found across 3 files (changes from recent commits).

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="packages/server/openapi.v3.yaml">

<violation number="1" location="packages/server/openapi.v3.yaml:83">
P2: `match: {}` is not a valid OpenAPI 3.1/JSON Schema keyword. If pattern validation is intended, use `pattern` with a regex. If no validation is needed, this line can be removed entirely.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}