@robota-sdk/agent-provider 3.0.0-beta.64

package/src/deepseek/model-catalog.ts

@@ -0,0 +1,55 @@
+import type { IProviderModelCatalogEntry } from '@robota-sdk/agent-core';
+import { DEFAULT_DEEPSEEK_PROVIDER_MODEL } from './defaults';
+
+export const DEEPSEEK_MODEL_CATALOG_SOURCE_URL =
+  'https://api-docs.deepseek.com/quick_start/pricing';
+export const DEEPSEEK_MODEL_LIST_SOURCE_URL = 'https://api-docs.deepseek.com/api/list-models';
+export const DEEPSEEK_MODEL_LAST_VERIFIED_AT = '2026-05-07';
+export const DEEPSEEK_DEPRECATED_ALIAS_RETIREMENT_DATE = '2026-07-24';
+
+export const DEEPSEEK_MODEL_CATALOG_ENTRIES: readonly IProviderModelCatalogEntry[] = [
+  {
+    id: DEFAULT_DEEPSEEK_PROVIDER_MODEL,
+    displayName: 'DeepSeek V4 Flash',
+    contextWindow: 1_000_000,
+    capabilities: ['tools', 'reasoning', 'json_schema', 'streaming'],
+    lifecycle: 'active',
+    sourceUrl: DEEPSEEK_MODEL_CATALOG_SOURCE_URL,
+    lastVerifiedAt: DEEPSEEK_MODEL_LAST_VERIFIED_AT,
+  },
+  {
+    id: 'deepseek-v4-pro',
+    displayName: 'DeepSeek V4 Pro',
+    contextWindow: 1_000_000,
+    capabilities: ['tools', 'reasoning', 'json_schema', 'streaming'],
+    lifecycle: 'active',
+    sourceUrl: DEEPSEEK_MODEL_CATALOG_SOURCE_URL,
+    lastVerifiedAt: DEEPSEEK_MODEL_LAST_VERIFIED_AT,
+  },
+  {
+    id: 'deepseek-chat',
+    displayName: `DeepSeek Chat compatibility alias, deprecated ${DEEPSEEK_DEPRECATED_ALIAS_RETIREMENT_DATE}`,
+    aliases: [DEFAULT_DEEPSEEK_PROVIDER_MODEL],
+    contextWindow: 1_000_000,
+    capabilities: ['tools', 'json_schema', 'streaming'],
+    lifecycle: 'deprecated',
+    sourceUrl: DEEPSEEK_MODEL_CATALOG_SOURCE_URL,
+    lastVerifiedAt: DEEPSEEK_MODEL_LAST_VERIFIED_AT,
+  },
+  {
+    id: 'deepseek-reasoner',
+    displayName: `DeepSeek Reasoner compatibility alias, deprecated ${DEEPSEEK_DEPRECATED_ALIAS_RETIREMENT_DATE}`,
+    aliases: [DEFAULT_DEEPSEEK_PROVIDER_MODEL],
+    contextWindow: 1_000_000,
+    capabilities: ['reasoning', 'json_schema', 'streaming'],
+    lifecycle: 'deprecated',
+    sourceUrl: DEEPSEEK_MODEL_CATALOG_SOURCE_URL,
+    lastVerifiedAt: DEEPSEEK_MODEL_LAST_VERIFIED_AT,
+  },
+];
+
+export function getDeepSeekFallbackModelCatalogEntry(
+  id: string,
+): IProviderModelCatalogEntry | undefined {
+  return DEEPSEEK_MODEL_CATALOG_ENTRIES.find((entry) => entry.id === id);
+}

package/src/deepseek/provider-definition.test.ts

@@ -0,0 +1,109 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  createDeepSeekProviderDefinition,
+  DeepSeekProvider,
+  DEFAULT_DEEPSEEK_PROVIDER_API_KEY_ENV,
+  DEFAULT_DEEPSEEK_PROVIDER_API_KEY_REFERENCE,
+  DEFAULT_DEEPSEEK_PROVIDER_BASE_URL,
+  DEFAULT_DEEPSEEK_PROVIDER_MODEL,
+} from './index';
+
+vi.mock('openai', () => {
+  const MockOpenAI = vi.fn().mockImplementation(() => ({
+    chat: {
+      completions: {
+        create: vi.fn(),
+      },
+    },
+  }));
+  return { default: MockOpenAI };
+});
+
+describe('createDeepSeekProviderDefinition', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('exposes DeepSeek defaults, setup steps, and model catalog metadata', () => {
+    const definition = createDeepSeekProviderDefinition();
+
+    expect(definition.type).toBe('deepseek');
+    expect(definition.requiresApiKey).toBe(true);
+    expect(definition.probeProfile).toBeTypeOf('function');
+    expect(definition.refreshModelCatalog).toBeTypeOf('function');
+    expect(definition.defaults).toEqual({
+      model: DEFAULT_DEEPSEEK_PROVIDER_MODEL,
+      apiKey: DEFAULT_DEEPSEEK_PROVIDER_API_KEY_REFERENCE,
+      baseURL: DEFAULT_DEEPSEEK_PROVIDER_BASE_URL,
+    });
+    expect(definition.setupHelpLinks).toEqual([
+      {
+        kind: 'api-key',
+        label: 'DeepSeek API keys',
+        url: 'https://platform.deepseek.com/api_keys',
+        sourceUrl: 'https://api-docs.deepseek.com/',
+        lastVerifiedAt: '2026-05-08',
+      },
+    ]);
+    expect(DEFAULT_DEEPSEEK_PROVIDER_API_KEY_ENV).toBe('DEEPSEEK_API_KEY');
+    expect(definition.setupSteps).toEqual([
+      {
+        key: 'baseURL',
+        title: 'DeepSeek OpenAI-compatible base URL',
+        defaultValue: DEFAULT_DEEPSEEK_PROVIDER_BASE_URL,
+      },
+      {
+        key: 'model',
+        title: 'DeepSeek model',
+        defaultValue: DEFAULT_DEEPSEEK_PROVIDER_MODEL,
+      },
+      {
+        key: 'apiKey',
+        title: 'DeepSeek API key',
+        defaultValue: DEFAULT_DEEPSEEK_PROVIDER_API_KEY_REFERENCE,
+        masked: true,
+      },
+    ]);
+    expect(definition.modelCatalog?.entries?.map((entry) => entry.id)).toEqual([
+      'deepseek-v4-flash',
+      'deepseek-v4-pro',
+      'deepseek-chat',
+      'deepseek-reasoner',
+    ]);
+    expect(definition.modelCatalog?.entries?.[2]).toMatchObject({
+      id: 'deepseek-chat',
+      lifecycle: 'deprecated',
+      aliases: ['deepseek-v4-flash'],
+    });
+  });
+
+  it('creates a DeepSeekProvider from a resolved provider profile', () => {
+    const definition = createDeepSeekProviderDefinition();
+
+    const provider = definition.createProvider({
+      name: 'deepseek',
+      model: 'deepseek-v4-pro',
+      apiKey: 'deepseek-key',
+      baseURL: 'https://api.deepseek.com',
+      timeout: 12_000,
+      options: {
+        thinking: { type: 'enabled' },
+        reasoningEffort: 'max',
+      },
+    });
+
+    expect(provider).toBeInstanceOf(DeepSeekProvider);
+    expect(provider.name).toBe('deepseek');
+  });
+
+  it('rejects provider creation without an API key', () => {
+    const definition = createDeepSeekProviderDefinition();
+
+    expect(() =>
+      definition.createProvider({
+        name: 'deepseek',
+        model: 'deepseek-v4-flash',
+      }),
+    ).toThrow('Provider deepseek requires apiKey');
+  });
+});

package/src/deepseek/provider-definition.ts

@@ -0,0 +1,132 @@
+import type { IProviderDefinition, TUniversalValue } from '@robota-sdk/agent-core';
+import { probeOpenAICompatibleProfile } from '../shared/openai-compatible/index.js';
+import {
+  DEFAULT_DEEPSEEK_PROVIDER_API_KEY_REFERENCE,
+  DEFAULT_DEEPSEEK_PROVIDER_BASE_URL,
+  DEFAULT_DEEPSEEK_PROVIDER_MODEL,
+} from './defaults';
+import {
+  DEEPSEEK_MODEL_CATALOG_ENTRIES,
+  DEEPSEEK_MODEL_CATALOG_SOURCE_URL,
+  DEEPSEEK_MODEL_LAST_VERIFIED_AT,
+} from './model-catalog';
+import { refreshDeepSeekModelCatalog } from './model-catalog-refresh';
+import { DeepSeekProvider } from './provider';
+import type { TDeepSeekReasoningEffort, TDeepSeekThinkingMode } from './types';
+
+const DEEPSEEK_MODEL_CATALOG: NonNullable<IProviderDefinition['modelCatalog']> = {
+  status: 'fallback',
+  sourceUrl: DEEPSEEK_MODEL_CATALOG_SOURCE_URL,
+  lastVerifiedAt: DEEPSEEK_MODEL_LAST_VERIFIED_AT,
+  entries: DEEPSEEK_MODEL_CATALOG_ENTRIES,
+};
+const DEEPSEEK_API_KEY_URL = 'https://platform.deepseek.com/api_keys';
+const DEEPSEEK_SETUP_SOURCE_URL = 'https://api-docs.deepseek.com/';
+const DEEPSEEK_SETUP_LAST_VERIFIED_AT = '2026-05-08';
+const DEEPSEEK_SETUP_HELP_LINKS: NonNullable<IProviderDefinition['setupHelpLinks']> = [
+  {
+    kind: 'api-key',
+    label: 'DeepSeek API keys',
+    url: DEEPSEEK_API_KEY_URL,
+    sourceUrl: DEEPSEEK_SETUP_SOURCE_URL,
+    lastVerifiedAt: DEEPSEEK_SETUP_LAST_VERIFIED_AT,
+  },
+];
+
+export function createDeepSeekProviderDefinition(): IProviderDefinition {
+  return {
+    type: 'deepseek',
+    displayName: 'DeepSeek',
+    description: 'DeepSeek OpenAI-compatible endpoint',
+    defaults: {
+      model: DEFAULT_DEEPSEEK_PROVIDER_MODEL,
+      apiKey: DEFAULT_DEEPSEEK_PROVIDER_API_KEY_REFERENCE,
+      baseURL: DEFAULT_DEEPSEEK_PROVIDER_BASE_URL,
+    },
+    modelCatalog: DEEPSEEK_MODEL_CATALOG,
+    setupHelpLinks: DEEPSEEK_SETUP_HELP_LINKS,
+    setupSteps: [
+      {
+        key: 'baseURL',
+        title: 'DeepSeek OpenAI-compatible base URL',
+        defaultValue: DEFAULT_DEEPSEEK_PROVIDER_BASE_URL,
+      },
+      {
+        key: 'model',
+        title: 'DeepSeek model',
+        defaultValue: DEFAULT_DEEPSEEK_PROVIDER_MODEL,
+      },
+      {
+        key: 'apiKey',
+        title: 'DeepSeek API key',
+        defaultValue: DEFAULT_DEEPSEEK_PROVIDER_API_KEY_REFERENCE,
+        masked: true,
+      },
+    ],
+    requiresApiKey: true,
+    probeProfile: probeOpenAICompatibleProfile,
+    refreshModelCatalog: ({ profile }) => refreshDeepSeekModelCatalog(profile),
+    modelCatalogCacheTtlSeconds: 86400,
+    createProvider: (config) => {
+      const options = parseDeepSeekProviderOptions(config.options);
+      return new DeepSeekProvider({
+        apiKey: requireApiKey(config.apiKey),
+        ...(config.baseURL !== undefined && { baseURL: config.baseURL }),
+        ...(config.timeout !== undefined && { timeout: config.timeout }),
+        ...(options.thinking !== undefined && { thinking: options.thinking }),
+        ...(options.reasoningEffort !== undefined && { reasoningEffort: options.reasoningEffort }),
+        defaultModel: config.model,
+      });
+    },
+  };
+}
+
+function requireApiKey(apiKey: string | undefined): string {
+  if (!apiKey) {
+    throw new Error('Provider deepseek requires apiKey');
+  }
+  return apiKey;
+}
+
+function parseDeepSeekProviderOptions(options: Record<string, TUniversalValue> | undefined): {
+  thinking?: TDeepSeekThinkingMode;
+  reasoningEffort?: TDeepSeekReasoningEffort;
+} {
+  const thinking = parseThinkingMode(options?.['thinking']);
+  const reasoningEffort = parseReasoningEffort(options?.['reasoningEffort']);
+  return {
+    ...(thinking !== undefined && { thinking }),
+    ...(reasoningEffort !== undefined && { reasoningEffort }),
+  };
+}
+
+function parseThinkingMode(value: TUniversalValue | undefined): TDeepSeekThinkingMode | undefined {
+  if (value === true) return 'enabled';
+  if (value === false) return 'disabled';
+  if (value === 'enabled' || value === 'disabled') return value;
+  const record = asRecord(value);
+  const type = record?.['type'];
+  return type === 'enabled' || type === 'disabled' ? type : undefined;
+}
+
+function parseReasoningEffort(
+  value: TUniversalValue | undefined,
+): TDeepSeekReasoningEffort | undefined {
+  if (
+    value === 'low' ||
+    value === 'medium' ||
+    value === 'high' ||
+    value === 'xhigh' ||
+    value === 'max'
+  ) {
+    return value;
+  }
+  return undefined;
+}
+
+function asRecord(value: TUniversalValue | undefined): Record<string, TUniversalValue> | undefined {
+  if (value === null || value === undefined || value instanceof Date || Array.isArray(value)) {
+    return undefined;
+  }
+  return typeof value === 'object' ? value : undefined;
+}

package/src/deepseek/provider.test.ts

@@ -0,0 +1,324 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type OpenAI from 'openai';
+import type {
+  IProviderNativeRawPayloadEvent,
+  IToolSchema,
+  TUniversalMessage,
+} from '@robota-sdk/agent-core';
+import { DEFAULT_DEEPSEEK_PROVIDER_BASE_URL, DeepSeekProvider } from './index';
+
+vi.mock('openai', () => {
+  const MockOpenAI = vi.fn().mockImplementation(() => ({
+    chat: {
+      completions: {
+        create: vi.fn(),
+      },
+    },
+  }));
+  return { default: MockOpenAI };
+});
+
+const timestamp = new Date('2026-05-01T00:00:00.000Z');
+
+interface IOpenAIClientMock {
+  chat: {
+    completions: {
+      create: ReturnType<typeof vi.fn>;
+    };
+  };
+}
+
+function getClient(provider: DeepSeekProvider): IOpenAIClientMock {
+  return (provider as unknown as { client: IOpenAIClientMock }).client;
+}
+
+function createUserMessage(content: string): TUniversalMessage {
+  return {
+    id: 'user-1',
+    role: 'user',
+    content,
+    state: 'complete',
+    timestamp,
+  };
+}
+
+function createToolSchema(): IToolSchema {
+  return {
+    name: 'inspect_file',
+    description: 'Inspect a file',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: { type: 'string' },
+      },
+      required: ['path'],
+    },
+  };
+}
+
+async function* asyncIterableFrom<T>(items: T[]): AsyncIterable<T> {
+  for (const item of items) {
+    yield item;
+  }
+}
+
+function createChunk(
+  content: string,
+  finishReason: OpenAI.Chat.ChatCompletionChunk.Choice['finish_reason'] = null,
+): OpenAI.Chat.ChatCompletionChunk {
+  return {
+    id: 'chunk-1',
+    object: 'chat.completion.chunk',
+    created: 1,
+    model: 'deepseek-v4-flash',
+    choices: [
+      {
+        index: 0,
+        delta: { content },
+        finish_reason: finishReason,
+        logprobs: null,
+      },
+    ],
+  };
+}
+
+describe('DeepSeekProvider', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('creates an OpenAI-compatible client with DeepSeek endpoint options', async () => {
+    const OpenAIModule = await import('openai');
+    const OpenAIConstructor = vi.mocked(OpenAIModule.default);
+
+    const provider = new DeepSeekProvider({
+      apiKey: 'deepseek-key',
+      baseURL: 'https://api.deepseek.com',
+      timeout: 1000,
+    });
+
+    expect(provider.name).toBe('deepseek');
+    expect(OpenAIConstructor).toHaveBeenCalledWith({
+      apiKey: 'deepseek-key',
+      baseURL: 'https://api.deepseek.com',
+      timeout: 1000,
+    });
+  });
+
+  it('uses the documented DeepSeek OpenAI-compatible base URL by default', async () => {
+    const OpenAIModule = await import('openai');
+    const OpenAIConstructor = vi.mocked(OpenAIModule.default);
+
+    new DeepSeekProvider({
+      apiKey: 'deepseek-key',
+    });
+
+    expect(OpenAIConstructor).toHaveBeenCalledWith({
+      apiKey: 'deepseek-key',
+      baseURL: DEFAULT_DEEPSEEK_PROVIDER_BASE_URL,
+    });
+  });
+
+  it('sends OpenAI-compatible messages, tools, and DeepSeek thinking controls', async () => {
+    const provider = new DeepSeekProvider({
+      apiKey: 'deepseek-key',
+      thinking: 'enabled',
+      reasoningEffort: 'high',
+    });
+    const client = getClient(provider);
+    client.chat.completions.create.mockResolvedValue({
+      id: 'chatcmpl-test',
+      object: 'chat.completion',
+      created: 1,
+      model: 'deepseek-v4-pro',
+      choices: [
+        {
+          index: 0,
+          message: {
+            role: 'assistant',
+            content: '',
+            refusal: null,
+            tool_calls: [
+              {
+                id: 'call_1',
+                type: 'function',
+                function: {
+                  name: 'inspect_file',
+                  arguments: '{"path":"README.md"}',
+                },
+              },
+            ],
+          },
+          finish_reason: 'tool_calls',
+          logprobs: null,
+        },
+      ],
+      usage: {
+        prompt_tokens: 10,
+        completion_tokens: 4,
+        total_tokens: 14,
+      },
+    } satisfies OpenAI.Chat.ChatCompletion);
+
+    const result = await provider.chat([createUserMessage('Inspect README')], {
+      model: 'deepseek-v4-pro',
+      tools: [createToolSchema()],
+    });
+
+    expect(client.chat.completions.create).toHaveBeenCalledWith({
+      model: 'deepseek-v4-pro',
+      messages: [{ role: 'user', content: 'Inspect README' }],
+      tools: [
+        {
+          type: 'function',
+          function: {
+            name: 'inspect_file',
+            description: 'Inspect a file',
+            parameters: createToolSchema().parameters,
+          },
+        },
+      ],
+      tool_choice: 'auto',
+      thinking: { type: 'enabled' },
+      reasoning_effort: 'high',
+    });
+    if (result.role !== 'assistant') throw new Error('Expected assistant message');
+    expect(result.toolCalls).toEqual([
+      {
+        id: 'call_1',
+        type: 'function',
+        function: {
+          name: 'inspect_file',
+          arguments: '{"path":"README.md"}',
+        },
+      },
+    ]);
+  });
+
+  it('emits native Chat Completions request and response payloads', async () => {
+    const provider = new DeepSeekProvider({ apiKey: 'deepseek-key' });
+    const client = getClient(provider);
+    client.chat.completions.create.mockResolvedValue({
+      id: 'deepseek-chat-native',
+      object: 'chat.completion',
+      created: 1,
+      model: 'deepseek-v4-flash',
+      choices: [
+        {
+          index: 0,
+          message: { role: 'assistant', content: 'native', refusal: null },
+          finish_reason: 'stop',
+          logprobs: null,
+        },
+      ],
+    } satisfies OpenAI.Chat.ChatCompletion);
+    const events: IProviderNativeRawPayloadEvent[] = [];
+
+    await provider.chat([createUserMessage('Hello')], {
+      model: 'deepseek-v4-flash',
+      onProviderNativeRawPayload: (event) => events.push(event),
+    });
+
+    expect(events).toEqual([
+      expect.objectContaining({
+        provider: 'deepseek',
+        apiSurface: 'chat-completions',
+        payloadKind: 'request',
+      }),
+      expect.objectContaining({
+        provider: 'deepseek',
+        apiSurface: 'chat-completions',
+        payloadKind: 'response',
+        payload: expect.objectContaining({ id: 'deepseek-chat-native' }),
+      }),
+    ]);
+  });
+
+  it('uses streaming assembly when text deltas are requested', async () => {
+    const provider = new DeepSeekProvider({ apiKey: 'deepseek-key' });
+    const client = getClient(provider);
+    client.chat.completions.create.mockResolvedValue(
+      asyncIterableFrom([
+        createChunk('Hello'),
+        createChunk(' from '),
+        createChunk('DeepSeek', 'stop'),
+      ]),
+    );
+    const onTextDelta = vi.fn();
+
+    const result = await provider.chat([createUserMessage('Hello')], {
+      model: 'deepseek-v4-flash',
+      onTextDelta,
+    });
+
+    expect(client.chat.completions.create).toHaveBeenCalledWith(
+      {
+        model: 'deepseek-v4-flash',
+        messages: [{ role: 'user', content: 'Hello' }],
+        stream: true,
+      },
+      undefined,
+    );
+    expect(onTextDelta).toHaveBeenNthCalledWith(1, 'Hello');
+    expect(onTextDelta).toHaveBeenNthCalledWith(2, ' from ');
+    expect(onTextDelta).toHaveBeenNthCalledWith(3, 'DeepSeek');
+    expect(result.content).toBe('Hello from DeepSeek');
+  });
+
+  it('reports function calling without provider-native web tools', () => {
+    const provider = new DeepSeekProvider({ apiKey: 'deepseek-key' });
+
+    expect(provider.getCapabilities()).toEqual({
+      functionCalling: { supported: true },
+      nativeWebTools: {
+        webSearch: {
+          supported: false,
+          enabled: false,
+          source: 'openai-compatible-chat-completions',
+          reason:
+            'DeepSeek OpenAI-compatible Chat Completions supports declared function tools, not provider-native web search.',
+        },
+        webFetch: {
+          supported: false,
+          enabled: false,
+          source: 'openai-compatible-chat-completions',
+          reason:
+            'DeepSeek OpenAI-compatible Chat Completions supports declared function tools, not provider-native web fetch.',
+        },
+      },
+    });
+  });
+
+  it('yields universal assistant messages from direct chatStream chunks', async () => {
+    const provider = new DeepSeekProvider({ apiKey: 'deepseek-key' });
+    const client = getClient(provider);
+    client.chat.completions.create.mockResolvedValue(
+      asyncIterableFrom([createChunk('Part one'), createChunk(' done', 'stop')]),
+    );
+
+    const chunks: TUniversalMessage[] = [];
+    for await (const chunk of provider.chatStream?.([createUserMessage('Stream')], {
+      model: 'deepseek-v4-flash',
+    }) ?? []) {
+      chunks.push(chunk);
+    }
+
+    expect(client.chat.completions.create).toHaveBeenCalledWith({
+      model: 'deepseek-v4-flash',
+      messages: [{ role: 'user', content: 'Stream' }],
+      stream: true,
+    });
+    expect(chunks.map((chunk) => chunk.content)).toEqual(['Part one', ' done']);
+    expect(chunks[1]?.metadata?.['isComplete']).toBe(true);
+  });
+
+  it('wraps upstream chat failures with DeepSeek context', async () => {
+    const provider = new DeepSeekProvider({ apiKey: 'deepseek-key' });
+    const client = getClient(provider);
+    client.chat.completions.create.mockRejectedValue(new Error('Invalid API key'));
+
+    await expect(
+      provider.chat([createUserMessage('Hello')], { model: 'deepseek-v4-flash' }),
+    ).rejects.toThrow('DeepSeek chat failed: Invalid API key');
+  });
+});