qhub-serve 1.2.0

Local development server for Kipu Quantum Hub services, imitates the platform runtime.

qhub-serve

Local development server for Kipu Quantum Hub services.

Runs a Kipu Quantum Hub workspace locally and exposes it through an HTTP server that imitates the platform runtime — same async job lifecycle, same API endpoints, same run(data, params) invocation convention.

qhub-serve runs inside the workspace's own uv venv, so all the workspace's dependencies are naturally available.

How the platform runtime works

The Kipu Quantum Hub platform invokes your service by calling a run function in src/program.py:

def run(data: DataModel, params: dict) -> ResultModel:
    ...

qhub-serve does exactly the same thing locally, wrapping it in an HTTP server that exposes the full job lifecycle API (submit → poll status → fetch result).

Usage

Via the qhub CLI (recommended)

qhubctl serve

The qhub serve command adds qhub-serve as a dev dependency to your workspace (if not already present) and runs it via uv run, so it always executes inside your workspace's own venv where all your dependencies are installed.

Without the CLI

qhub-serve is a standard Python package and can be used independently of the qhub CLI. The key requirement is that it runs inside your workspace's own venv so that all of your service's dependencies are available.

1. Add qhub-serve as a dev dependency to your workspace:

cd /path/to/your/workspace
uv add --dev qhub-serve

2. Run it from your workspace directory:

uv run automatically activates the workspace venv before executing the command, so your service dependencies are always on the path:

uv run qhub-serve

This is equivalent to running qhub serve without the CLI wrapper. The --workspace flag defaults to the current directory, so the above is the same as:

uv run qhub-serve --workspace .

To target a workspace located elsewhere:

uv run --project /path/to/your/workspace qhub-serve --workspace /path/to/your/workspace

Using a pre-activated venv directly:

If your workspace venv is already activated (e.g. source .venv/bin/activate), you can invoke the script directly:

qhub-serve
# or
python -m qhub_serve

Options

qhub-serve [--workspace DIR] [--host HOST] [--port PORT] [--entrypoint MODULE:FUNCTION]

  --workspace DIR         Path to the workspace directory (default: current working directory)
  --host HOST             Bind host (default: 127.0.0.1)
  --port PORT             Bind port (default: 8081)
  --entrypoint MOD:FN     Entrypoint in module:function notation, relative to the workspace
                          (default: src.program:run)

The server watches the workspace directory and reloads automatically on any file change.

HTTP API

The server exposes the same API the Kipu Quantum Hub platform uses:

Method	Path	Description
GET	/	List all service executions
POST	/	Submit a service execution — returns immediately with status: PENDING
GET	/{id}	Poll execution status (PENDING / RUNNING / SUCCEEDED / FAILED / CANCELLED)
GET	/{id}/result	Fetch the result once the job has succeeded
GET	/{id}/result/{file}	Download a specific result file
GET	/{id}/log	Get log entries for a service execution
PUT	/{id}/cancel	Cancel a running execution

Example — submit a job:

curl -X POST http://127.0.0.1:8081/ \
  -H "Content-Type: application/json" \
  -d '{"data": {"values": [1, 2, 3]}, "params": {}}'
# → {"id": "abc-123", "status": "PENDING", ...}

Poll until done, then fetch the result:

curl http://127.0.0.1:8081/abc-123
# → {"id": "abc-123", "status": "SUCCEEDED", ...}

curl http://127.0.0.1:8081/abc-123/result
# → {"sum": 6.0, "_links": {...}, "_embedded": {...}}

Interactive API docs are available at http://127.0.0.1:8081/docs while the server is running.

Development

Setup

Clone the repository and install all dependencies (including dev dependencies) into a local venv:

uv venv
uv sync

Run the server against the built-in sample workspace

The repository ships a minimal sample workspace under workspace/ that sums a list of floats. It is the canonical target for local development and smoke-testing.

Run the server directly from the repo root using the local source:

uv run qhub-serve --workspace workspace

Then in another terminal, submit a test job:

curl -X POST http://127.0.0.1:8081/ \
  -H "Content-Type: application/json" \
  -d '{"data": {"values": [1, 5.2, 20, 7, 9.4]}, "params": {"round_off": false}}'

Alternatively, drive uvicorn directly (useful when iterating on the server itself, as it gives more control over reload behavior):

ENTRYPOINT=src.program:run PYTHONPATH=workspace uv run uvicorn qhub_serve.app:app --reload

Run the tests

uv run pytest

Build the package

uv build

Publishing

Releases are managed via semantic-release (conventional commits). On merge to the default branch, the CI pipeline:

1. Runs tests
2. Determines the next version from commit messages
3. Publishes the new version to PyPI via uv publish

The project must be set up as a Trusted Publisher on PyPI for this to work.

qhubctl CLI integration

The qhubctl CLI drives qhub-serve via uv, ensuring it always runs inside the user's workspace venv where all workspace dependencies are available.

The qhubctl serve command does the following:

# 1. Add qhub-serve as a dev dependency (idempotent)
uv add --dev qhub-serve --project <workspace-dir>

# 2. Run it inside the workspace venv
uv run --project <workspace-dir> qhub-serve --workspace <workspace-dir>

The only prerequisite is that uv is installed and the workspace is a valid uv project, both of which are guaranteed by the qhubctl CLI's workspace bootstrap flow.

License

Apache-2.0 | Copyright 2026-present Kipu Quantum GmbH