⚠️ No Changeset found

Latest commit: 5657c1e

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.

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

✱ Stainless preview builds

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

feat: Using provider/model syntax in modelName examples within openapi spec

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

Greptile Overview

Greptile Summary

This PR corrects documentation examples in the Zod schemas and OpenAPI specification to use the provider/model syntax (e.g., "openai/gpt-4o") instead of model-only syntax (e.g., "gpt-4o").

What Changed

The PR updates examples in three locations:

1. ModelConfigObjectSchema.modelName - Changed from "gpt-5-nano" (without prefix) to "openai/gpt-5-nano" (with prefix)
2. SessionStartRequestSchema.modelName - Changed from "gpt-4o" to "openai/gpt-4o"
3. OpenAPI YAML - Updated corresponding examples in both component schemas and the inline /v1/sessions/start endpoint schema

Why This Matters

The old examples showed "gpt-4o" which incorrectly suggested users should pass model names without the provider prefix. However:

• The ModelNameSchema has a regex validation requiring the format: /^(openai|anthropic|google|microsoft)\/.+$/
• The codebase examples (e.g., packages/core/examples/) consistently use the provider/model format
• The LLMProvider.getClient() method checks if modelName.includes("/") to determine whether to use AI SDK or legacy model lookup

The system does support both formats for backward compatibility, but the documentation should show the recommended provider/model syntax.

Review Findings

✅ No issues found. The changes are:

• Consistent: All four locations in the YAML match the TypeScript schema changes
• Correct: The examples now align with actual API usage patterns
• Safe: This is purely a documentation change that doesn't affect runtime behavior
• Complete: Both files that needed updates were modified

Confidence Score: 5/5

• This PR is safe to merge with no risk
• This is a documentation-only change that corrects misleading examples in OpenAPI/Zod schemas. No runtime code or validation logic was modified. The changes are internally consistent across both files and align with actual API usage patterns observed in the codebase.
• No files require special attention

Important Files Changed

File Analysis

Sequence Diagram

sequenceDiagram
    participant Client
    participant API as SessionStart API
    participant Schema as Zod Schema
    participant Resolver as resolveModel()
    participant Provider as LLMProvider
    participant AISDK as AI SDK
    
    Client->>API: POST /v1/sessions/start
    Note over Client,API: modelName: "openai/gpt-4o"
    
    API->>Schema: Validate with SessionStartRequestSchema
    Schema->>Schema: Check modelName example
    Note over Schema: Example now shows<br/>"openai/gpt-4o"<br/>(was "gpt-4o")
    
    Schema->>Resolver: Pass validated modelName
    
    alt modelName includes "/"
        Resolver->>Resolver: Split on "/"
        Note over Resolver: provider = "openai"<br/>modelName = "gpt-4o"
        Resolver->>Provider: getClient("openai/gpt-4o")
        Provider->>Provider: Split on "/"
        Provider->>AISDK: Use AI SDK with openai("gpt-4o")
    else modelName without "/"
        Resolver->>Provider: getClient("gpt-4o")
        Provider->>Provider: Lookup in modelToProviderMap
        Note over Provider: Legacy format:<br/>uses predefined provider
    end
    
    AISDK->>Client: Return session with configured model