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

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.3
File	Size	Uploaded
chump_server-0.3.3.tar.gz	218.3 kB	Aug 25, 2026	Details

Built distribution (wheel)

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

Total release size: 326.9 kB

Release files / chump_server-0.3.3.tar.gz

Download URL	chump_server-0.3.3.tar.gz
Size	218.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`44849e469aec17d76c41e7e438b748597312a6fd82fb2bbfebd0f87e69fc2632`
BLAKE2b-256 checksum How to use checksums	`8308df51b455544b3f92f7378bad4d596abc5e5681c89ceb9b30d91cab13d395`
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/5a587b7052209fe9581f29a05d064848614dfbd1

Workflow

Publishing configuration: github.com/Abdulmumin1/chump/blob/5a587b7052209fe9581f29a05d064848614dfbd1/.github/workflows/release.yml
Publishing logs: github.com/Abdulmumin1/chump/actions/runs/32877172323/attempts/1

Artifact

Subject: chump_server-0.3.3.tar.gz
SHA-256 checksum: 44849e469aec17d76c41e7e438b748597312a6fd82fb2bbfebd0f87e69fc2632 Verifying attestations

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

Download URL	chump_server-0.3.3-py3-none-any.whl
Size	108.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`a14ee1f9533dac818dcf3adbda29feaf411e301b40e5437c1c9b725877b5186d`
BLAKE2b-256 checksum How to use checksums	`8e3532abe0892ea7f71b6534ddf18bc20e9477fa2ebc5ff1e878f10f51af727e`
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/5a587b7052209fe9581f29a05d064848614dfbd1

Workflow

Publishing configuration: github.com/Abdulmumin1/chump/blob/5a587b7052209fe9581f29a05d064848614dfbd1/.github/workflows/release.yml
Publishing logs: github.com/Abdulmumin1/chump/actions/runs/32877172323/attempts/1

Artifact

Subject: chump_server-0.3.3-py3-none-any.whl
SHA-256 checksum: a14ee1f9533dac818dcf3adbda29feaf411e301b40e5437c1c9b725877b5186d Verifying attestations