Demo Pack Pipeline

This page explains how pack_demo produces a runnable demo directory.

The current implementation is:

• espnet3/publication/demo/packing.py

Entry points

• stage method: BaseSystem.pack_demo()
• implementation: espnet3.publication.demo.packing.pack_demo

What pack_demo writes

pack_demo writes a bundle rooted at pack.out_dir or ${exp_dir}/demo.

Typical contents:

demo/
  app.py
  demo.yaml
  readme.md            # if referenced by ui.description
  ...                  # files copied from pack.include

Important

pack_demo does not pack the whole training or inference experiment by itself. The main model assets usually live in the separate model pack referenced by model.dir_or_tag.

In the common flow:

1. pack_model creates model_pack/
2. pack_demo creates demo/
3. demo/demo.yaml points at ../model_pack

That means the demo bundle and the model bundle are separate.

Main steps

1. Resolve the output directory

Priority:

1. demo_config.pack.out_dir
2. system.exp_dir / "demo"
3. Path.cwd() / "demo"

1. Rewrite and write demo.yaml

_prepare_demo_config(...):

• deep-copies the config
• drops pack-time-only keys such as pack.config_name
• stamps demo_dir
• ensures model.dir_or_tag exists
• rewrites local paths to relative paths when possible
• normalizes ui.description paths

Then pack_demo writes the resolved config as demo/demo.yaml.

2.1 What is rewritten in demo.yaml

_prepare_demo_config(...) mainly affects these fields:

Config field	What happens during packing
pack.config_name	removed
demo_dir	added to the packed config
model.dir_or_tag	inferred if missing, then normalized to a relative path when it points to a local directory
ui.description	normalized so copied files can be loaded from inside demo/

If model.dir_or_tag is omitted, pack_demo tries:

1. publication_config.pack_model.out_dir
2. ${exp_dir}/model_pack

So the packed demo often ends up with:

model:
  dir_or_tag: ../model_pack

1. Copy pack.include

pack.include entries are copied into the bundle. pack.exclude patterns are applied while copying include directories.

This is the main way to place extra files next to app.py.

Typical examples:

• local assets such as assets/
• extra markdown files
• helper Python files used by the recipe-local launcher
• small metadata files needed by the UI

Example:

pack:
  out_dir: demo
  include:
    - assets
    - prompts/example.wav
  exclude:
    - "**/*.log"

3.1 What include and exclude do not do

They do not automatically copy:

• ${exp_dir}
• checkpoints
• conf/training.yaml
• conf/inference.yaml
• conf/metrics.yaml

Those files belong to the model pack side unless you explicitly include them.

Config fields and packed files

The relation between config and files is roughly:

Config field	Affects packed file(s)
pack.out_dir	destination directory of the demo bundle
model.dir_or_tag	value written into demo.yaml; usually points to ../model_pack
ui.app_script	copied to demo/app.py
ui.description	copied into demo/ if it points to a real file
ui.inputs / ui.outputs	stored in demo/demo.yaml; consumed at runtime
pack.include	copied into demo/
pack.exclude	filters files while copying pack.include directories
upload_demo.*	stored in demo.yaml; used only by upload_demo

Where training.yaml and inference.yaml end up

This is the key boundary:

• pack_demo writes demo/demo.yaml
• pack_model writes the model bundle, including packed config files

So when the demo uses a local packed model directory:

demo/
  app.py
  demo.yaml
model_pack/
  conf/
    training.yaml
    inference.yaml
    metrics.yaml
    publication.yaml
  meta.yaml

The demo runtime opens model.dir_or_tag, then InferenceModel.from_packed(...) reads meta.yaml and finds the packed conf/inference.yaml from the model pack.

So:

• demo/ owns UI and launch-time files
• model_pack/ owns the packed inference/training-related config and model artifacts

When to include config files in demo/

Usually you do not need to copy training.yaml or inference.yaml into the demo bundle itself.

Do it only if:

• your custom launcher wants to display or inspect them directly
• you are shipping additional human-readable docs beside the UI
• you intentionally want duplicated copies outside the model pack

In that case, add them through pack.include.

1. Copy launcher assets

_setup_demo_assets(...) copies:

• ui.app_script to demo/app.py
• ui.description if it points to a real file

Upload path

upload_demo(...) reads:

• upload_demo.hf_repo
• optional upload_demo.repo_type
• optional upload_demo.organization
• optional upload_demo.create

Then it uploads the already-packed demo directory.

Related pages

Demo Config

See the config fields consumed during packing.

Runtime

See how the packed demo is loaded and executed.

Demo Stage

Read the stage-level flow for `pack_demo` and `upload_demo`.