chump-server

The backend hosts ChumpAgent instances over ai-query's built-in agent server routes.

Run

uv sync
uv run chump-server

Install

End-user Chump release archives bundle a platform-specific chump-server binary next to the CLI. The PyPI package remains useful for development, debugging, and direct backend runs:

uv run chump-server

During repository development, uv uses the released ai-query version pinned in pyproject.toml and uv.lock.

Build a local standalone backend binary:

python scripts/build_binary.py

The output is written to dist/bin/chump-server-<platform>. Use python scripts/build_binary.py --mode onedir --archive to produce the release archive at dist/bin/chump-server-<platform>.tar.gz.

Release

chump-server versions come from git tags through hatch-vcs.

git tag chump-server-v0.1.0
git push origin chump-server-v0.1.0

Pushing a chump-server-v* tag runs the PyPI job and creates a GitHub Release in .github/workflows/release.yml. The same release also gets platform-specific standalone backend runtime archives named chump-server-<platform>.tar.gz attached for sandbox/server-only deployments. Legacy onefile assets named chump-server-<platform> are also attached so older clients can update across the runtime archive transition.

Environment

CHUMP_HOST: default 127.0.0.1
CHUMP_PORT: default 8080
CHUMP_WORKSPACE_ROOT: defaults to the parent directory of server/
CHUMP_STATE_DIR: optional override for the workspace state directory; defaults to a per-workspace path under the user's OS state/data directory
CHUMP_PROVIDER: default chump_cloud; also supports codex, github_copilot, openai, google, anthropic, workers_ai, deepseek, openrouter, groq, xai, opencode, opencode_go, and zenmux
CHUMP_MODEL: provider-specific default
CHUMP_CLOUD_BASE_URL: optional OpenAI-compatible base URL for the chump_cloud provider
CHUMP_MAX_STEPS: default 250
CHUMP_RETRY_MAX_ATTEMPTS: provider-call retry attempts; default 3, set 1 to disable
CHUMP_RETRY_INITIAL_DELAY: initial retry delay in seconds; default 0.5
CHUMP_RETRY_MAX_DELAY: max retry delay in seconds; default 8
CHUMP_RETRY_BACKOFF: retry delay multiplier; default 2
CHUMP_RETRY_JITTER: enable retry jitter; default 1
CHUMP_COMMAND_TIMEOUT: default 120
CHUMP_MANAGED_SERVER_IDLE_TIMEOUT: optional process idle shutdown timeout in seconds
CHUMP_REASONING_EFFORT: optional OpenAI-compatible reasoning effort
CHUMP_REASONING_BUDGET: optional Gemini-compatible thinking budget
CHUMP_VERBOSE: default 1

Prompt-cache benchmark

Chump persists provider-reported token usage for every model step. Report the observed cache hit rate across local sessions, grouped by provider and model:

uv run --project server python server/scripts/benchmark_prompt_cache.py

The report includes two different rates:

Request hit: model calls where cached_tokens > 0.
Token hit: cached input tokens divided by all input tokens.

Use --provider google (repeatable), --min-calls 10, --json, or --state-root <path> to filter or automate the report. This benchmark reads local telemetry without making model requests or spending provider credits.

Metadata

Release files for chump-server 0.3.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for chump-server 0.3.5
File	Size	Uploaded
chump_server-0.3.5.tar.gz	218.6 kB	Sep 10, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for chump-server 0.3.5
File	Interpreter	ABI	Platform	Reset
chump_server-0.3.5-py3-none-any.whl 108.7 kB Sep 10, 2026	Python 3	none	any	Details

Total release size: 327.2 kB

Release files / chump_server-0.3.5.tar.gz

Download URL	chump_server-0.3.5.tar.gz
Size	218.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`ce1aa522a0cd4d2b1445f7c162282fcbb365d5da91928e74ca3ae9dd8d12fdb3`
BLAKE2b-256 checksum How to use checksums	`acac83d66864cccd3fd0c8a548537a08d199ae413bd46cb679e2e7e635d8f8d9`
Upload date	Sep 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Abdulmumin1/chump
Publishing commit: github.com/Abdulmumin1/chump/tree/07d7504bd8b4c2a398148fcb5795d2255e44b2dc

Workflow

Publishing configuration: github.com/Abdulmumin1/chump/blob/07d7504bd8b4c2a398148fcb5795d2255e44b2dc/.github/workflows/release.yml
Publishing logs: github.com/Abdulmumin1/chump/actions/runs/34458390150/attempts/1

Artifact

Subject: chump_server-0.3.5.tar.gz
SHA-256 checksum: ce1aa522a0cd4d2b1445f7c162282fcbb365d5da91928e74ca3ae9dd8d12fdb3 Verifying attestations

Release files / chump_server-0.3.5-py3-none-any.whl

Download URL	chump_server-0.3.5-py3-none-any.whl
Size	108.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`c802b76967214654e9f1272dee0d5fdfe749bf6c031cd588a011cd9fc8c09110`
BLAKE2b-256 checksum How to use checksums	`d43e8faffe69b117be1dd9ad3491e3e5a49432ac255ac3c077ee5603b38d0506`
Upload date	Sep 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Abdulmumin1/chump
Publishing commit: github.com/Abdulmumin1/chump/tree/07d7504bd8b4c2a398148fcb5795d2255e44b2dc

Workflow

Publishing configuration: github.com/Abdulmumin1/chump/blob/07d7504bd8b4c2a398148fcb5795d2255e44b2dc/.github/workflows/release.yml
Publishing logs: github.com/Abdulmumin1/chump/actions/runs/34458390150/attempts/1

Artifact

Subject: chump_server-0.3.5-py3-none-any.whl
SHA-256 checksum: c802b76967214654e9f1272dee0d5fdfe749bf6c031cd588a011cd9fc8c09110 Verifying attestations