anastasiyaw/codex-claude-code-config/deepseek-provider-contract

DeepSeek Provider Contract

This is a local, offline contract check. It neither reads DEEPSEEK_API_KEY nor sends code, transcripts, or secrets. A third-party harness is an implementation candidate, not a trusted route.

Use It In This Order

1. Classify the proposed prompt/data. Private archive, credentials, customer

data, and whole transcripts stay local unless the user explicitly authorizes that provider and scope.

1. Freeze the provider model, endpoint, request budget, and fallback in the

integration plan. Do not inherit defaults from a community wrapper.

1. Save a redacted request-history fixture that explicitly declares whether the

outbound request carries tools, then run:

The fixture shape is {"outbound_request":{"tools":[...]},"messages":[...]}; use "tools": [] only for an outbound tools-free request.

``text python skills/operational/deepseek-provider-contract/scripts/validate_deepseek_history.py fixture.json ``

1. Run the provider only in a bounded, opt-in experiment. Record model, endpoint,

max output, cache-usage fields, request digest, and observed result.

1. Compare against the incumbent on the same frozen task before adding any route

to a workflow. A passing history fixture proves message lifecycle only; it does not prove quality, price, availability, or data handling.

Required Invariants

• In thinking mode with tools, preserve the provider's complete assistant

message, including reasoning_content and tool_calls. Do not rebuild a reduced assistant message from content alone.

• Each tool result has the exact prior tool_call_id.
• While a request carries tools, retain the documented reasoning_content

from prior assistant turns in its history. Do not reduce this to only the most recent tool-call turn; check the current provider documentation because model and endpoint semantics change.

• Use strict schema only with the beta endpoint and only after validating the

supported JSON Schema subset. Never call a schema "strict" merely because it looks valid locally.

• Set output bounds explicitly and make cache hits/misses observability, not a

correctness promise.

Adoption Decision

Adopt a DeepSeek route only when all are true:

1. The offline history validator and its regression tests pass.
2. A redacted live canary succeeds with the exact frozen integration.
3. The frozen benchmark beats or materially supplements the current route.
4. Provider data scope and failure fallback are written down.

Otherwise keep this skill and the fixture only; do not install a global MCP.

Gotchas

• For a tools-bearing request, the current DeepSeek documentation requires the

prior assistant reasoning_content; a tools-free request has different context semantics. Treat the offline validator as a narrow fixture check, not a substitute for the live API contract.

• A response can say cache-hit while quality or latency still changes; measure

those separately.

• A history normalizer that strips reasoning_content can make the next

tools-bearing request request fail with HTTP 400 even if the first request succeeded.

• Model names, limits, pricing, and beta semantics are provider facts: re-check

the official documentation at the integration date.

Troubleshooting

Sources

• DeepSeek Thinking Mode
• DeepSeek Tool Calls