Cloud APIs — DeepSeek¶

BDPD's v0.8 Agent SDK is built and tested against DeepSeek, reached via its OpenAI-compatible API (base URL https://api.deepseek.com/v1, models deepseek-v4-flash and deepseek-v4-pro). The legacy aliases deepseek-chat / deepseek-reasoner still resolve at the time of writing but are deprecated on 2026-07-24 — use the explicit v4 names.

Both the platform agent (bdpd_agent.py) and the card game simulator (cards_ai_play.py) speak the OpenAI /v1/chat/completions protocol via the official openai Python SDK with a custom base_url. The whole code path has been used this way since the early experiments — DeepSeek's OpenAI-compatible endpoint is the supported configuration.

What "DeepSeek-only" means here¶

The code is, by construction, generic: any provider that implements the OpenAI /v1/chat/completions endpoint will respond to our calls if you point DEEPSEEK_BASE_URL (or API_BASE_URL) at it. You can see this in the docstring of cards_ai_play.py (it explicitly lists DeepSeek, OpenAI, Anthropic, Gemini base URLs as the same shape).

What we mean by DeepSeek-only is the supported and tested surface:

Tested. DeepSeek (deepseek-v4-flash with thinking disabled, deepseek-v4-pro with thinking) is what we exercise in regression and what the v0.8 examples target. Other endpoints may work — we just don't run them ourselves.
Documented. Pricing tables, model recommendations, troubleshooting recipes below refer to DeepSeek. Other providers are outside the doc's scope.
Why this stance. The maintainer has DeepSeek API credit and not the others. Writing official adapters for OpenAI / Anthropic / Gemini would mean shipping code we cannot validate — incompatible with the bit-identical strict regression guarantee the rest of BDPD upholds. Cost (~10× cheaper than gpt-4o-class) is a secondary factor; reducing the test/docs surface to ship v0.8 sooner is a tertiary one.

If you have credentials elsewhere and want to point BDPD at them, it will likely just work — but you are on your own for verification. The honest path to officially-supported multi-provider is for an external contributor with credentials on those providers to take ownership of that adapter; it is not on the v0.8 / v0.9 / v1.0 roadmap.

Configuration¶

Set the operating mode to api and provide the DeepSeek endpoint and key:

LLM_MODE=api \
  DEEPSEEK_API_KEY=sk-your-deepseek-key-here \
  API_MODEL=deepseek-v4-flash \
  ./scripts/run_arena.sh

BDPD_API_KEY also works if you prefer a provider-neutral name.

Environment Variables¶

The API key is resolved by trying these variables in order (first non-empty wins):

DEEPSEEK_API_KEY — preferred, explicit
BDPD_API_KEY — project-level alias
OPENAI_API_KEY — generic fallback (the SDK reuses the OpenAI client)

The base URL follows the same pattern: DEEPSEEK_BASE_URL then API_BASE_URL, then the hardcoded default.

Variable	Default	Description
`LLM_MODE`	`local`	Set to `api` to use DeepSeek
`DEEPSEEK_API_KEY`	—	DeepSeek API key (highest priority)
`BDPD_API_KEY`	—	Alias; used if `DEEPSEEK_API_KEY` is unset
`OPENAI_API_KEY`	—	Last-resort fallback
`DEEPSEEK_BASE_URL`	`https://api.deepseek.com/v1`	DeepSeek base URL (with `/v1`; the SDK passes it directly to `openai.OpenAI`)
`API_BASE_URL`	—	Alias; used if `DEEPSEEK_BASE_URL` is unset
`API_MODEL`	`deepseek-v4-flash`	DeepSeek model identifier (also `deepseek-v4-pro` for thinking mode)
`AGENT_PORT`	`5001`	Port for `bdpd_agent.py` Flask server
`AGENT_NAME`	`LLM-Agent`	Display name in arena
`AGENT_MAX_HISTORY`	`3`	Number of past turns to include as conversation context

DeepSeek models¶

Model	Use case	Context	Notes
`deepseek-v4-flash`	Default for arena agents and card play	128K	Fast, good cost/quality for high-call sweeps. v0.8 calls it with `extra_body={"thinking":{"type":"disabled"}}` — thinking is on by default at the API level and is silently incompatible with our tool loop (reasoning_content must be replayed across tool_call boundaries, which we do not yet plumb)
`deepseek-v4-pro`	Agents that need to deliberate before acting	64K reasoning + 64K context	Higher tier; supports `reasoning_effort=low\|medium\|high\|max`. Returns a `reasoning_content` field — captured by BDPD into `turns.jsonl` reasoning trace
`deepseek-chat` / `deepseek-reasoner`	Legacy aliases	—	`deepseek-chat` ≡ `v4-flash` with thinking disabled; `deepseek-reasoner` ≡ `v4-flash` with thinking enabled. Deprecated 2026-07-24 — migrate to the explicit v4 names

The eval harness (v0.8) runs scenarios against both and produces a comparative table — same provider, two roles.

Card Game API Configuration¶

When running card game LLM tournaments, DeepSeek is configured via CLI flags:

python agents/cards_ai_play.py \
  --deck1 stranger --deck2 warrior \
  --cards cards/cards_v03.json \
  --api-model deepseek-v4-flash \
  --api-base-url https://api.deepseek.com \
  --games 20

The API key is read from the BDPD_API_KEY environment variable by default (--api-key-env flag); falls back to the same DEEPSEEK_API_KEY → BDPD_API_KEY → OPENAI_API_KEY chain when called via sweep_card_tournaments.py.

Rate Limiting and Cost¶

Model	Input Price	Output Price	Context
`deepseek-v4-flash`	$0.14/M tokens	$0.28/M tokens	128K
`deepseek-v4-pro`	$0.55/M tokens	$2.19/M tokens	64K

A 20-game card tournament (~8 turns/game, ~500 tokens/turn) with deepseek-v4-flash costs approximately $0.02–$0.05 in API credits.

DeepSeek's rate limits are generous; BDPD's sequential turn structure naturally spaces requests 1–5 seconds apart and stays well within typical limits.

For large parametric sweeps (hundreds of games), consider running with --lock-defection and --games 1 per cell, or use local models (LLM_MODE=local) for cost-free experimentation. See Local Models.

Technical note: OpenAI-compatible protocol¶

The client code (agents/cards_ai_play.py, agents/bdpd_agent.py) uses the official openai Python SDK with a custom base_url. Since DeepSeek implements the same /v1/chat/completions shape, the SDK works against it unchanged. The same is true, in principle, of any OpenAI-compatible endpoint — see the "What DeepSeek-only means" section above for what we test vs what merely works.

Troubleshooting¶

401 Unauthorized

Ensure one of the API key variables is set:

echo ${DEEPSEEK_API_KEY:-${BDPD_API_KEY:-$OPENAI_API_KEY}}  # should print your key

Connection timeout

Check network and DeepSeek endpoint:

curl -s https://api.deepseek.com/v1/models \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY"

Model not found

List models actually available to your account:

curl -s https://api.deepseek.com/v1/models \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" | python -m json.tool

Agent timeout on slow API responses

deepseek-v4-pro (or any thinking-mode call) can take 10–30s. Bump the arena's agent timeout in the creation payload:

{ "agentTimeout": 60000 }