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 and ksadk/studio/static, so users can open both local UIs without a Node toolchain.

The hosted web UI source lives in the ksadk-web repo. The public ksadk-python clean export and Python artifacts contain only the two reviewed production static payloads; editable Studio React / TypeScript source is not published.

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.

make build-wheel and release builds print the KsADK version, source commit, working-tree state, wheel filename, and SHA-256 for the artifact that was actually produced. Code builds likewise print the version, source type, and commit id embedded in the zip. Use that artifact provenance for diagnosis instead of inferring the cloud version from the developer machine.

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 is the release build entrypoint. It generates both frontend payloads, then runs uv build, wheel/sdist content assertions, and twine check dist/*.

clean-dist clears the previous dist/
sync-ksadk-web-static fetches the pinned, published UI static assets
build-studio-static builds Studio in a complete source workspace, or validates and reuses the reviewed static payload in a public clean export
uv build builds the sdist/wheel
tests/test_runtime_common_packaging.py inspects wheel and sdist 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/.
neither the wheel nor the sdist contains editable ksadk/studio/react-ui/ source.
the wheel does not contain historical build residue (stale dist/ fragments, .zread/, .pypirc).
the wheel includes the synced ksadk/server/static/index.html and generated ksadk/studio/static/index.html, with their assets/ entries, so both local UIs open 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 and Studio. The hosted web UI source belongs to ksadk-web; editable Studio source does not enter the public repository, sdist, or wheel.

Official PyPI releases run through .github/workflows/publish-pypi.yml, triggered by a GitHub Release published event or workflow_dispatch. The workflow runs make public-preflight, which synchronizes the pinned ksadk-web static payload (select another published version via the ksadk_web_version input) and validates the reviewed Studio static payload, then uploads through OIDC Trusted Publishing without relying on a long-lived PyPI token. The gate rejects any editable Studio React / TypeScript source.

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