Add support for DeepSeek

[shrey150]

why

what changed

test plan

---

Summary by cubic

Adds Deepseek chat completion support and fixes provider routing. Improves JSON-only responses, schema validation, and standardizes executionModel typing.

• New Features

  • Implement Deepseek client and integrate into LLMProvider.
  • Add models: deepseek/deepseek-chat and deepseek/deepseek-reasoner.

• Bug Fixes

  • Route via modelToProviderMap before AISDK fallback.
  • Clarify JSON-only response instructions and safely parse content.
  • Use toJsonSchema for Zod v3/v4 compatibility.

^{Written for commit 460b19c. Summary will update automatically on new commits.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 460b19c

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

This PR includes changesets to release 3 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server	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

[cubic-dev-ai]

No issues found across 12 files

Architecture diagram

sequenceDiagram
    participant Agent as V3AgentHandler
    participant Provider as LLMProvider
    participant DSClient as DeepSeekAIClient
    participant Tools as Agent Tools (Act/Extract)
    participant API as DeepSeek API

    Note over Agent,API: Scenario: Agent execution using new DeepSeek integration

    %% Initialization & Routing Phase
    Agent->>Provider: getClient("deepseek/deepseek-chat")
    
    Note right of Provider: CHANGED: Routing Fix<br/>Checks explicit map before generic "/" fallback
    
    alt Model in modelToProviderMap (NEW)
        Provider->>DSClient: NEW: Instantiate DeepSeekAIClient
        DSClient-->>Provider: Client Instance
    else Generic Model (e.g. custom/other)
        Provider->>Provider: Use generic AI SDK fallback
    end
    
    Provider-->>Agent: Return LLMClient

    %% Execution Phase
    loop Agent Step
        Agent->>Tools: Initialize Tool (e.g., act, extract)
        Note right of Agent: CHANGED: executionModel passed as<br/>ModelConfiguration object (was string)
        
        Agent->>DSClient: createChatCompletion(messages, schema)
        
        opt Schema Validation (NEW)
            DSClient->>DSClient: Convert Zod to JSON Schema
            Note right of DSClient: Ensures compatibility with<br/>DeepSeek JSON mode
        end

        DSClient->>API: POST /chat/completions
        API-->>DSClient: 200 OK (JSON string)

        DSClient->>DSClient: NEW: Safe JSON Parse & Validation
        
        DSClient-->>Agent: Structured Response
    end

Loading

[greptile-apps]

Greptile Summary

This PR adds DeepSeek chat completion support by implementing DeepSeekAIClient and integrating it into the LLM provider system. The implementation also standardizes executionModel typing across agent tools from string to ModelConfiguration.

Key Changes:

• Implemented DeepSeekAIClient following the OpenAI client pattern with support for JSON mode responses
• Fixed provider routing in LLMProvider.getClient() to check modelToProviderMap before falling back to AI SDK
• Added deepseek/deepseek-chat and deepseek/deepseek-reasoner models to type definitions
• Standardized executionModel parameter type from string to ModelConfiguration across all agent tools and handlers
• Improved JSON schema instructions for response models using toJsonSchema() helper for Zod v3/v4 compatibility

Issues Found:

• Missing error handling for JSON.parse() at DeepSeekAIClient:274 - could throw unhandled exception if API returns malformed JSON

Confidence Score: 4/5

• This PR is safe to merge with one minor fix needed for error handling.
• The implementation follows established patterns from other LLM clients and the type system improvements are sound. However, there's one logical error where JSON.parse is called without error handling, which could cause runtime crashes if DeepSeek returns malformed JSON. This is critical enough to fix before merging since it affects production stability.
• Fix error handling in packages/core/lib/v3/llm/DeepSeekAIClient.ts at line 274 before merging

Important Files Changed

Filename	Overview
packages/core/lib/v3/llm/DeepSeekAIClient.ts	New DeepSeek client implementation following OpenAI pattern. Missing error handling for JSON.parse at line 274.
packages/core/lib/v3/llm/LLMProvider.ts	Correctly integrates DeepSeek provider with proper routing logic via modelToProviderMap before falling back to AISDK.
packages/core/lib/v3/types/public/model.ts	Added DeepSeek models to type definitions and ModelConfiguration type for better type safety.
packages/core/lib/v3/agent/tools/index.ts	Updated interface to accept ModelConfiguration instead of string for executionModel.
packages/core/lib/v3/v3.ts	Simplified executionModel passing to handler by directly passing the ModelConfiguration object.

Sequence Diagram

sequenceDiagram
    participant User
    participant V3
    participant LLMProvider
    participant DeepSeekAIClient
    participant OpenAI SDK
    participant DeepSeek API
    participant AISDK

    User->>V3: agent({ model: "deepseek/deepseek-chat" })
    V3->>LLMProvider: getClient("deepseek/deepseek-chat")
    
    Note over LLMProvider: Check modelToProviderMap
    LLMProvider->>LLMProvider: Find provider = "deepseek"
    
    LLMProvider->>DeepSeekAIClient: new DeepSeekAIClient()
    DeepSeekAIClient->>OpenAI SDK: new OpenAI({ baseURL: "https://api.deepseek.com/v1" })
    LLMProvider-->>V3: Return DeepSeekAIClient
    
    V3->>DeepSeekAIClient: createChatCompletion()
    
    alt With response_model (JSON mode)
        DeepSeekAIClient->>DeepSeekAIClient: Add JSON schema instructions
        DeepSeekAIClient->>DeepSeekAIClient: Set response_format: { type: "json_object" }
    end
    
    DeepSeekAIClient->>OpenAI SDK: chat.completions.create()
    OpenAI SDK->>DeepSeek API: POST /v1/chat/completions
    DeepSeek API-->>OpenAI SDK: Response
    OpenAI SDK-->>DeepSeekAIClient: Response
    
    alt With response_model
        DeepSeekAIClient->>DeepSeekAIClient: JSON.parse(content)
        DeepSeekAIClient->>DeepSeekAIClient: validateZodSchema()
        alt Validation fails
            DeepSeekAIClient->>DeepSeekAIClient: Retry with retries-1
        end
    end
    
    DeepSeekAIClient-->>V3: Return response
    V3-->>User: Agent execution result
    
    Note over V3,AISDK: For AI SDK integration (e.g., streamText)
    User->>V3: Use AI SDK methods
    V3->>DeepSeekAIClient: getLanguageModel()
    DeepSeekAIClient->>AISDK: createDeepSeek({ apiKey })
    AISDK-->>DeepSeekAIClient: DeepSeek provider
    DeepSeekAIClient-->>V3: LanguageModelV2

Loading

[greptile-apps]

_{10 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

logic: JSON.parse can throw an error if the response is malformed. Wrap in try-catch to handle gracefully (see GoogleClient:364-373 for reference pattern)

Suggested change

	const parsedData = JSON.parse(extractedData);
	let parsedData;
	try {
	parsedData = JSON.parse(extractedData);
	} catch (e) {
	logger({
	category: "deepseek",
	message: `Failed to parse JSON response: ${e.message}`,
	level: 0,
	});
	if (retries > 0) {
	return this.createChatCompletion({
	options: options as ChatCompletionOptions,
	logger,
	retries: retries - 1,
	});
	}
	throw new CreateChatCompletionResponseError("Failed to parse JSON response");
	}

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/core/lib/v3/llm/DeepSeekAIClient.ts
Line: 274:274

Comment:
**logic:** `JSON.parse` can throw an error if the response is malformed. Wrap in try-catch to handle gracefully (see GoogleClient:364-373 for reference pattern)

```suggestion
      let parsedData;
      try {
        parsedData = JSON.parse(extractedData);
      } catch (e) {
        logger({
          category: "deepseek",
          message: `Failed to parse JSON response: ${e.message}`,
          level: 0,
        });
        if (retries > 0) {
          return this.createChatCompletion({
            options: options as ChatCompletionOptions,
            logger,
            retries: retries - 1,
          });
        }
        throw new CreateChatCompletionResponseError("Failed to parse JSON response");
      }
```

How can I resolve this? If you propose a fix, please make it concise.