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.2

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.2
File	Size	Uploaded
chump_server-0.3.2.tar.gz	216.9 kB	Aug 25, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for chump-server 0.3.2
File	Interpreter	ABI	Platform	Reset
chump_server-0.3.2-py3-none-any.whl 107.7 kB Aug 25, 2026	Python 3	none	any	Details

Total release size: 324.6 kB

Release files / chump_server-0.3.2.tar.gz

Download URL	chump_server-0.3.2.tar.gz
Size	216.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`d1931da8a50b079403e6165eb4e72902716491a993900ca175de27e8ec2f2dcf`
BLAKE2b-256 checksum How to use checksums	`7f2d81121eab6e1dc86c1bf0cc1ca74a996e49ed1d619a3928e6a7cdd425ea1d`
Upload date	Aug 25, 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/2cb1863c51502b60ab2c99a448ee994affbdf43b

Workflow

Publishing configuration: github.com/Abdulmumin1/chump/blob/2cb1863c51502b60ab2c99a448ee994affbdf43b/.github/workflows/release.yml
Publishing logs: github.com/Abdulmumin1/chump/actions/runs/32852792895/attempts/1

Artifact

Subject: chump_server-0.3.2.tar.gz
SHA-256 checksum: d1931da8a50b079403e6165eb4e72902716491a993900ca175de27e8ec2f2dcf Verifying attestations

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

Download URL	chump_server-0.3.2-py3-none-any.whl
Size	107.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`924f3c9855bcf51ff4e5083be0edb205d4e9a1aefbdc0fda02f34b790a603a56`
BLAKE2b-256 checksum How to use checksums	`f240a2a9fb251a17ecc4b4899c6160ee5b95ff4242878b3b9a2a000e2eccb366`
Upload date	Aug 25, 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/2cb1863c51502b60ab2c99a448ee994affbdf43b

Workflow

Publishing configuration: github.com/Abdulmumin1/chump/blob/2cb1863c51502b60ab2c99a448ee994affbdf43b/.github/workflows/release.yml
Publishing logs: github.com/Abdulmumin1/chump/actions/runs/32852792895/attempts/1

Artifact

Subject: chump_server-0.3.2-py3-none-any.whl
SHA-256 checksum: 924f3c9855bcf51ff4e5083be0edb205d4e9a1aefbdc0fda02f34b790a603a56 Verifying attestations