packages/llm/llm-deepseek/README.md

# @deepseek-ai/dsh-llm-deepseek

DeepSeek chat-completions adapter for the harness LLM seam: hand-rolled `fetch` + SSE translation from the official wire format (source of truth: the API docs — guides/thinking_mode, guides/tool_calls, api/create-chat-completion) into the `StreamChunk` protocol.

A second, independent implementation of the same seam exists in `@deepseek-ai/dsh-llm-pi-ai` (library-backed). Same Config shape — pick one per context (registering both for the same model names throws by design).

## Config

```yaml
- id: llm-deepseek
  name: '@deepseek-ai/dsh-llm-deepseek'
  config:
    apiKey: !!js process.env.DEEPSEEK_API_KEY    # or rely on the env fallback
    baseURL: !!js process.env.DEEPSEEK_BASE_URL  # default: https://api.deepseek.com
    models: [deepseek-v4-flash, deepseek-v4-pro] # one adapter, registered for each name
    thinking: enabled        # optional; provider default is enabled
    reasoningEffort: high    # optional; high | max — omitted ⇒ not sent
```

`models` lists every model name this one adapter instance serves: the adapter registers itself for each (the harness model name IS the wire `model` string), so a `generate`/`stream` call routes to it whenever `options.model` is any of them. Registering a second adapter for a name already taken throws `LlmError('DUPLICATE_ADAPTER')` (the LLM service enforces one adapter per model, all-or-nothing).

`reasoningEffort` is **omitted by default** — when unset, the `reasoning_effort` wire field is not sent and the server applies its own default for the model. The only accepted values are `high` and `max` (DeepSeek's official effort levels). It is meaningful only with thinking enabled (the provider default).

`thinking`/`reasoningEffort` are adapter-level request defaults serialized as the official top-level `thinking: {type}` / `reasoning_effort` wire fields. They live in adapter config (not `GenerateOptions`) to keep the core vocabulary provider-neutral.

## App attribution

Every request carries the shared attribution header from dsh-llm's `attributionHeaders()` - the mandatory `User-Agent` baseline identifying the harness (see [dsh-llm § App attribution](../llm/README.md#app-attribution-attributionts)). Direct DeepSeek requests and OpenAI-compatible gateway requests get no provider-specific app-attribution headers under this adapter contract; OpenRouter app attribution is deferred to a future explicit OpenRouter adapter or mode.

## Wire-format notes (verified live + against the official docs)

- Streaming only (`stream_options.include_usage` always on). `usage` may arrive attached to the finish chunk or as a trailing usage-only chunk — the translator defers both to `[DONE]`, so `usage` always precedes `finish` and nothing follows `finish`.
- The first thinking-mode chunk carries `reasoning_content: ""` — handled (no spurious reasoning block).
- **Reasoning passback rule**: on assistant turns that carried tool calls, `reasoning_content` is serialized back in history (required by the API in thinking mode); on tool-call-free turns it is dropped (ignored anyway — saves tokens).
- Cache accounting: `cacheReadTokens` ← `prompt_cache_hit_tokens` / `prompt_tokens_details.cached_tokens`; DeepSeek reports no cache-write metric.

## Limitations (MVP, documented deliberately)

- `tool_choice` is not mapped (not part of the core vocabulary).

## Errors

Non-2xx responses throw `LlmError` with stable codes: `AUTH` (401/403), `RATE_LIMIT` (429), `INVALID_REQUEST` (400), `SERVER` (5xx), `HTTP_<status>` otherwise. Protocol violations throw `STREAM_CLOSED` (no `[DONE]`) or `MALFORMED_RESPONSE` (bad JSON payload). Unknown wire `finish_reason`s (e.g. `content_filter`, `insufficient_system_resource`) become `finish {kind: 'error', code: <REASON>}` chunks.

## Testing

Unit suites run against a local `node:http` mock SSE server (no network). Real-API coverage lives in `tests/adapter.e2e.ts` (`pnpm run test:e2e`, key-gated): V4 Flash + V4 Pro across thinking enabled/disabled and both official effort levels, including the thinking+tools round trip with reasoning passback.
Add two DeepSeek LLM adapters: dsh-llm-deepseek and dsh-llm-pi-ai 2026-06-13 00:28:29 +08:00			`# @deepseek-ai/dsh-llm-deepseek`

docs: unwrap hard-wrapped Markdown to one line per paragraph 2026-06-13 18:39:20 +08:00			DeepSeek chat-completions adapter for the harness LLM seam: hand-rolled `fetch` + SSE translation from the official wire format (source of truth: the API docs — guides/thinking_mode, guides/tool_calls, api/create-chat-completion) into the `StreamChunk` protocol.
Add two DeepSeek LLM adapters: dsh-llm-deepseek and dsh-llm-pi-ai 2026-06-13 00:28:29 +08:00
docs: unwrap hard-wrapped Markdown to one line per paragraph 2026-06-13 18:39:20 +08:00			A second, independent implementation of the same seam exists in `@deepseek-ai/dsh-llm-pi-ai` (library-backed). Same Config shape — pick one per context (registering both for the same model names throws by design).
Add two DeepSeek LLM adapters: dsh-llm-deepseek and dsh-llm-pi-ai 2026-06-13 00:28:29 +08:00
			`## Config`

			```yaml
			`- id: llm-deepseek`
			`name: '@deepseek-ai/dsh-llm-deepseek'`
			`config:`
			`apiKey: !!js process.env.DEEPSEEK_API_KEY # or rely on the env fallback`
			`baseURL: !!js process.env.DEEPSEEK_BASE_URL # default: https://api.deepseek.com`
			`models: [deepseek-v4-flash, deepseek-v4-pro] # one adapter, registered for each name`
			`thinking: enabled # optional; provider default is enabled`
			`reasoningEffort: high # optional; high \| max — omitted ⇒ not sent`
			```

docs: unwrap hard-wrapped Markdown to one line per paragraph 2026-06-13 18:39:20 +08:00			`models` lists every model name this one adapter instance serves: the adapter registers itself for each (the harness model name IS the wire `model` string), so a `generate`/`stream` call routes to it whenever `options.model` is any of them. Registering a second adapter for a name already taken throws `LlmError('DUPLICATE_ADAPTER')` (the LLM service enforces one adapter per model, all-or-nothing).
Add two DeepSeek LLM adapters: dsh-llm-deepseek and dsh-llm-pi-ai 2026-06-13 00:28:29 +08:00
docs: unwrap hard-wrapped Markdown to one line per paragraph 2026-06-13 18:39:20 +08:00			`reasoningEffort` is omitted by default — when unset, the `reasoning_effort` wire field is not sent and the server applies its own default for the model. The only accepted values are `high` and `max` (DeepSeek's official effort levels). It is meaningful only with thinking enabled (the provider default).
Add two DeepSeek LLM adapters: dsh-llm-deepseek and dsh-llm-pi-ai 2026-06-13 00:28:29 +08:00
docs: unwrap hard-wrapped Markdown to one line per paragraph 2026-06-13 18:39:20 +08:00			`thinking`/`reasoningEffort` are adapter-level request defaults serialized as the official top-level `thinking: {type}` / `reasoning_effort` wire fields. They live in adapter config (not `GenerateOptions`) to keep the core vocabulary provider-neutral.
Add two DeepSeek LLM adapters: dsh-llm-deepseek and dsh-llm-pi-ai 2026-06-13 00:28:29 +08:00
Implement mandatory app-attribution headers per the RFC 2026-07-04 18:14:42 +08:00			`## App attribution`

Merge remote app attribution branch 2026-07-04 22:47:53 +08:00			Every request carries the shared attribution header from dsh-llm's `attributionHeaders()` - the mandatory `User-Agent` baseline identifying the harness (see [dsh-llm § App attribution](../llm/README.md#app-attribution-attributionts)). Direct DeepSeek requests and OpenAI-compatible gateway requests get no provider-specific app-attribution headers under this adapter contract; OpenRouter app attribution is deferred to a future explicit OpenRouter adapter or mode.
Implement mandatory app-attribution headers per the RFC 2026-07-04 18:14:42 +08:00
Add two DeepSeek LLM adapters: dsh-llm-deepseek and dsh-llm-pi-ai 2026-06-13 00:28:29 +08:00			`## Wire-format notes (verified live + against the official docs)`

docs: unwrap hard-wrapped Markdown to one line per paragraph 2026-06-13 18:39:20 +08:00			- Streaming only (`stream_options.include_usage` always on). `usage` may arrive attached to the finish chunk or as a trailing usage-only chunk — the translator defers both to `[DONE]`, so `usage` always precedes `finish` and nothing follows `finish`.
			- The first thinking-mode chunk carries `reasoning_content: ""` — handled (no spurious reasoning block).
			- Reasoning passback rule: on assistant turns that carried tool calls, `reasoning_content` is serialized back in history (required by the API in thinking mode); on tool-call-free turns it is dropped (ignored anyway — saves tokens).
			- Cache accounting: `cacheReadTokens` ← `prompt_cache_hit_tokens` / `prompt_tokens_details.cached_tokens`; DeepSeek reports no cache-write metric.
Add two DeepSeek LLM adapters: dsh-llm-deepseek and dsh-llm-pi-ai 2026-06-13 00:28:29 +08:00
			`## Limitations (MVP, documented deliberately)`

			- `tool_choice` is not mapped (not part of the core vocabulary).

			`## Errors`

docs: unwrap hard-wrapped Markdown to one line per paragraph 2026-06-13 18:39:20 +08:00			Non-2xx responses throw `LlmError` with stable codes: `AUTH` (401/403), `RATE_LIMIT` (429), `INVALID_REQUEST` (400), `SERVER` (5xx), `HTTP_<status>` otherwise. Protocol violations throw `STREAM_CLOSED` (no `[DONE]`) or `MALFORMED_RESPONSE` (bad JSON payload). Unknown wire `finish_reason`s (e.g. `content_filter`, `insufficient_system_resource`) become `finish {kind: 'error', code: <REASON>}` chunks.
Add two DeepSeek LLM adapters: dsh-llm-deepseek and dsh-llm-pi-ai 2026-06-13 00:28:29 +08:00
			`## Testing`

feat: migrate to pnpm 2026-06-16 14:55:37 +08:00			Unit suites run against a local `node:http` mock SSE server (no network). Real-API coverage lives in `tests/adapter.e2e.ts` (`pnpm run test:e2e`, key-gated): V4 Flash + V4 Pro across thinking enabled/disabled and both official effort levels, including the thinking+tools round trip with reasoning passback.