feat: add model_base_url parameter for custom LLM endpoints

[chrisreadsf]

Mirrors x-model-api-key pattern with x-model-base-url header, enabling OpenAI-compatible providers (e.g. ZhipuAI) via the chatcompletions/ prefix

sister PR for stagehand here: browserbase/stagehand#1804

[cubic-dev-ai]

1 issue found across 1 file

Confidence score: 3/5

• There is a concrete regression risk in src/stagehand/_client.py: copy() / with_options() on Stagehand and AsyncStagehand can silently drop an existing model_base_url, which can redirect or break downstream model calls.
• Given the reported severity (7/10) and high confidence (9/10), this is more than a cosmetic issue and could impact users who rely on client.with_options(...) to preserve connection settings.
• This looks fixable in a focused follow-up by accepting and forwarding model_base_url consistently in both sync and async client option-copy paths.
• Pay close attention to src/stagehand/_client.py - ensure model_base_url is preserved through copy()/with_options() in both Stagehand and AsyncStagehand.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/stagehand/_client.py">

<violation number="1" location="src/stagehand/_client.py:127">
P1: The `copy()` / `with_options()` methods in both `Stagehand` and `AsyncStagehand` do not accept or forward `model_base_url`, so calling `client.with_options(...)` silently drops a previously-set `model_base_url`. Add `model_base_url` to the `copy` signature and pass it through, mirroring the `model_api_key` pattern.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant User
    participant Env as OS Environment
    participant Client as Stagehand Client
    participant Server as Stagehand Server
    participant LLM as LLM Provider (Ollama/ZhipuAI)

    Note over User, Client: Client Initialization
    User->>Client: Stagehand(model_base_url=...)
    
    opt model_base_url is None
        Client->>Env: NEW: os.environ.get("MODEL_BASE_URL")
        Env-->>Client: model_base_url value
    end

    Note over User, LLM: Request Flow
    User->>Client: act() / extract() / observe()
    
    Client->>Client: CHANGED: Build auth_headers()
    Note right of Client: Includes x-model-api-key<br/>NEW: Includes x-model-base-url
    
    Client->>Server: HTTP Request (headers: x-model-base-url, ...)
    
    alt x-model-base-url present
        Server->>LLM: Forward Request to Custom Endpoint
    else Default behavior
        Server->>Server: Route to default OpenAI/Anthropic
    end
    
    LLM-->>Server: LLM Response
    Server-->>Client: Action Result
    Client-->>User: Result

Loading

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