deepseek-harness/python/README.md

DeepSeek Harness Python SDK

English | 中文

Python packages for driving DeepSeek Harness as a subprocess: a client SDK that spawns the dsh-jsonrpc-agent binary and talks newline-delimited JSON-RPC over stdio. The runtime carrier is the single-file executable produced by this repo; design, build, and acceptance details live in docs/rfc/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md.

Packages

Directory	Dist / module	Role
sdk	deepseek-harness / deepseek_harness	Client SDK: the DeepSeekHarness high-level turns API and the lower-level HarnessClient JSON-RPC client
sdk-runtime	deepseek-harness-runtime-bin / deepseek_harness_runtime	Runtime carrier: locates the bundled runtime binaries and ships the default agent configuration

Building the runtime executable

The platform executables are build artifacts, not checked into git. From the repo root:

pnpm install
pnpm exec tsx scripts/build-exe-for-python-sdk.ts                 # host platform, ~2 min
pnpm exec tsx scripts/build-exe-for-python-sdk.ts --skip-build    # lib/ artifacts already built
pnpm exec tsx scripts/build-exe-for-python-sdk.ts --targets=node24-linux-x64,node24-linux-arm64,node24-macos-arm64

Products land in dist-exe/ (CI artifact shape) and are synced into this package at sdk-runtime/src/deepseek_harness_runtime/runtime/dsh-jsonrpc-agent-pkg-<platform>-<arch> (platform: linux/macos; arch: x64/arm64) — after a build the SDK finds the executable with no further setup. Alternatively, download the platform artifact from the build-exe-for-python-sdk CI workflow (manual dispatch, or the build-exe PR label) and place it at that same path. Which plugins the exe bundles and how the carriers are organized: sdk-runtime README; the build also refreshes the dev-only node carrier (see "against the Node source" below).

Validating the SDK against the executable

export UV_PROJECT_ENVIRONMENT="$PWD/tmp/py-sdk-venv"   # keep the venv out of python/
uv sync --project python/sdk --group test
uv run --project python/sdk pytest python/sdk/tests/test_bundled_runtime.py   # boots the real carriers
uv run --project python/sdk pytest                                            # full suite; keyless tests included

For an interactive check (needs DEEPSEEK_API_KEY in the environment or the repo-root .env):

from deepseek_harness import DeepSeekHarness
print(DeepSeekHarness().run("say hi").final_response)   # auto-resolution picks the bundled exe

Running the SDK against the Node source (no executable)

Two flavors, both for repo members:

• Built node carrier — set DSH_RUNTIME_MODE=node and the SDK runs runtime/node/node_modules/@deepseek-ai/dsh-jsonrpc-agent/lib/bin.js on the system Node (>= 22.19). The tree is refreshed on every build-script run and is the same dependency closure the exe snapshots, so plugin semantics are identical. Never auto-selected, never distributed.
• Unbuilt source (tsx) — point the client straight at the bin's TypeScript source for edit-run loops and debugging: launch_args_override=("./node_modules/.bin/tsx", "packages/ui/jsonrpc-agent/src/bin.ts") with cwd at the repo root, plus a config via cordis=... (or rely on the default-config injection). sdk/tests/manual_sdk_agent_smoke.py is the worked example.

Distributing the Python packages

Python releases use stable tags of the form python-vX.Y.Z. The common staging script derives both distribution versions from the tag, pins deepseek-harness-runtime-bin==X.Y.Z in the SDK metadata, and rejects any other tag form. Build the pure SDK wheel once and one runtime wheel on each native platform:

python scripts/build-python-release.py --package sdk --tag python-v0.1.0 --output-dir dist-python
python scripts/build-python-release.py --package runtime --tag python-v0.1.0 --platform macos-arm64 --runtime-exe dist-exe/dsh-jsonrpc-agent-pkg-macos-arm64 --output-dir dist-python
pip install --find-links dist-python deepseek-harness==0.1.0

The runtime distribution is wheel-only and rejects sdist builds, missing executables, and mixed-platform payloads. Its three wheel tags are py3-none-manylinux_2_28_x86_64, py3-none-manylinux_2_28_aarch64, and py3-none-macosx_11_0_arm64; the SDK remains py3-none-any. A tag pipeline builds these four non-conflicting files and publishes them together, so a normal pip install deepseek-harness==X.Y.Z selects the matching runtime wheel and import deepseek_harness needs no runtime_bin.

Zero-config semantics

The runtime binary itself always requires an explicit config ($DSH_CORDIS_CONFIG, or a config path as the first argv argument), has no built-in fallback, and boots only what the config lists. Zero-config is SDK wrapper behavior: when the caller uses no explicit channel, the client injects the runtime package's checked-in default configuration (runtime/cordis.yml) via DSH_CORDIS_CONFIG; any explicit channel wins and disables the injection. The full injection conditions live in the sdk README; the default config's contents and the hard semantic in the sdk-runtime README.

The executable is also a supported direct interface; keep stdin open for the NDJSON JSON-RPC exchange and supply a config explicitly:

DSH_CORDIS_CONFIG=/absolute/path/cordis.yml ./dsh-jsonrpc-agent-pkg-macos-arm64

Test layout

test_client.py is fully keyless (a Python fake runtime is the peer). test_bundled_runtime.py boots each bundled carrier and skips per carrier when its artifact is missing. test_runtime_resolution.py covers the carrier-resolution rules without spawning anything.