Build And Package

This guide explains the public build boundary for KsADK projects and the SDK itself.

Common Commands

uv run --extra dev python -m twine check dist/*
make public-review

Web UI Artifacts

The ksadk-python wheel ships ksadk/server/static, so users can open the local UI without a Node toolchain.

Editable UI source is not part of ksadk-python; it lives in the ksadk-web repo only.

Local Project Build

For a normal agent project, start with local validation:

agentengine run . -i
agentengine web . --no-open

Cloud packaging can require credentials, registry access, object storage, or approved deployment targets. Public examples should keep those paths optional and provide a local fallback.

Dry Run

Use dry-run where supported to validate intent without creating remote resources:

agentengine --dry-run build .
agentengine --dry-run deploy .

Release Gate

make public-build-check runs wheel-content assertions between uv build and twine check dist/*, so a clean build is enforced before any upload.

clean-dist clears the previous dist/
sync-ksadk-web-static fetches the latest UI static assets
uv build builds the sdist/wheel
tests/test_runtime_common_packaging.py inspects wheel contents
twine check dist/* final check

The assertions guarantee:

the wheel does not contain legacy ksadk/server/web-ui/ sources, build outputs, or node_modules/.
the wheel does not contain historical build residue (stale dist/ fragments, .zread/, .pypirc).
the wheel includes the synced ksadk/server/static/index.html and its assets/ entry, so the local UI opens right after install.

Match the official release gate locally

make public-preflight layers public-audit, public-test, and docs-site-build on top of public-build-check. It is the mandatory local gate before pushing to GitHub, PyPI, or a Release.

Artifact Rules

Release artifacts must not contain:

.env, .pypirc, kubeconfig, cookies, access keys, or tokens.
private registry names.
internal Helm values.
generated local state under .agentengine/.
node_modules/.
hosted-only UI bundles in the Python wheel.
customer data, traces, logs, or screenshots.

The Python package may include static UI assets needed by agentengine web. Editable UI source belongs to ksadk-web.

Official PyPI releases run through .github/workflows/publish-pypi.yml, triggered by a GitHub Release published event or workflow_dispatch. The workflow first runs make sync-ksadk-web-static (default @kingsoftcloud/ksadk-web@latest; pin a version via the ksadk_web_version input), then make public-preflight, and finally uploads through OIDC Trusted Publishing without relying on a long-lived PyPI token.

New in 0.6.7

Serverless deployment injects the resolved UI runtime configuration into the pod environment as KSADK_UI_PROFILE, KSADK_UI_PATH, KSADK_UI_URL, and KSADK_UI_BUNDLE_PATH. ksadk.server.app reads these variables inside the pod to restore UI runtime configuration, without packaging local .agentengine/ state into the image.

Python SDK Release Candidate

Maintainers preparing a public SDK release should run the open-source gate:

python3 scripts/audit_public_history_paths.py --json --allow-violations
git diff --check

The gate covers:

public repository audit.
clean ksadk-python export audit.
clean ksadk-web export audit.
public docs build and audit.
Python package build.
release artifact audit.
wheel smoke install.
Web UI candidate tests and builds.
path-level Git history audit evidence for publication strategy.

The history path audit is intentionally path-level only. It helps decide whether the first public import can use full history, clean export, or a reviewed history rewrite. It does not replace a content-level secret scan.

Clean Export Versus Full History

For the first public import, maintainers must choose one strategy:

Strategy	When to use	Required evidence
clean export	history contains internal paths or deployment material	clean export manifest, tree digest, artifact audit, approval record
rewritten history	preserving public history is important and feasible	rewrite procedure, content-level history secret scan, reviewer approval
full history	only when history audit and content scan are clean	path-level and content-level history evidence

If the path-level audit reports blocked historical paths, do not import full history directly. Use the reviewed clean export unless maintainers explicitly approve a history rewrite and content-level scan.

Maintainer Review Before Public Push

The intended publication sequence:

Push the review branch to the private maintainer review channel.
Complete maintainer review.
Import reviewed source into kingsoftcloud/ksadk-python.
Import reviewed UI source into kingsoftcloud/ksadk-web.
Enable GitHub Pages.
Create GitHub releases.
Publish PyPI or TestPyPI packages.

Do not skip the maintainer review step. PyPI credentials, TestPyPI credentials, and release tokens must stay outside GitHub source.

Review Bundle

The review bundle should include:

full diff.
candidate export manifests.
clean-export SHA-256 tree digests.
publication state checks.
path-level history audit.
approval request.
final blocker list.

Reviewers should be able to answer four questions from the bundle:

what source will become public?
what was intentionally removed?
what commands passed before publication?
which Git history strategy was approved?

Build And Package

On this page