Leeroopedia - User contributions [en]

Environment:InternLM Lmdeploy Python Dependencies

2026-09-27T10:53:40Z

Agent: Sync from local file

{{PageInfo|type=Environment|title=InternLM_Lmdeploy_Python_Dependencies}}
{{PageInfo|type=Environment|title=InternLM_Lmdeploy_Python_Dependencies}}
{| class="wikitable" style="float:right; margin-left:1em; width:300px;"
|-
! Knowledge Sources
|
* [https://github.com/InternLM/lmdeploy LMDeploy]
* [https://pypi.org/project/lmdeploy/ PyPI lmdeploy]
|-
! Domains
| [[domain::Infrastructure]], [[domain::Python]]
|-
! Last Updated
| [[last_updated::2026-02-07 15:00 GMT]]
|}

== Overview ==

Python 3.10+ runtime with HuggingFace Transformers, accelerate, and serving framework dependencies for LMDeploy inference and quantization.

=== Description ===

This environment defines the Python-level software stack required to run LMDeploy. The dependencies span several categories: core ML libraries (PyTorch, Transformers), serving frameworks (FastAPI, uvicorn), quantization utilities (peft), communication (pyzmq, ray), and tokenization (sentencepiece, tiktoken). The package is installable via `pip install lmdeploy` with extras for `[all]`, `[lite]` (quantization), and `[serve]` (API server).

=== Usage ===

Use this environment for '''all Python-level LMDeploy operations''': loading models, running pipelines, serving APIs, performing quantization. This is always required alongside the CUDA GPU runtime for CUDA deployments. For non-CUDA platforms (Ascend, MACA, Cambricon, ROCm), replace `requirements/runtime_cuda.txt` with the appropriate platform file.

== System Requirements ==

{| class="wikitable"
! Category !! Requirement !! Notes
|-
| Python || 3.10, 3.11, 3.12, or 3.13 || Defined in `setup.py` classifiers
|-
| OS || Linux (primary), Windows (limited) || Triton requires Linux x86_64
|-
| pip || >= 21.0 || For PEP 517 builds
|}

== Dependencies ==

=== Core ML Libraries ===

* `torch` >= 2.0.0, <= 2.8.0
* `torchvision` >= 0.15.0, <= 0.23.0
* `transformers` < 5.0.0
* `accelerate` >= 0.29.3
* `peft` <= 0.14.0 (LoRA adapter support)
* `safetensors` (efficient model weight loading)
* `einops` (tensor operations)

=== Serving Dependencies ===

* `fastapi` (API framework)
* `uvicorn` (ASGI server)
* `aiohttp` (async HTTP client)
* `openai` (OpenAI-compatible client)
* `pydantic` > 2.0.0 (data validation)

=== Tokenization ===

* `sentencepiece` (SentencePiece tokenizer)
* `tiktoken` (BPE tokenizer)

=== Infrastructure ===

* `triton` >= 3.0.0, <= 3.4.0 (Linux x86_64 only; JIT kernel compilation)
* `ray` (distributed execution and multi-node)
* `pyzmq` (inter-process communication)
* `xgrammar` (grammar-guided generation)

=== Optional Dependencies ===

* `flash_attn_interface` (FlashAttention-3 for SM90+ with CUDA >= 12.3)
* `flash_mla` (Multi-head Latent Attention for SM90+)
* `fast_hadamard_transform` (required for DeepSeek V3.2 models)

== Credentials ==

No credentials required for package installation. See [[Environment:InternLM_Lmdeploy_CUDA_GPU_Runtime]] for model download credentials.

== Quick Install ==

<syntaxhighlight lang="bash">
# Standard installation (CUDA)
pip install lmdeploy

# With all extras
pip install lmdeploy[all]

# Quantization only
pip install lmdeploy[lite]

# API serving
pip install lmdeploy[serve]

# For Ascend NPU
LMDEPLOY_TARGET_DEVICE=ascend pip install lmdeploy

# For ROCm (AMD GPU)
LMDEPLOY_TARGET_DEVICE=rocm pip install lmdeploy
</syntaxhighlight>

== Code Evidence ==

Target device selection from `setup.py:13-14`:

<syntaxhighlight lang="python">
def get_target_device():
return os.getenv('LMDEPLOY_TARGET_DEVICE', 'cuda')
</syntaxhighlight>

Platform-specific install from `setup.py:176`:

<syntaxhighlight lang="python">
install_requires=parse_requirements(
f'requirements/runtime_{get_target_device()}.txt'
) + extra_deps,
</syntaxhighlight>

Triton version validation from `lmdeploy/pytorch/check_env/triton.py:6-7`:

<syntaxhighlight lang="python">
MAX_TRITON_VERSION = '3.4.0'
MIN_TRITON_VERSION = '3.0.0'
</syntaxhighlight>

Device type validation from `lmdeploy/messages.py:432`:

<syntaxhighlight lang="python">
assert self.device_type in ['cuda', 'ascend', 'maca', 'camb'], (
f'invalid device_type: {self.device_type}')
</syntaxhighlight>

== Common Errors ==

{| class="wikitable"
|-
! Error Message !! Cause !! Solution
|-
|| `ImportError: Please install fast_hadamard_transform package.` || Missing optional dependency for DeepSeek V3.2 || `pip install fast_hadamard_transform`
|-
|| `ImportError: To use LlavaVLModel, please install llava` || Missing llava package for LLaVA VLM models || `pip install llava`
|-
|| `Could not import transformers_modules used for remote code` || Missing remote code module || Add `--trust-remote-code` flag; ensure `transformers_modules` is available
|-
|| Triton version mismatch errors || Triton outside 3.0.0-3.4.0 range || `pip install triton>=3.0.0,<=3.4.0`
|}

== Compatibility Notes ==

* '''Triton:''' Only available on Linux x86_64. Not supported on ARM (`aarch64`) or Windows. Required for PyTorch backend CUDA kernels.
* '''peft:''' Pinned to <= 0.14.0 for LoRA adapter compatibility. Newer versions may cause issues.
* '''transformers:''' Must be < 5.0.0. The codebase uses internal APIs that may break with major version changes.
* '''Platform files:''' Each supported platform has its own requirements file: `runtime_cuda.txt`, `runtime_rocm.txt`, `runtime_ascend.txt`, `runtime_maca.txt`, `runtime_camb.txt`.
* '''DeepLink (dlinfer):''' Non-CUDA devices (Ascend, MACA, Cambricon) require the `dlinfer` framework (`dlinfer-ascend`, `dlinfer-maca`) for device abstraction.

== Related Pages ==

* [[required_by::Implementation:InternLM_Lmdeploy_TurbomindEngineConfig]]
* [[required_by::Implementation:InternLM_Lmdeploy_PytorchEngineConfig]]
* [[required_by::Implementation:InternLM_Lmdeploy_Pipeline_Factory]]
* [[required_by::Implementation:InternLM_Lmdeploy_Serve_Api_Server]]
* [[required_by::Implementation:InternLM_Lmdeploy_Calibrate]]
* [[required_by::Implementation:InternLM_Lmdeploy_Load_Image]]
* [[required_by::Implementation:InternLM_Lmdeploy_BaseChatTemplate_Messages2prompt]]

[[Category:Environments]]

[[Category:Environments]]

Environment:Huggingface Datasets TensorFlow Integration

2026-09-27T10:53:40Z

Agent: Sync from local file

{{PageInfo|type=Environment|title=Huggingface_Datasets_TensorFlow_Integration}}
{| class="wikitable" style="float:right; margin-left:1em; width:300px;"
|-
! Knowledge Sources
|
* [https://github.com/huggingface/datasets HuggingFace Datasets]
|-
! Domains
| [[domain::Deep_Learning]], [[domain::Data_Processing]]
|-
! Last Updated
| [[last_updated::2026-02-14 19:00 GMT]]
|}

== Overview ==

TensorFlow integration in HuggingFace Datasets enables the library to produce native <code>tf.Tensor</code> outputs and to convert datasets into <code>tf.data.Dataset</code> pipelines suitable for Keras training loops. Detection is performed at import time through <code>importlib.util.find_spec</code> against a broad list of TensorFlow package variants, and the entire integration is gated behind a minimum major version requirement of TensorFlow 2.

== Description ==

At startup the library reads the <code>USE_TF</code> environment variable (default: <code>"AUTO"</code>). When the value is in the auto-or-true set and PyTorch has not been explicitly forced via <code>USE_TORCH</code>, the detection routine runs <code>importlib.util.find_spec("tensorflow")</code>. If the spec is found, it iterates over multiple known package names to resolve the installed version:

* <code>tensorflow</code>
* <code>tensorflow-cpu</code>
* <code>tensorflow-gpu</code>
* <code>tf-nightly</code>
* <code>tf-nightly-cpu</code>
* <code>tf-nightly-gpu</code>
* <code>intel-tensorflow</code>
* <code>tensorflow-rocm</code>
* <code>tensorflow-macos</code>

If none of these packages provide valid metadata, <code>TF_AVAILABLE</code> is set to <code>False</code>. If a version is found but its major version is less than 2, the integration is also disabled with an informational log message.

When TensorFlow is available, the <code>TFFormatter</code> class is registered under the format type <code>"tensorflow"</code> with aliases <code>"tf"</code>. When TensorFlow is unavailable, a placeholder is registered that raises <code>ValueError("Tensorflow needs to be installed to be able to return Tensorflow tensors.")</code> on use.

The <code>to_tf_dataset()</code> method on <code>Dataset</code> converts a HuggingFace dataset into a <code>tf.data.Dataset</code> that can be passed directly to <code>model.fit()</code> or <code>model.predict()</code>. It supports batching, shuffling, custom collation, label column separation, prefetching, and multi-worker loading. A runtime check detects TPU strategies and emits a warning that the generator-based loading approach is not compatible with remote TPU connections.

== Usage ==

Set the dataset format to TensorFlow tensors:

<pre>
from datasets import load_dataset

dataset = load_dataset("glue", "mrpc", split="train")
dataset.set_format(type="tensorflow", columns=["input_ids", "attention_mask", "label"])
</pre>

Convert directly to a <code>tf.data.Dataset</code> for Keras:

<pre>
tf_dataset = dataset.to_tf_dataset(
columns=["input_ids", "attention_mask"],
label_cols=["label"],
batch_size=16,
shuffle=True,
)
model.fit(tf_dataset, epochs=3)
</pre>

== System Requirements ==

* '''Python:''' 3.9+ (TensorFlow constraint). For Python < 3.10, TensorFlow >= 2.6.0 is required. For Python >= 3.10, TensorFlow >= 2.16.0 is required.
* '''Operating System:''' Linux or macOS. TensorFlow tests in this repository explicitly exclude Windows (<code>sys_platform != 'win32'</code>).
* '''Python upper bound:''' Python >= 3.14 is excluded from TensorFlow test dependencies.
* '''NumPy:''' TensorFlow is listed in <code>NUMPY2_INCOMPATIBLE_LIBRARIES</code>, meaning it is excluded from NumPy 2 test runs.

== Dependencies ==

{| class="wikitable"
|-
! Dependency !! Version Constraint !! Notes
|-
| <code>tensorflow</code> || <code>>=2.6.0</code> || Core extra; also accepts <code>tensorflow-cpu</code>, <code>tensorflow-gpu</code>, and other variants
|-
| <code>protobuf</code> || <code><4.0.0</code> || Required for compatibility with TensorFlow < 2.12 in test environments
|}

Install via the extras:

<pre>
pip install datasets[tensorflow]
</pre>

Or for the GPU variant:

<pre>
pip install datasets[tensorflow_gpu]
</pre>

== Credentials ==

No credentials are required for TensorFlow integration itself. Standard HuggingFace Hub authentication (token-based) is used when downloading datasets from the Hub but is independent of the TensorFlow environment.

== Quick Install ==

<pre>
pip install datasets[tensorflow]
</pre>

To verify the integration is active:

<pre>
from datasets import config
print(f"TF available: {config.TF_AVAILABLE}")
print(f"TF version: {config.TF_VERSION}")
</pre>

== Code Evidence ==

'''Environment variable and detection logic''' (from <code>src/datasets/config.py</code> lines 42, 81-114):

<pre>
USE_TF = os.environ.get("USE_TF", "AUTO").upper()

TF_VERSION = "N/A"
TF_AVAILABLE = False

if USE_TF in ENV_VARS_TRUE_AND_AUTO_VALUES and USE_TORCH not in ENV_VARS_TRUE_VALUES:
TF_AVAILABLE = importlib.util.find_spec("tensorflow") is not None
if TF_AVAILABLE:
for package in [
"tensorflow",
"tensorflow-cpu",
"tensorflow-gpu",
"tf-nightly",
"tf-nightly-cpu",
"tf-nightly-gpu",
"intel-tensorflow",
"tensorflow-rocm",
"tensorflow-macos",
]:
try:
TF_VERSION = version.parse(importlib.metadata.version(package))
except importlib.metadata.PackageNotFoundError:
continue
else:
break
else:
TF_AVAILABLE = False
if TF_AVAILABLE:
if TF_VERSION.major < 2:
logger.info(f"TensorFlow found but with version {TF_VERSION}. `datasets` requires version 2 minimum.")
TF_AVAILABLE = False
</pre>

'''Formatter registration''' (from <code>src/datasets/formatting/__init__.py</code> lines 98-104):

<pre>
if config.TF_AVAILABLE:
from .tf_formatter import TFFormatter
_register_formatter(TFFormatter, "tensorflow", aliases=["tf"])
else:
_tf_error = ValueError("Tensorflow needs to be installed to be able to return Tensorflow tensors.")
_register_unavailable_formatter(_tf_error, "tensorflow", aliases=["tf"])
</pre>

'''TPU strategy warning''' (from <code>src/datasets/arrow_dataset.py</code> lines 415-421):

<pre>
if isinstance(tf.distribute.get_strategy(), tf.distribute.TPUStrategy):
logger.warning(
"Note that to_tf_dataset() loads the data with a generator rather than a full tf.data "
"pipeline and is not compatible with remote TPU connections. If you encounter errors, please "
"try using a TPU VM or, if your data can fit in memory, loading it into memory as a dict of "
"Tensors instead of streaming with to_tf_dataset()."
)
</pre>

'''Extras in setup.py''' (from <code>setup.py</code> lines 217-220):

<pre>
"tensorflow": [
"tensorflow>=2.6.0",
],
"tensorflow_gpu": ["tensorflow>=2.6.0"],
</pre>

== Common Errors ==

{| class="wikitable"
|-
! Error !! Cause !! Resolution
|-
| <code>ValueError: Tensorflow needs to be installed to be able to return Tensorflow tensors.</code> || <code>set_format(type="tensorflow")</code> called when TensorFlow is not installed or detected || Install TensorFlow: <code>pip install tensorflow>=2.6.0</code>
|-
| <code>ImportError: Called a Tensorflow-specific function but Tensorflow is not installed.</code> || <code>to_tf_dataset()</code> called when <code>config.TF_AVAILABLE</code> is <code>False</code> || Install TensorFlow or check that <code>USE_TF</code> is not set to a false value
|-
| <code>TensorFlow found but with version {X}. datasets requires version 2 minimum.</code> || TensorFlow 1.x is installed || Upgrade to TensorFlow >= 2.6.0
|-
| TPU warning: "not compatible with remote TPU connections" || <code>to_tf_dataset()</code> used under a <code>TPUStrategy</code> || Use a TPU VM instead of a remote TPU connection, or load data into memory as a dict of tensors
|-
| TF disabled because <code>USE_TORCH</code> is set to a true value || Mutual exclusion logic in <code>config.py</code>: when <code>USE_TORCH</code> is explicitly true, TF detection is skipped || Set <code>USE_TF=1</code> explicitly to override, or unset <code>USE_TORCH</code>
|}

== Compatibility Notes ==

* '''Mutual exclusion with PyTorch:''' When <code>USE_TORCH</code> is explicitly set to a true value, TensorFlow detection is skipped entirely. Conversely, when <code>USE_TF</code> is explicitly true, PyTorch is disabled. In <code>AUTO</code> mode both can coexist.
* '''Windows:''' TensorFlow test dependencies carry the marker <code>sys_platform != 'win32'</code>, indicating that TensorFlow integration is not tested or officially supported on Windows within this project.
* '''NumPy 2:''' TensorFlow is listed in <code>NUMPY2_INCOMPATIBLE_LIBRARIES</code> and is excluded from the <code>tests_numpy2</code> extras. Environments using NumPy >= 2.0 should not expect TensorFlow compatibility.
* '''Python 3.14:''' TensorFlow test dependencies are restricted to <code>python_version < '3.14'</code>.
* '''protobuf:''' Test environments pin <code>protobuf<4.0.0</code> because protobuf 4.x breaks compatibility with TensorFlow versions prior to 2.12.

== Related Pages ==

* [[Implementation:Huggingface_Datasets_TFFormatter]] -- The <code>TFFormatter</code> class that converts Arrow tables to TensorFlow tensors
* [[Implementation:Huggingface_Datasets_Dataset_To_Tf_Dataset]] -- The <code>to_tf_dataset()</code> method for creating <code>tf.data.Dataset</code> pipelines
* [[Implementation:Huggingface_Datasets_Dataset_Set_Format]] -- The <code>set_format()</code> method used to select the TensorFlow output format

[[Category:Environments]]

Environment:Huggingface Datasets SQL Dependencies

2026-09-27T10:53:40Z

Agent: Sync from local file

{{PageInfo|type=Environment|title=Huggingface_Datasets_SQL_Dependencies}}
{| class="wikitable" style="float:right; margin-left:1em; width:300px;"
|-
! Knowledge Sources
|
* [https://github.com/huggingface/datasets HuggingFace Datasets]
|-
! Domains
| [[domain::Database]], [[domain::SQL]], [[domain::Data Import]], [[domain::Data Export]]
|-
! Last Updated
| [[last_updated::2026-02-14 19:00 GMT]]
|}

== Overview ==

=== Description ===

The '''SQL Dependencies''' environment defines the packages required to enable reading from and writing to SQL databases within the HuggingFace Datasets library. SQL support relies on '''SQLAlchemy''' as the database abstraction layer, with Python's built-in '''sqlite3''' module available as a lightweight alternative for SQLite databases. SQLAlchemy is '''not''' included in the base datasets installation and is currently listed as a test dependency.

=== Usage ===

SQL features enable the ability to:

* '''Read''' datasets from SQL databases using <code>SqlDatasetReader</code> in <code>io/sql.py</code>
* '''Write''' datasets to SQL databases using the dataset-to-SQL export functionality
* Connect to any database supported by SQLAlchemy (PostgreSQL, MySQL, SQLite, Oracle, SQL Server, etc.)

The library checks for the availability of SQLAlchemy at runtime using <code>importlib.util.find_spec("sqlalchemy")</code> and stores the result in the <code>SQLALCHEMY_AVAILABLE</code> flag defined in <code>config.py</code>.

== System Requirements ==

* '''Python''': Compatible with the Python versions supported by HuggingFace Datasets
* '''Operating System''': Linux, macOS, or Windows
* '''Database''': A running database instance accessible via a SQLAlchemy connection string, or a local SQLite file
* '''Database Drivers''': Depending on the target database, additional driver packages may be needed (e.g., <code>psycopg2</code> for PostgreSQL, <code>pymysql</code> for MySQL)

== Dependencies ==

{| class="wikitable"
|-
! Package !! Minimum Version !! Purpose !! Required By
|-
| '''sqlalchemy''' || ''(see setup.py)'' || Database abstraction, connection management, SQL query execution || <code>io/sql.py</code>
|-
| '''sqlite3''' || ''(stdlib)'' || Lightweight SQL database support (built into Python) || <code>io/sql.py</code>
|}

As defined in <code>setup.py</code>, '''sqlalchemy''' is listed in <code>TESTS_REQUIRE</code>, indicating it is used in the test suite and is an optional runtime dependency.

Depending on the target database, additional driver packages may also be required:

{| class="wikitable"
|-
! Database !! Driver Package !! Install Command
|-
| PostgreSQL || <code>psycopg2</code> or <code>psycopg2-binary</code> || <code>pip install psycopg2-binary</code>
|-
| MySQL || <code>pymysql</code> or <code>mysqlclient</code> || <code>pip install pymysql</code>
|-
| SQLite || ''(none, uses stdlib sqlite3)'' || ''No additional install needed''
|-
| SQL Server || <code>pyodbc</code> || <code>pip install pyodbc</code>
|}

== Credentials ==

Database credentials are passed via SQLAlchemy connection strings. These typically include:

* '''Username''' and '''password''' for the database
* '''Host''' and '''port''' of the database server
* '''Database name'''

Example connection string format:

<pre>
dialect+driver://username:password@host:port/database
</pre>

'''Security note:''' Connection strings containing credentials should '''not''' be committed to version control. Use environment variables or secrets management tools to handle database credentials.

== Quick Install ==

Install SQLAlchemy with pip:

<pre>
pip install sqlalchemy
</pre>

For a specific database backend, install the appropriate driver alongside SQLAlchemy:

<pre>
# PostgreSQL
pip install sqlalchemy psycopg2-binary

# MySQL
pip install sqlalchemy pymysql

# SQLite (no additional driver needed)
pip install sqlalchemy
</pre>

== Code Evidence ==

'''Runtime availability check''' in <code>config.py</code>:

<pre>
SQLALCHEMY_AVAILABLE = importlib.util.find_spec("sqlalchemy") is not None
</pre>

'''TYPE_CHECKING imports''' in <code>io/sql.py</code>:

<pre>
from typing import TYPE_CHECKING

if TYPE_CHECKING:
import sqlalchemy
import sqlite3
</pre>

This pattern indicates that <code>sqlalchemy</code> and <code>sqlite3</code> are used for type annotations and are imported at runtime only when needed, allowing the module to be loaded without these dependencies installed.

'''Test dependency''' in <code>setup.py</code>:

<pre>
TESTS_REQUIRE = [
...
"sqlalchemy",
...
]
</pre>

== Common Errors ==

{| class="wikitable"
|-
! Error Message !! Cause !! Resolution
|-
| <code>ModuleNotFoundError: No module named 'sqlalchemy'</code> || SQLAlchemy is not installed || Run <code>pip install sqlalchemy</code>
|-
| <code>sqlalchemy.exc.OperationalError: (sqlite3.OperationalError) unable to open database file</code> || SQLite database file path is incorrect or inaccessible || Verify the database file path and permissions
|-
| <code>sqlalchemy.exc.NoSuchModuleError: Can't load plugin: sqlalchemy.dialects:postgresql</code> || Database driver for the specified dialect is not installed || Install the appropriate driver (e.g., <code>pip install psycopg2-binary</code>)
|-
| <code>sqlalchemy.exc.OperationalError: could not connect to server</code> || Database server is not running or connection parameters are incorrect || Verify the database server is running and the connection string is correct
|}

== Compatibility Notes ==

* '''SQLAlchemy''' is listed in <code>TESTS_REQUIRE</code> rather than as a core or optional extra dependency, which means it is primarily validated through the test suite. Users must install it manually for SQL functionality.
* The '''sqlite3''' module is part of Python's standard library and does not require separate installation. It is always available in standard CPython distributions.
* The <code>TYPE_CHECKING</code> import pattern in <code>io/sql.py</code> means that <code>sqlalchemy</code> and <code>sqlite3</code> are lazily imported, so the SQL module can be loaded even when these packages are not installed.
* The <code>SQLALCHEMY_AVAILABLE</code> flag in <code>config.py</code> allows the library to check for SQLAlchemy availability before attempting SQL operations, enabling graceful error messages.
* SQLAlchemy 1.x and 2.x have significant API differences; consult the datasets library documentation for the supported version range.

== Related Pages ==

* [[Implementation:Huggingface_Datasets_SqlDatasetReader]] — SQL dataset reader implementation
* [[Implementation:Huggingface_Datasets_Dataset_To_Sql]] — Dataset to SQL export functionality

[[Category:Environments]]

Environment:Huggingface Datasets JAX Integration

2026-09-27T10:53:40Z

Agent: Sync from local file

{{PageInfo|type=Environment|title=Huggingface_Datasets_JAX_Integration}}
{| class="wikitable" style="float:right; margin-left:1em; width:300px;"
|-
! Knowledge Sources
|
* [https://github.com/huggingface/datasets HuggingFace Datasets]
|-
! Domains
| [[domain::Deep_Learning]], [[domain::Data_Processing]]
|-
! Last Updated
| [[last_updated::2026-02-14 19:00 GMT]]
|}

== Overview ==

JAX integration in HuggingFace Datasets enables the library to produce native <code>jax.Array</code> outputs with device placement and dtype selection that respects JAX's 64-bit precision configuration. Unlike the TensorFlow and PyTorch integrations, JAX requires two separate packages (<code>jax</code> and <code>jaxlib</code>) to both be importable, and the integration is not supported on Windows.

== Description ==

At startup the library reads the <code>USE_JAX</code> environment variable (default: <code>"AUTO"</code>). When the value is in the auto-or-true set, the detection routine checks that both <code>importlib.util.find_spec("jax")</code> and <code>importlib.util.find_spec("jaxlib")</code> return non-None values. Both packages must be present for <code>JAX_AVAILABLE</code> to be set to <code>True</code>. The JAX version is then resolved from the <code>jax</code> package metadata.

When JAX is available, the <code>JaxFormatter</code> class is registered under the format type <code>"jax"</code> with no aliases. When JAX is unavailable, a placeholder is registered that raises <code>ValueError("JAX needs to be installed to be able to return JAX arrays.")</code> on use.

The <code>JaxFormatter</code> handles several JAX-specific concerns:

* '''Device validation:''' The constructor checks whether the provided <code>device</code> argument is a <code>jaxlib.xla_client.Device</code> object. If so, it raises a <code>ValueError</code> because <code>Device</code> objects are not serializable with either <code>pickle</code> or <code>dill</code>. Users must pass the device as a string identifier instead. A global <code>DEVICE_MAPPING</code> dictionary maps string identifiers to actual device objects.

* '''Precision-aware dtype selection:''' When tensorizing integer values, the formatter checks <code>jax.config.jax_enable_x64</code>. If 64-bit mode is enabled, integers default to <code>jnp.int64</code>; otherwise they default to <code>jnp.int32</code>. Floating-point values default to <code>jnp.float32</code> regardless of the x64 setting.

* '''Device placement:''' All array creation is wrapped in a <code>jax.default_device(DEVICE_MAPPING[self.device])</code> context manager, ensuring tensors land on the intended device.

== Usage ==

Set the dataset format to JAX arrays:

<pre>
from datasets import load_dataset

dataset = load_dataset("glue", "mrpc", split="train")
dataset.set_format(type="jax", columns=["input_ids", "attention_mask", "label"])
</pre>

Specify a target device by string identifier:

<pre>
dataset.set_format(type="jax", columns=["input_ids"], device="cpu:0")
</pre>

Access formatted samples (returns <code>jax.Array</code> objects):

<pre>
sample = dataset[0]
print(type(sample["input_ids"])) # <class 'jaxlib.xla_extension.ArrayImpl'>
</pre>

== System Requirements ==

* '''Python:''' 3.9+
* '''Operating System:''' Linux or macOS only. JAX dependencies carry the marker <code>sys_platform != 'win32'</code> in both the extras and test requirements. JAX is not supported on Windows within this project.

== Dependencies ==

{| class="wikitable"
|-
! Dependency !! Version Constraint !! Notes
|-
| <code>jax</code> || <code>>=0.3.14</code> || Core JAX library; must be importable for integration to activate
|-
| <code>jaxlib</code> || <code>>=0.3.14</code> || XLA compilation backend; must also be importable alongside <code>jax</code>
|}

Install via the extras:

<pre>
pip install datasets[jax]
</pre>

== Credentials ==

No credentials are required for JAX integration itself. Standard HuggingFace Hub authentication (token-based) is used when downloading datasets from the Hub but is independent of the JAX environment.

== Quick Install ==

<pre>
pip install datasets[jax]
</pre>

To verify the integration is active:

<pre>
from datasets import config
print(f"JAX available: {config.JAX_AVAILABLE}")
print(f"JAX version: {config.JAX_VERSION}")
</pre>

== Code Evidence ==

'''Environment variable and detection logic''' (from <code>src/datasets/config.py</code> lines 44, 117-129):

<pre>
USE_JAX = os.environ.get("USE_JAX", "AUTO").upper()

JAX_VERSION = "N/A"
JAX_AVAILABLE = False

if USE_JAX in ENV_VARS_TRUE_AND_AUTO_VALUES:
JAX_AVAILABLE = importlib.util.find_spec("jax") is not None and importlib.util.find_spec("jaxlib") is not None
if JAX_AVAILABLE:
try:
JAX_VERSION = version.parse(importlib.metadata.version("jax"))
logger.info(f"JAX version {JAX_VERSION} available.")
except importlib.metadata.PackageNotFoundError:
pass
else:
logger.info("Disabling JAX because USE_JAX is set to False")
</pre>

'''Formatter registration''' (from <code>src/datasets/formatting/__init__.py</code> lines 106-112):

<pre>
if config.JAX_AVAILABLE:
from .jax_formatter import JaxFormatter
_register_formatter(JaxFormatter, "jax", aliases=[])
else:
_jax_error = ValueError("JAX needs to be installed to be able to return JAX arrays.")
_register_unavailable_formatter(_jax_error, "jax", aliases=[])
</pre>

'''Device validation in JaxFormatter constructor''' (from <code>src/datasets/formatting/jax_formatter.py</code> lines 39-64):

<pre>
class JaxFormatter(TensorFormatter[Mapping, "jax.Array", Mapping]):
def __init__(self, features=None, device=None, token_per_repo_id=None, **jnp_array_kwargs):
super().__init__(features=features, token_per_repo_id=token_per_repo_id)
import jax
from jaxlib.xla_client import Device

if isinstance(device, Device):
raise ValueError(
f"Expected {device} to be a `str` not {type(device)}, as `jaxlib.xla_extension.Device` "
"is not serializable neither with `pickle` nor with `dill`. Instead you can surround "
"the device with `str()` to get its string identifier that will be internally mapped "
"to the actual `jaxlib.xla_extension.Device`."
)
self.device = device if isinstance(device, str) else str(jax.devices()[0])
</pre>

'''Precision-aware dtype selection''' (from <code>src/datasets/formatting/jax_formatter.py</code> lines 92-102):

<pre>
default_dtype = {}

if isinstance(value, (np.number, np.ndarray)) and np.issubdtype(value.dtype, np.integer):
if jax.config.jax_enable_x64:
default_dtype = {"dtype": jnp.int64}
else:
default_dtype = {"dtype": jnp.int32}
elif isinstance(value, (np.number, np.ndarray)) and np.issubdtype(value.dtype, np.floating):
default_dtype = {"dtype": jnp.float32}
</pre>

'''Device-aware tensor creation''' (from <code>src/datasets/formatting/jax_formatter.py</code> lines 126-129):

<pre>
with jax.default_device(DEVICE_MAPPING[self.device]):
return jnp.array(value, **{**default_dtype, **self.jnp_array_kwargs})
</pre>

'''Extras in setup.py''' (from <code>setup.py</code> line 222):

<pre>
"jax": ["jax>=0.3.14", "jaxlib>=0.3.14"],
</pre>

'''Windows exclusion in test dependencies''' (from <code>setup.py</code> lines 171-172):

<pre>
"jax>=0.3.14; sys_platform != 'win32'",
"jaxlib>=0.3.14; sys_platform != 'win32'",
</pre>

== Common Errors ==

{| class="wikitable"
|-
! Error !! Cause !! Resolution
|-
| <code>ValueError: JAX needs to be installed to be able to return JAX arrays.</code> || <code>set_format(type="jax")</code> called when JAX or jaxlib is not installed || Install both packages: <code>pip install jax>=0.3.14 jaxlib>=0.3.14</code>
|-
| <code>ValueError: Expected {device} to be a `str` not {type}, as `jaxlib.xla_extension.Device` is not serializable...</code> || A <code>jaxlib.xla_extension.Device</code> object was passed directly as the <code>device</code> parameter || Wrap the device with <code>str()</code> to pass its string identifier instead of the object
|-
| Device not listed among available devices (warning, falls back to default) || The string device identifier does not match any device returned by <code>jax.devices()</code> || Use a valid device string such as <code>"cpu:0"</code> or <code>"gpu:0"</code> matching the output of <code>jax.devices()</code>
|-
| <code>Disabling JAX because USE_JAX is set to False</code> (info log) || <code>USE_JAX</code> environment variable is set to a false value (<code>0</code>, <code>OFF</code>, <code>NO</code>, <code>FALSE</code>) || Unset <code>USE_JAX</code> or set it to <code>AUTO</code> or <code>1</code>
|-
| Integer precision mismatch (int32 vs int64) || JAX defaults to 32-bit integers unless <code>jax_enable_x64</code> is enabled || Set <code>jax.config.update("jax_enable_x64", True)</code> before loading data if 64-bit integers are needed
|}

== Compatibility Notes ==

* '''Windows:''' JAX is explicitly excluded on Windows. Both the extras and test dependencies carry the <code>sys_platform != 'win32'</code> platform marker.
* '''Dual-package requirement:''' Unlike TensorFlow or PyTorch, JAX requires both <code>jax</code> and <code>jaxlib</code> to be importable. Having only one installed will result in <code>JAX_AVAILABLE = False</code>.
* '''No mutual exclusion:''' Unlike the TensorFlow/PyTorch pair, JAX detection has no mutual exclusion logic with other frameworks. JAX can be active simultaneously with PyTorch or TensorFlow.
* '''Serialization constraint:''' <code>jaxlib.xla_extension.Device</code> objects cannot be serialized with <code>pickle</code> or <code>dill</code>. The formatter uses a global <code>DEVICE_MAPPING</code> dictionary and string-based device references to work around this limitation. This design means device objects are re-resolved from strings after deserialization.
* '''64-bit precision:''' JAX's default 32-bit behavior affects dtype selection in the formatter. Code relying on 64-bit integer precision must explicitly enable <code>jax_enable_x64</code> before data loading.

== Related Pages ==

* [[Implementation:Huggingface_Datasets_JaxFormatter]] -- The <code>JaxFormatter</code> class that converts Arrow tables to JAX arrays with device placement
* [[Implementation:Huggingface_Datasets_Dataset_Set_Format]] -- The <code>set_format()</code> method used to select the JAX output format

[[Category:Environments]]

Environment:Huggingface Datasets Image Dependencies

2026-09-27T10:53:39Z

Agent: Sync from local file

{{PageInfo|type=Environment|title=Huggingface_Datasets_Image_Dependencies}}
{| class="wikitable" style="float:right; margin-left:1em; width:300px;"
|-
! Knowledge Sources
|
* [https://github.com/huggingface/datasets HuggingFace Datasets]
|-
! Domains
| [[domain::Image Processing]], [[domain::Computer Vision]], [[domain::Media Encoding]], [[domain::Media Decoding]]
|-
! Last Updated
| [[last_updated::2026-02-14 19:00 GMT]]
|}

== Overview ==

=== Description ===

The '''Image Dependencies''' environment defines the optional packages required to enable image encoding and decoding within the HuggingFace Datasets library. Image support relies on '''Pillow''' (the PIL fork), which is the standard Python library for opening, manipulating, and saving image files. Pillow is '''not''' included in the base datasets installation and must be installed separately or via the <code>[vision]</code> extra.

=== Usage ===

Image features are activated by installing the optional <code>[vision]</code> extra. This unlocks the ability to:

* '''Encode''' image data into dataset-compatible formats via <code>image.py</code>
* '''Decode''' image data from stored representations via <code>image.py</code>
* Access EXIF metadata and other image properties through PIL's API

The library checks for the availability of Pillow at runtime using <code>importlib.util.find_spec("PIL")</code> and stores the result in the <code>PIL_AVAILABLE</code> flag defined in <code>config.py</code>.

== System Requirements ==

* '''Python''': Compatible with the Python versions supported by HuggingFace Datasets
* '''Operating System''': Linux, macOS, or Windows
* '''System Libraries''': Pillow may require system-level imaging libraries (e.g., <code>libjpeg</code>, <code>libpng</code>, <code>zlib</code>) depending on the image formats used

== Dependencies ==

{| class="wikitable"
|-
! Package !! Minimum Version !! Purpose !! Required By
|-
| '''Pillow''' || 9.4.0 || Image encoding, decoding, and manipulation || <code>image.py</code>
|}

As defined in <code>setup.py</code>:

<pre>
VISION_REQUIRE = ["Pillow>=9.4.0"]
</pre>

The minimum version of '''Pillow 9.4.0''' was chosen because this is when <code>PIL.Image.ExifTags</code> was introduced, which the datasets library uses for EXIF metadata handling.

== Credentials ==

No credentials are required to install or use the image dependencies. All packages are available from public PyPI repositories.

== Quick Install ==

Install the vision extras with pip:

<pre>
pip install datasets[vision]
</pre>

Or install the dependency directly:

<pre>
pip install "Pillow>=9.4.0"
</pre>

== Code Evidence ==

'''Runtime availability check''' in <code>config.py</code>:

<pre>
PIL_AVAILABLE = importlib.util.find_spec("PIL") is not None
</pre>

'''Image encoding guard''' in <code>image.py</code>:

<pre>
# Raises an error when Pillow is not installed
"To support encoding images, please install 'Pillow'."
</pre>

'''Image decoding guard''' in <code>image.py</code>:

<pre>
# Raises an error when Pillow is not installed
"To support decoding images, please install 'Pillow'."
</pre>

'''Version requirement rationale''' in <code>setup.py</code>:

<pre>
VISION_REQUIRE = ["Pillow>=9.4.0"] # When PIL.Image.ExifTags was introduced
</pre>

== Common Errors ==

{| class="wikitable"
|-
! Error Message !! Cause !! Resolution
|-
| <code>To support encoding images, please install 'Pillow'.</code> || Pillow is not installed and image encoding was attempted || Run <code>pip install "Pillow>=9.4.0"</code>
|-
| <code>To support decoding images, please install 'Pillow'.</code> || Pillow is not installed and image decoding was attempted || Run <code>pip install "Pillow>=9.4.0"</code>
|-
| <code>ModuleNotFoundError: No module named 'PIL'</code> || Pillow package is missing from the environment || Run <code>pip install "Pillow>=9.4.0"</code>
|-
| <code>ImportError: cannot import name 'ExifTags' from 'PIL.Image'</code> || Installed Pillow version is older than 9.4.0 || Run <code>pip install --upgrade "Pillow>=9.4.0"</code>
|}

== Compatibility Notes ==

* The '''Pillow >= 9.4.0''' requirement is specifically tied to the introduction of <code>PIL.Image.ExifTags</code>. Earlier Pillow versions will not provide full functionality.
* Pillow is imported under the <code>PIL</code> namespace (the original Python Imaging Library name), which is why the availability check uses <code>find_spec("PIL")</code> rather than <code>find_spec("Pillow")</code>.
* The <code>PIL_AVAILABLE</code> flag in <code>config.py</code> allows the library to gracefully degrade when Pillow is absent, rather than failing at import time.
* Pillow supports a wide range of image formats (JPEG, PNG, TIFF, BMP, GIF, WebP, etc.), but some formats may require additional system libraries to be installed.

== Related Pages ==

* [[Implementation:Huggingface_Datasets_Image]] — Image feature type implementation

[[Category:Environments]]

Environment:Huggingface Datasets Audio Video Dependencies

2026-09-27T10:53:39Z

Agent: Sync from local file

{{PageInfo|type=Environment|title=Huggingface_Datasets_Audio_Video_Dependencies}}
{| class="wikitable" style="float:right; margin-left:1em; width:300px;"
|-
! Knowledge Sources
|
* [https://github.com/huggingface/datasets HuggingFace Datasets]
|-
! Domains
| [[domain::Audio Processing]], [[domain::Video Processing]], [[domain::Media Encoding]], [[domain::Media Decoding]]
|-
! Last Updated
| [[last_updated::2026-02-14 19:00 GMT]]
|}

== Overview ==

=== Description ===

The '''Audio/Video Dependencies''' environment defines the optional packages required to enable audio and video encoding and decoding within the HuggingFace Datasets library. Audio and video support is '''not''' included in the base installation; users must install additional dependencies to work with these media types. The primary dependency is '''torchcodec''', which provides both encoding and decoding capabilities for audio data, and decoding capabilities for video data. The '''torch''' (PyTorch) library is also required as a foundational dependency.

=== Usage ===

Audio and video features are activated by installing the optional <code>[audio]</code> extra. This unlocks the ability to:

* '''Encode''' audio data into dataset-compatible formats via <code>audio.py</code>
* '''Decode''' audio data from stored representations via <code>audio.py</code> and <code>_torchcodec.py</code>
* '''Decode''' video data from stored representations via <code>video.py</code>

The library checks for the availability of torchcodec at runtime using <code>importlib.util.find_spec("torchcodec")</code> and stores the result in the <code>TORCHCODEC_AVAILABLE</code> flag defined in <code>config.py</code>.

== System Requirements ==

* '''Python''': Compatible with the Python versions supported by HuggingFace Datasets
* '''Operating System''': Linux, macOS, or Windows (subject to PyTorch and torchcodec platform support)
* '''Hardware''': A PyTorch-compatible environment; GPU is optional but may accelerate encoding/decoding operations

== Dependencies ==

{| class="wikitable"
|-
! Package !! Minimum Version !! Purpose !! Required By
|-
| '''torchcodec''' || 0.6.0 || Audio encoding/decoding, video decoding || <code>audio.py</code>, <code>video.py</code>, <code>_torchcodec.py</code>
|-
| '''torch''' (PyTorch) || 2.8.0 || Tensor operations, backend for torchcodec || <code>_torchcodec.py</code>, <code>audio.py</code>, <code>video.py</code>
|-
| '''numpy''' || ''(transitive)'' || Array operations used by torchcodec internals || <code>_torchcodec.py</code>
|}

As defined in <code>setup.py</code>:

<pre>
AUDIO_REQUIRE = ["torchcodec>=0.6.0", "torch>=2.8.0"]
</pre>

== Credentials ==

No credentials are required to install or use the audio/video dependencies. All packages are available from public PyPI repositories.

== Quick Install ==

Install the audio/video extras with pip:

<pre>
pip install datasets[audio]
</pre>

Or install the dependencies directly:

<pre>
pip install "torchcodec>=0.6.0" "torch>=2.8.0"
</pre>

== Code Evidence ==

'''Runtime availability check''' in <code>config.py</code>:

<pre>
TORCHCODEC_AVAILABLE = importlib.util.find_spec("torchcodec") is not None
</pre>

'''Audio encoding guard''' in <code>audio.py</code>:

<pre>
# Raises an error when torchcodec is not installed
"To support encoding audio data, please install 'torchcodec'."
</pre>

'''Audio decoding guard''' in <code>audio.py</code>:

<pre>
# Raises an error when torchcodec is not installed
"To support decoding audio data, please install 'torchcodec'."
</pre>

'''Video decoding guard''' in <code>video.py</code>:

<pre>
# Raises an error when torchcodec is not installed
"To support decoding videos, please install 'torchcodec'."
</pre>

'''Direct imports''' in <code>_torchcodec.py</code>:

<pre>
from torchcodec.decoders import AudioDecoder
import numpy
import torch
</pre>

== Common Errors ==

{| class="wikitable"
|-
! Error Message !! Cause !! Resolution
|-
| <code>To support encoding audio data, please install 'torchcodec'.</code> || torchcodec is not installed and audio encoding was attempted || Run <code>pip install "torchcodec>=0.6.0" "torch>=2.8.0"</code>
|-
| <code>To support decoding audio data, please install 'torchcodec'.</code> || torchcodec is not installed and audio decoding was attempted || Run <code>pip install "torchcodec>=0.6.0" "torch>=2.8.0"</code>
|-
| <code>To support decoding videos, please install 'torchcodec'.</code> || torchcodec is not installed and video decoding was attempted || Run <code>pip install "torchcodec>=0.6.0" "torch>=2.8.0"</code>
|-
| <code>ModuleNotFoundError: No module named 'torchcodec'</code> || torchcodec package is missing from the environment || Run <code>pip install "torchcodec>=0.6.0"</code>
|-
| <code>ModuleNotFoundError: No module named 'torch'</code> || PyTorch is missing from the environment || Run <code>pip install "torch>=2.8.0"</code>
|}

== Compatibility Notes ==

* The '''torchcodec >= 0.6.0''' requirement indicates that earlier versions of torchcodec lack the APIs used by the datasets library (e.g., <code>AudioDecoder</code>).
* The '''torch >= 2.8.0''' requirement ensures compatibility with torchcodec 0.6.0 and above.
* The <code>TORCHCODEC_AVAILABLE</code> flag in <code>config.py</code> allows the library to gracefully degrade when these optional dependencies are absent, rather than failing at import time.
* Audio and video features share the same dependency set, so installing for one automatically enables the other.

== Related Pages ==

* [[Implementation:Huggingface_Datasets_Audio]] — Audio feature type implementation
* [[Implementation:Huggingface_Datasets_Video]] — Video feature type implementation

[[Category:Environments]]

Environment:Googleapis Python genai Vertex AI Service Account

2026-09-27T10:53:38Z

Agent: Sync from local file

{{PageInfo|type=Environment|title=Googleapis_Python_genai_Vertex_AI_Service_Account}}
{| class="wikitable" style="float:right; margin-left:1em; width:300px;"
|-
! Knowledge Sources
|
* [https://github.com/googleapis/python-genai googleapis/python-genai]
* [https://cloud.google.com/vertex-ai/docs Vertex AI Documentation]
|-
! Domains
| [[domain::Authentication]], [[domain::Infrastructure]], [[domain::Google_Cloud]]
|-
! Last Updated
| [[last_updated::2026-02-15 14:00 GMT]]
|}

== Overview ==

Google Cloud service account / Application Default Credentials (ADC) environment for Vertex AI API access, configured via `GOOGLE_GENAI_USE_VERTEXAI`, `GOOGLE_CLOUD_PROJECT`, and `GOOGLE_CLOUD_LOCATION`.

=== Description ===

This environment configures authentication for the '''Vertex AI API''' path. When `vertexai=True` or the `GOOGLE_GENAI_USE_VERTEXAI` environment variable is set, the SDK uses Google Cloud Application Default Credentials (ADC) with the `cloud-platform` OAuth scope. The base URL becomes `https://{location}-aiplatform.googleapis.com/` with API version `v1beta1`.

The SDK automatically loads credentials via `google.auth.default()` and manages token refresh using a thread-safe lock mechanism. Credentials are refreshed before each request if they have expired.

=== Usage ===

Use this environment when accessing Gemini models through '''Vertex AI''' in Google Cloud. This is required for enterprise features, VPC Service Controls, private endpoints, and when billing through a Google Cloud project.

== System Requirements ==

{| class="wikitable"
! Category !! Requirement !! Notes
|-
| Network || HTTPS to `{location}-aiplatform.googleapis.com` || Location-specific endpoint
|-
| Authentication || Google Cloud service account or ADC || Application Default Credentials
|-
| Google Cloud || Active GCP project with Vertex AI API enabled || Billing must be configured
|}

== Dependencies ==

No additional dependencies beyond the base SDK runtime ([[Environment:Googleapis_Python_genai_Python_3_10_SDK_Runtime]]). The `google-auth` package (already a core dependency) handles credential loading.

== Credentials ==

The following environment variables configure Vertex AI authentication:

* `GOOGLE_GENAI_USE_VERTEXAI`: Set to `true` or `1` to enable Vertex AI mode.
* `GOOGLE_CLOUD_PROJECT`: Google Cloud project ID. Auto-detected from ADC if not set.
* `GOOGLE_CLOUD_LOCATION`: Google Cloud region (e.g., `us-central1`). Required for Vertex AI.
* `GOOGLE_VERTEX_BASE_URL`: (Optional) Custom Vertex AI base URL for private endpoints.
* `SSL_CERT_FILE`: (Optional) Path to custom CA certificate file. Defaults to certifi bundle.
* `SSL_CERT_DIR`: (Optional) Directory containing CA certificates.

'''Credential sources''' (in order of precedence):
# Explicitly passed `credentials` parameter
# Application Default Credentials via `google.auth.default()`

'''OAuth Scope:''' `https://www.googleapis.com/auth/cloud-platform`

== Quick Install ==

<syntaxhighlight lang="bash">
# Set up Vertex AI mode
export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT='my-project-id'
export GOOGLE_CLOUD_LOCATION='us-central1'

# Authenticate with Google Cloud
gcloud auth application-default login

# Install the SDK
pip install google-genai
</syntaxhighlight>

== Code Evidence ==

Vertex AI mode detection from `_api_client.py:559-564`:
<syntaxhighlight lang="python">
if self.vertexai is None:
if os.environ.get('GOOGLE_GENAI_USE_VERTEXAI', '0').lower() in [
'true',
'1',
]:
self.vertexai = True
</syntaxhighlight>

Project and location from environment in `_api_client.py:597-602`:
<syntaxhighlight lang="python">
env_project = os.environ.get('GOOGLE_CLOUD_PROJECT', None)
env_location = os.environ.get('GOOGLE_CLOUD_LOCATION', None)
env_api_key = get_env_api_key()
self.project = project or env_project
self.location = location or env_location
self.api_key = api_key or env_api_key
</syntaxhighlight>

ADC credential loading from `_api_client.py:182-203`:
<syntaxhighlight lang="python">
def load_auth(*, project: Union[str, None]) -> Tuple[Credentials, str]:
os.environ['GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES'] = 'false'
credentials, loaded_project_id = google.auth.default(
scopes=['https://www.googleapis.com/auth/cloud-platform'],
)
if not project:
project = loaded_project_id
if not project:
raise ValueError(
'Could not resolve project using application default credentials.'
)
return credentials, project
</syntaxhighlight>

Precedence logic for Vertex AI mode from `_api_client.py:615-644`:
<syntaxhighlight lang="python">
if self.vertexai:
if credentials and env_api_key:
# Explicit credentials take precedence over implicit api_key.
self.api_key = None
elif (env_location or env_project) and api_key:
# Explicit api_key takes precedence over implicit project/location.
self.project = None
self.location = None
elif (project or location) and env_api_key:
# Explicit project/location takes precedence over implicit api_key.
self.api_key = None
elif (env_location or env_project) and env_api_key:
# Implicit project/location takes precedence over implicit api_key.
self.api_key = None
</syntaxhighlight>

SSL configuration from `_api_client.py:834-835`:
<syntaxhighlight lang="python">
cafile=os.environ.get('SSL_CERT_FILE', certifi.where())
capath=os.environ.get('SSL_CERT_DIR')
</syntaxhighlight>

== Common Errors ==

{| class="wikitable"
|-
! Error Message !! Cause !! Solution
|-
|| `ValueError: Could not resolve project using application default credentials.` || No project ID found via ADC or env var || Set `GOOGLE_CLOUD_PROJECT` or pass `project=` parameter
|-
|| `ValueError: Project/location and API key are mutually exclusive` || Both API key and project/location provided || Use one authentication mode
|-
|| `google.auth.exceptions.DefaultCredentialsError` || No ADC configured || Run `gcloud auth application-default login`
|-
|| `PermissionDenied` (403) || Vertex AI API not enabled or missing IAM roles || Enable Vertex AI API; grant `roles/aiplatform.user`
|}

== Compatibility Notes ==

* '''Vertex AI Express Mode:''' API keys can be used with Vertex AI (bypassing ADC), but project/location takes precedence when both are available from environment.
* '''Token Sharing:''' The SDK internally sets `GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES=false` to disable bound token sharing.
* '''Thread Safety:''' Credential refresh is protected by `threading.Lock` (sync) and `asyncio.Lock` (async) for concurrent access.
* '''Custom Endpoints:''' Use `GOOGLE_VERTEX_BASE_URL` for private or regional endpoints.
* '''Live API:''' Vertex AI Live API uses bearer token authentication over WebSocket, with automatic credential refresh if the token has expired.

== Related Pages ==

* [[required_by::Implementation:Googleapis_Python_genai_Client_Init]]

[[Category:Environments]]

Environment:Googleapis Python genai Python 3 10 SDK Runtime

2026-09-27T10:53:38Z

Agent: Sync from local file

{{PageInfo|type=Environment|title=Googleapis_Python_genai_Python_3_10_SDK_Runtime}}
{| class="wikitable" style="float:right; margin-left:1em; width:300px;"
|-
! Knowledge Sources
|
* [https://github.com/googleapis/python-genai googleapis/python-genai]
* [https://pypi.org/project/google-genai/ PyPI google-genai]
|-
! Domains
| [[domain::Infrastructure]], [[domain::SDK_Runtime]]
|-
! Last Updated
| [[last_updated::2026-02-15 14:00 GMT]]
|}

== Overview ==

Python 3.10+ runtime environment with core dependencies (httpx, pydantic, google-auth, websockets, aiohttp) required to run the Google GenAI SDK v1.63.0.

=== Description ===

This environment defines the base Python runtime and package dependencies needed to use the '''google-genai''' SDK. The SDK requires Python 3.10 or higher due to use of '''types.UnionType''' (PEP 604) and other 3.10+ features in the automatic function calling utilities and type system. The SDK supports Python 3.10 through 3.14 as declared in its classifiers.

Core dependencies include '''httpx''' for HTTP transport, '''pydantic''' v2 for data modeling, '''google-auth''' for authentication, '''websockets''' for the Live API, '''aiohttp''' for async HTTP, and '''tenacity''' for retry logic.

=== Usage ===

This environment is required for '''all''' workflows in the Google GenAI SDK. Every operation — from text generation to fine-tuning to Live API streaming — requires these base dependencies to be installed.

== System Requirements ==

{| class="wikitable"
! Category !! Requirement !! Notes
|-
| OS || Any (OS Independent) || Classified as OS Independent in pyproject.toml
|-
| Python || >= 3.10 || Supports 3.10, 3.11, 3.12, 3.13, 3.14
|-
| Network || Internet access || Required for API calls to Google endpoints
|-
| Disk || Minimal || SDK itself is lightweight; no large model files
|}

== Dependencies ==

=== System Packages ===

No OS-level system packages are required beyond a standard Python installation.

=== Python Packages (Core) ===

* `google-genai` >= 1.63.0
* `anyio` >= 4.8.0, < 5.0.0
* `google-auth[requests]` >= 2.47.0, < 3.0.0
* `httpx` >= 0.28.1, < 1.0.0
* `pydantic` >= 2.9.0, < 3.0.0
* `requests` >= 2.28.1, < 3.0.0
* `tenacity` >= 8.2.3, < 9.2.0
* `websockets` >= 13.0.0, < 15.1.0
* `typing-extensions` >= 4.11.0, < 5.0.0
* `distro` >= 1.7.0, < 2
* `sniffio`
* `aiohttp` >= 3.10.11

=== Python Packages (Optional) ===

* `pillow` — Required for '''Image''' display/save via `Image.show()` and PIL-based content parts
* `mcp` >= 1.14.0 — Required for Model Context Protocol tool integration (Python > 3.9)
* `sentencepiece` >= 0.2.0 — Required for local token counting
* `protobuf` — Required alongside sentencepiece for local tokenizer

== Credentials ==

No credentials are required at the environment level. Authentication credentials (API keys, service accounts) are configured at the '''Client''' initialization level — see the [[Environment:Googleapis_Python_genai_Gemini_API_Key_Authentication]] and [[Environment:Googleapis_Python_genai_Vertex_AI_Service_Account]] environment pages.

== Quick Install ==

<syntaxhighlight lang="bash">
# Install the SDK with all core dependencies
pip install google-genai>=1.63.0

# For optional features:
# Local tokenizer support
pip install google-genai[local-tokenizer]

# MCP tool integration (Python 3.10+)
pip install mcp>=1.14.0

# PIL image support
pip install pillow
</syntaxhighlight>

== Code Evidence ==

Python 3.10+ requirement from `_automatic_function_calling_util.py:28`:
<syntaxhighlight lang="python">
if sys.version_info >= (3, 10):
import types as builtin_types
</syntaxhighlight>

Same pattern in `_extra_utils.py:37`:
<syntaxhighlight lang="python">
if sys.version_info >= (3, 10):
import types as builtin_types
</syntaxhighlight>

Optional PIL import from `types.py:60-65`:
<syntaxhighlight lang="python">
try:
import PIL.Image
PIL_Image = PIL.Image.Image
_is_pillow_image_imported = True
except ImportError:
PIL_Image = None
</syntaxhighlight>

Optional MCP import from `_mcp_utils.py:31-36`:
<syntaxhighlight lang="python">
try:
from mcp.types import Tool as McpTool
from mcp import ClientSession as McpClientSession
except ImportError:
McpTool = None
McpClientSession = None
</syntaxhighlight>

Dependency declaration from `pyproject.toml:10`:
<syntaxhighlight lang="toml">
requires-python = ">=3.10"
</syntaxhighlight>

== Common Errors ==

{| class="wikitable"
|-
! Error Message !! Cause !! Solution
|-
|| `SyntaxError: X | Y` || Python < 3.10 used with union type syntax || Upgrade to Python 3.10+
|-
|| `ImportError: No module named 'PIL'` || Pillow not installed, used `Image.show()` || `pip install pillow`
|-
|| `ImportError: No module named 'mcp'` || MCP package not installed || `pip install mcp>=1.14.0`
|-
|| `ImportError: No module named 'sentencepiece'` || Local tokenizer optional dep missing || `pip install google-genai[local-tokenizer]`
|-
|| `ValidationError` from pydantic || pydantic v1 installed instead of v2 || `pip install pydantic>=2.9.0`
|}

== Compatibility Notes ==

* '''Python 3.10+:''' Required minimum. The SDK uses `types.UnionType` (PEP 604) and other 3.10+ features.
* '''Python 3.12+:''' Additional typing features are leveraged via `typing.override` when available.
* '''MCP Integration:''' Requires Python > 3.9 (declared in requirements.txt conditional).
* '''Websockets Compatibility:''' The SDK handles both old (`websockets.client`) and new (`websockets.asyncio.client`) import paths for websockets version compatibility.
* '''Pydantic v2 Only:''' The SDK requires pydantic >= 2.9.0; pydantic v1 is not supported.
* '''aiohttp:''' Async interactions client falls back to httpx if aiohttp is used, with a warning.

== Related Pages ==

* [[required_by::Implementation:Googleapis_Python_genai_Client_Init]]
* [[required_by::Implementation:Googleapis_Python_genai_Models_Generate_Content]]
* [[required_by::Implementation:Googleapis_Python_genai_Chat_Send_Message]]
* [[required_by::Implementation:Googleapis_Python_genai_Files_Upload]]
* [[required_by::Implementation:Googleapis_Python_genai_Tunings_Tune]]
* [[required_by::Implementation:Googleapis_Python_genai_Caches_Create]]
* [[required_by::Implementation:Googleapis_Python_genai_Models_Generate_Images]]

[[Category:Environments]]

Environment:Googleapis Python genai Gemini API Key Authentication

2026-09-27T10:53:37Z

Agent: Sync from local file

{{PageInfo|type=Environment|title=Googleapis_Python_genai_Gemini_API_Key_Authentication}}
{| class="wikitable" style="float:right; margin-left:1em; width:300px;"
|-
! Knowledge Sources
|
* [https://github.com/googleapis/python-genai googleapis/python-genai]
* [https://aistudio.google.com/ Google AI Studio]
|-
! Domains
| [[domain::Authentication]], [[domain::Infrastructure]]
|-
! Last Updated
| [[last_updated::2026-02-15 14:00 GMT]]
|}

== Overview ==

API key-based authentication environment for the Gemini Developer API, using `GOOGLE_API_KEY` or `GEMINI_API_KEY` environment variables.

=== Description ===

This environment configures authentication for the '''Gemini Developer API''' (non-Vertex AI) path. The SDK reads API keys from environment variables with a defined precedence order: `GOOGLE_API_KEY` takes priority over `GEMINI_API_KEY`. If both are set, a warning is logged and `GOOGLE_API_KEY` is used.

The API key is passed as the `x-goog-api-key` HTTP header on every request. The base URL for this mode is `https://generativelanguage.googleapis.com/` with API version `v1beta`.

=== Usage ===

Use this environment for '''Gemini Developer API''' access. This is the simplest authentication mode — obtain an API key from Google AI Studio and set it as an environment variable or pass it directly to the Client constructor.

This is '''mutually exclusive''' with the Vertex AI Service Account environment. You cannot provide both an API key and project/location or credentials simultaneously.

== System Requirements ==

{| class="wikitable"
! Category !! Requirement !! Notes
|-
| Network || HTTPS to `generativelanguage.googleapis.com` || Default Gemini API endpoint
|-
| Authentication || Google API Key || Obtainable from Google AI Studio
|}

== Dependencies ==

No additional dependencies beyond the base SDK runtime ([[Environment:Googleapis_Python_genai_Python_3_10_SDK_Runtime]]).

== Credentials ==

The following environment variables configure API key authentication:

* `GOOGLE_API_KEY`: '''Primary''' API key for Google Gemini Developer API. Takes precedence if both keys are set.
* `GEMINI_API_KEY`: '''Fallback''' API key. Used only if `GOOGLE_API_KEY` is not set.

'''Alternatively''', pass the API key directly:
<syntaxhighlight lang="python">
client = genai.Client(api_key='your-api-key')
</syntaxhighlight>

== Quick Install ==

<syntaxhighlight lang="bash">
# Set the API key environment variable
export GOOGLE_API_KEY='your-api-key-here'

# Install the SDK
pip install google-genai
</syntaxhighlight>

== Code Evidence ==

API key retrieval with precedence logic from `_api_client.py:95-109`:
<syntaxhighlight lang="python">
def get_env_api_key() -> Optional[str]:
env_google_api_key = os.environ.get('GOOGLE_API_KEY', None)
env_gemini_api_key = os.environ.get('GEMINI_API_KEY', None)
if env_google_api_key and env_gemini_api_key:
logger.warning(
'Both GOOGLE_API_KEY and GEMINI_API_KEY are set. Using GOOGLE_API_KEY.'
)
return env_google_api_key or env_gemini_api_key or None
</syntaxhighlight>

Mutual exclusivity validation from `_api_client.py:567-578`:
<syntaxhighlight lang="python">
if (project or location) and api_key:
raise ValueError(
'Project/location and API key are mutually exclusive in the client'
' initializer.'
)
elif credentials and api_key:
raise ValueError(
'Credentials and API key are mutually exclusive in the client'
' initializer.'
)
</syntaxhighlight>

Ephemeral token restriction from `_api_client.py:1147-1150`:
<syntaxhighlight lang="python">
if self.api_key and self.api_key.startswith('auth_tokens/'):
raise EphemeralTokenAPIKeyError(
'Ephemeral tokens can only be used with the live API.'
)
</syntaxhighlight>

== Common Errors ==

{| class="wikitable"
|-
! Error Message !! Cause !! Solution
|-
|| `ValueError: Project/location and API key are mutually exclusive` || Both `api_key` and `project`/`location` provided || Use only one authentication mode
|-
|| `ValueError: Credentials and API key are mutually exclusive` || Both `credentials` and `api_key` provided || Use only one authentication mode
|-
|| `EphemeralTokenAPIKeyError: Ephemeral tokens can only be used with the live API` || Used `auth_tokens/` key with non-Live API || Ephemeral tokens only work with `client.aio.live`
|-
|| `Both GOOGLE_API_KEY and GEMINI_API_KEY are set` (warning) || Both env vars configured || Remove one; `GOOGLE_API_KEY` takes precedence
|-
|| `ClientError` with 401/403 || Invalid or expired API key || Regenerate key from Google AI Studio
|}

== Compatibility Notes ==

* '''Precedence:''' `GOOGLE_API_KEY` > `GEMINI_API_KEY` > None.
* '''Ephemeral Tokens:''' API keys starting with `auth_tokens/` are restricted to the Live API only and require `api_version='v1alpha'`.
* '''Explicit vs Implicit:''' Explicitly passed `api_key` parameter always overrides environment variables.
* '''Vertex AI Express:''' API keys can also be used with Vertex AI (when `vertexai=True`), but explicit project/location takes precedence over implicit API key in that mode.

== Related Pages ==

* [[required_by::Implementation:Googleapis_Python_genai_Client_Init]]

[[Category:Environments]]

Implementation:Zai org CogVideo SAT Read From CLI File

2026-09-27T10:53:36Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Zai_org_CogVideo_SAT_Read_From_CLI_File}}
{{PageInfo|type=Implementation|title=Zai_org_CogVideo_SAT_Read_From_CLI_File}}
{| class="wikitable" style="float:right; margin-left:1em; width:300px;"
|-
! Attribute !! Value
|-
| '''Implementation Name''' || SAT Read From CLI File
|-
| '''Workflow''' || SAT Video Generation
|-
| '''Step''' || 3 of 5
|-
| '''Type''' || API Doc
|-
| '''Source File''' || <code>sat/sample_video.py:L23-41</code>
|-
| '''Repository''' || [https://github.com/zai-org/CogVideo zai-org/CogVideo]
|-
| '''Last Updated''' || 2026-02-10 00:00 GMT
|}

== Overview ==

Implementation of two prompt input functions for the SAT video generation pipeline: <code>read_from_cli</code> for interactive single-prompt input and <code>read_from_file</code> for batch file-based input with distributed worker sharding.

=== Description ===

The module provides two generator functions:

* '''<code>read_from_cli()</code>''': Uses Python's built-in <code>input()</code> to interactively collect prompts from the user. Yields <code>(text, count)</code> tuples with an incrementing counter.
* '''<code>read_from_file(p, rank, world_size)</code>''': Reads lines from a text file and yields prompts assigned to the current worker based on modular distribution. Line index <code>i</code> is processed by worker <code>i mod world_size == rank</code>.

Both functions return Python generators that yield <code>(text, count)</code> tuples, enabling lazy evaluation and memory-efficient processing of large prompt files.

=== Usage ===

<syntaxhighlight lang="python">
# Interactive mode
for text, count in read_from_cli():
generate_video(text, count)

# Batch mode (distributed)
for text, count in read_from_file("prompts.txt", rank=0, world_size=4):
generate_video(text, count)
</syntaxhighlight>

== Code Reference ==

=== Source Location ===

{| class="wikitable"
|-
! File !! Lines !! Description
|-
| <code>sat/sample_video.py</code> || L23-41 || <code>read_from_cli</code> and <code>read_from_file</code> functions
|}

=== Signature ===

<syntaxhighlight lang="python">
def read_from_cli() -> Generator[Tuple[str, int], None, None]:
"""Interactive prompt input. Yields (text, count) tuples."""

def read_from_file(p: str, rank: int = 0, world_size: int = 1) -> Generator[Tuple[str, int], None, None]:
"""File-based prompt input with distributed sharding."""
</syntaxhighlight>

=== Import ===

<syntaxhighlight lang="python">
from sample_video import read_from_cli, read_from_file
</syntaxhighlight>

== I/O Contract ==

=== Inputs ===

'''<code>read_from_cli</code>'''

{| class="wikitable" style="width:100%;"
|-
! Parameter !! Type !! Default !! Description
|-
| ''(none)'' || -- || -- || Reads from standard input interactively
|}

'''<code>read_from_file</code>'''

{| class="wikitable" style="width:100%;"
|-
! Parameter !! Type !! Default !! Description
|-
| <code>p</code> || <code>str</code> || Required || Path to the prompt text file
|-
| <code>rank</code> || <code>int</code> || <code>0</code> || Current worker rank for distributed sharding
|-
| <code>world_size</code> || <code>int</code> || <code>1</code> || Total number of workers for distributed sharding
|}

=== Outputs ===

{| class="wikitable" style="width:100%;"
|-
! Output !! Type !! Description
|-
| Yielded tuples || <code>Generator[Tuple[str, int], None, None]</code> || Each yield produces <code>(text, count)</code> where <code>text</code> is the prompt string and <code>count</code> is the sequential index
|}

== Usage Examples ==

'''Example 1: Interactive CLI input'''

<syntaxhighlight lang="python">
from sample_video import read_from_cli

for text, count in read_from_cli():
print(f"Generating video {count} for prompt: {text}")
# User types: "A cat playing piano"
# Yields: ("A cat playing piano", 0)
</syntaxhighlight>

'''Example 2: File-based batch input'''

<syntaxhighlight lang="python">
from sample_video import read_from_file

# prompts.txt contains one prompt per line
for text, count in read_from_file("prompts.txt"):
print(f"Generating video {count} for prompt: {text}")
</syntaxhighlight>

'''Example 3: Distributed file input (4 GPUs)'''

<syntaxhighlight lang="python">
from sample_video import read_from_file

# Worker 0 of 4 processes lines 0, 4, 8, ...
for text, count in read_from_file("prompts.txt", rank=0, world_size=4):
generate_video(text, count)
</syntaxhighlight>

'''Example 4: Image-to-video prompt format'''

<syntaxhighlight lang="python">
# In prompts.txt for I2V:
# A cat playing piano@@/data/images/cat.jpg
# The "@@" separator splits text and image path
</syntaxhighlight>

== Related Pages ==

* [[implements::Principle:Zai_org_CogVideo_SAT_Prompt_Input]] -- Principle governing prompt input modes
* [[requires_env::Environment:Zai_org_CogVideo_SAT_Framework_Environment]]
* [[Implementation:Zai_org_CogVideo_SAT_Get_Model_Load_Checkpoint]] -- Previous step: model loading
* [[Implementation:Zai_org_CogVideo_SAT_Diffusion_Sample]] -- Next step: sampling with the prompt text
* [[Implementation:Zai_org_CogVideo_SAT_Inference_Get_Args]] -- Configuration that selects CLI vs file mode

[[Category:Implementations]]

[[Category:Implementations]]

Implementation:Zai org CogVideo SAT Inference Get Args

2026-09-27T10:53:36Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Zai_org_CogVideo_SAT_Inference_Get_Args}}
{{PageInfo|type=Implementation|title=Zai_org_CogVideo_SAT_Inference_Get_Args}}
{| class="wikitable" style="float:right; margin-left:1em; width:300px;"
|-
! Attribute !! Value
|-
| '''Implementation Name''' || SAT Inference Get Args
|-
| '''Workflow''' || SAT Video Generation
|-
| '''Step''' || 1 of 5
|-
| '''Type''' || API Doc
|-
| '''Source File''' || <code>sat/sample_video.py:L285-301</code>, <code>sat/arguments.py:L58-185</code>
|-
| '''Repository''' || [https://github.com/zai-org/CogVideo zai-org/CogVideo]
|-
| '''Last Updated''' || 2026-02-10 00:00 GMT
|}

== Overview ==

Implementation of the argument parsing system for SAT-based CogVideoX inference. The <code>get_args</code> function extends SAT's base argument parser with inference-specific parameters for controlling video generation resolution, frame count, FPS, prompt input method, and image-to-video mode.

=== Description ===

The <code>get_args</code> function builds an argument parser that combines:

# SAT framework's base arguments (model architecture, distributed settings, checkpoint path)
# YAML configuration loading via <code>--base</code>
# Inference-specific arguments added by the sample_video module

The function returns a fully populated <code>argparse.Namespace</code> object that is passed to all subsequent pipeline stages including model loading, prompt reading, and sampling.

=== Usage ===

<syntaxhighlight lang="python">
from arguments import get_args

# Parse from sys.argv
args = get_args()

# Or parse from explicit list
args = get_args(["--base", "configs/cogvideox_2b.yaml",
"--sampling-image-size", "768", "1360",
"--sampling-num-frames", "32"])
</syntaxhighlight>

== Code Reference ==

=== Source Location ===

{| class="wikitable"
|-
! File !! Lines !! Description
|-
| <code>sat/sample_video.py</code> || L285-301 || Inference argument additions
|-
| <code>sat/arguments.py</code> || L58-185 || Base SAT argument parser
|}

=== Signature ===

<syntaxhighlight lang="python">
def get_args(args_list=None) -> argparse.Namespace:
# Key inference-specific params:
# --base: YAML config files
# --input-type: "cli" or "txt"
# --input-file: prompt file path
# --sampling-image-size: [768, 1360]
# --sampling-num-frames: 32
# --sampling-fps: 8
# --image2video: bool flag
</syntaxhighlight>

=== Import ===

<syntaxhighlight lang="python">
from arguments import get_args
</syntaxhighlight>

== I/O Contract ==

=== Inputs ===

{| class="wikitable" style="width:100%;"
|-
! Parameter !! Type !! Default !! Description
|-
| <code>args_list</code> || <code>Optional[List[str]]</code> || <code>None</code> (uses sys.argv) || Explicit argument list for testing
|-
| <code>--base</code> || <code>List[str]</code> || Required || YAML config file paths
|-
| <code>--input-type</code> || <code>str</code> || <code>"cli"</code> || Prompt input method: <code>"cli"</code> or <code>"txt"</code>
|-
| <code>--input-file</code> || <code>str</code> || <code>None</code> || Path to prompt text file (required if input-type is <code>"txt"</code>)
|-
| <code>--sampling-image-size</code> || <code>List[int]</code> || <code>[768, 1360]</code> || Output video resolution [height, width]
|-
| <code>--sampling-num-frames</code> || <code>int</code> || <code>32</code> || Number of frames to generate
|-
| <code>--sampling-fps</code> || <code>int</code> || <code>8</code> || Frames per second of output video
|-
| <code>--image2video</code> || <code>bool</code> || <code>False</code> || Enable image-to-video generation mode
|}

=== Outputs ===

{| class="wikitable" style="width:100%;"
|-
! Output !! Type !! Description
|-
| Return value || <code>argparse.Namespace</code> || Fully populated argument namespace combining YAML config and CLI overrides
|}

== Usage Examples ==

'''Example 1: Text-to-video generation'''

<syntaxhighlight lang="bash">
python sat/sample_video.py \
--base configs/cogvideox_2b.yaml \
--sampling-image-size 768 1360 \
--sampling-num-frames 32 \
--sampling-fps 8 \
--input-type cli
</syntaxhighlight>

'''Example 2: Batch generation from file'''

<syntaxhighlight lang="bash">
python sat/sample_video.py \
--base configs/cogvideox_5b.yaml \
--sampling-image-size 480 720 \
--sampling-num-frames 48 \
--input-type txt \
--input-file prompts.txt
</syntaxhighlight>

'''Example 3: Image-to-video generation'''

<syntaxhighlight lang="bash">
python sat/sample_video.py \
--base configs/cogvideox_5b_i2v.yaml \
--sampling-image-size 480 720 \
--sampling-num-frames 48 \
--input-type cli \
--image2video
</syntaxhighlight>

== Related Pages ==

* [[implements::Principle:Zai_org_CogVideo_SAT_Inference_Configuration]] -- Principle governing inference configuration
* [[requires_env::Environment:Zai_org_CogVideo_SAT_Framework_Environment]]
* [[Implementation:Zai_org_CogVideo_SAT_Get_Model_Load_Checkpoint]] -- Next step: model loading using the parsed args
* [[Implementation:Zai_org_CogVideo_SAT_Read_From_CLI_File]] -- Prompt reading controlled by <code>--input-type</code>

[[Category:Implementations]]

[[Category:Implementations]]

Implementation:Zai org CogVideo SAT Get Model Load Checkpoint

2026-09-27T10:53:35Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Zai_org_CogVideo_SAT_Get_Model_Load_Checkpoint}}
{{PageInfo|type=Implementation|title=Zai_org_CogVideo_SAT_Get_Model_Load_Checkpoint}}
{| class="wikitable" style="float:right; margin-left:1em; width:300px;"
|-
! Attribute !! Value
|-
| '''Implementation Name''' || SAT Get Model Load Checkpoint
|-
| '''Workflow''' || SAT Video Generation
|-
| '''Step''' || 2 of 5
|-
| '''Type''' || Wrapper Doc
|-
| '''Source File''' || <code>sat/sample_video.py:L137-144</code>
|-
| '''Repository''' || [https://github.com/zai-org/CogVideo zai-org/CogVideo]
|-
| '''External Dependencies''' || sat
|-
| '''Last Updated''' || 2026-02-10 00:00 GMT
|}

== Overview ==

Implementation of model loading for SAT-based CogVideoX inference. This wrapper combines SAT framework's <code>get_model</code> and <code>load_checkpoint</code> functions to instantiate the <code>SATVideoDiffusionEngine</code> with pretrained weights and prepare it for inference.

=== Description ===

The model loading implementation consists of three sequential calls:

# <code>get_model(args, model_cls=SATVideoDiffusionEngine)</code> -- Constructs the model architecture from configuration
# <code>load_checkpoint(model, args)</code> -- Loads pretrained weights from the checkpoint path
# <code>model.eval()</code> -- Sets the model to evaluation mode

The <code>get_model</code> function reads model architecture parameters from <code>args.model_config</code> (populated from the YAML config file) and instantiates the specified model class. The <code>load_checkpoint</code> function reads weights from <code>args.load</code> and applies them to the model.

=== Usage ===

<syntaxhighlight lang="python">
from sat.model.base_model import get_model
from sat.training.model_io import load_checkpoint
from diffusion_video import SATVideoDiffusionEngine

# args is obtained from get_args()
model = get_model(args, model_cls=SATVideoDiffusionEngine)
load_checkpoint(model, args)
model.eval()

# Model is now ready for inference
with torch.no_grad():
samples = model.sample(cond, uc, batch_size=1, shape=shape)
</syntaxhighlight>

== Code Reference ==

=== Source Location ===

{| class="wikitable"
|-
! File !! Lines !! Description
|-
| <code>sat/sample_video.py</code> || L137-144 || Model loading wrapper
|}

=== Signature ===

<syntaxhighlight lang="python">
from sat.model.base_model import get_model
from sat.training.model_io import load_checkpoint

model = get_model(args, model_cls=SATVideoDiffusionEngine)
load_checkpoint(model, args)
model.eval()
</syntaxhighlight>

=== Import ===

<syntaxhighlight lang="python">
from sat.model.base_model import get_model
from sat.training.model_io import load_checkpoint
</syntaxhighlight>

== I/O Contract ==

=== Inputs ===

{| class="wikitable" style="width:100%;"
|-
! Parameter !! Type !! Default !! Description
|-
| <code>args</code> || <code>argparse.Namespace</code> || Required || Parsed arguments containing model config and checkpoint path
|-
| <code>args.model_config</code> || <code>dict</code> || From YAML || Model architecture configuration loaded from YAML
|-
| <code>args.load</code> || <code>str</code> || Required || Path to pretrained checkpoint directory
|-
| <code>model_cls</code> || <code>type</code> || <code>SATVideoDiffusionEngine</code> || Model class to instantiate
|}

=== Outputs ===

{| class="wikitable" style="width:100%;"
|-
! Output !! Type !! Description
|-
| <code>model</code> || <code>SATVideoDiffusionEngine</code> || Loaded model in eval mode, ready for inference
|}

== Usage Examples ==

'''Example 1: Standard model loading'''

<syntaxhighlight lang="python">
from arguments import get_args
from sat.model.base_model import get_model
from sat.training.model_io import load_checkpoint
from diffusion_video import SATVideoDiffusionEngine

args = get_args()
model = get_model(args, model_cls=SATVideoDiffusionEngine)
load_checkpoint(model, args)
model.eval()
</syntaxhighlight>

'''Example 2: Model loading with distributed setup'''

<syntaxhighlight lang="python">
import torch
from arguments import get_args
from sat.model.base_model import get_model
from sat.training.model_io import load_checkpoint
from diffusion_video import SATVideoDiffusionEngine

args = get_args()
model = get_model(args, model_cls=SATVideoDiffusionEngine)
load_checkpoint(model, args)
model.eval()

# Distributed inference uses SAT's built-in model parallelism
# configured via args (--model-parallel-size, etc.)
</syntaxhighlight>

== Related Pages ==

* [[implements::Principle:Zai_org_CogVideo_SAT_Model_Loading_for_Inference]] -- Principle governing model loading for inference
* [[requires_env::Environment:Zai_org_CogVideo_SAT_Framework_Environment]]
* [[Implementation:Zai_org_CogVideo_SAT_Inference_Get_Args]] -- Previous step: argument parsing that provides model config
* [[Implementation:Zai_org_CogVideo_SAT_Read_From_CLI_File]] -- Next step: reading prompts for generation
* [[Implementation:Zai_org_CogVideo_SAT_Diffusion_Sample]] -- Sampling step using the loaded model

[[Category:Implementations]]

[[Category:Implementations]]

Implementation:Zai org CogVideo SAT Diffusion Sample

2026-09-27T10:53:34Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Zai_org_CogVideo_SAT_Diffusion_Sample}}
{{PageInfo|type=Implementation|title=Zai_org_CogVideo_SAT_Diffusion_Sample}}
{| class="wikitable" style="float:right; margin-left:1em; width:300px;"
|-
! Attribute !! Value
|-
| '''Implementation Name''' || SAT Diffusion Sample
|-
| '''Workflow''' || SAT Video Generation
|-
| '''Step''' || 4 of 5
|-
| '''Type''' || API Doc
|-
| '''Source File''' || <code>sat/diffusion_video.py:L250-287</code>, <code>sat/sgm/modules/diffusionmodules/sampling.py:L25-43</code>
|-
| '''Repository''' || [https://github.com/zai-org/CogVideo zai-org/CogVideo]
|-
| '''External Dependencies''' || torch, sat.mpu, sgm.modules.diffusionmodules.sampling
|-
| '''Last Updated''' || 2026-02-10 00:00 GMT
|}

== Overview ==

Implementation of the diffusion sampling method on the <code>SATVideoDiffusionEngine</code> class. The <code>sample</code> method orchestrates the iterative denoising process using the EulerEDM sampler, classifier-free guidance, and optional image conditioning for I2V generation.

=== Description ===

The <code>sample</code> method:

# Initializes random Gaussian noise of the specified shape
# Delegates to the configured sampler (EulerEDM) via <code>BaseDiffusionSampler</code>
# The sampler iterates over the timestep schedule, calling the denoiser at each step
# Classifier-free guidance is applied by running both conditional and unconditional forward passes
# For I2V, <code>concat_images</code> are concatenated to the noise and <code>ofs</code> provides temporal offset embedding
# Returns the final denoised latent tensor

The <code>BaseDiffusionSampler</code> at <code>sgm/modules/diffusionmodules/sampling.py</code> defines the abstract sampling interface and timestep scheduling.

=== Usage ===

<syntaxhighlight lang="python">
with torch.no_grad():
samples = model.sample(
cond=conditioner_output,
uc=unconditional_output,
batch_size=1,
shape=(T, C, H // 8, W // 8),
)
</syntaxhighlight>

== Code Reference ==

=== Source Location ===

{| class="wikitable"
|-
! File !! Lines !! Description
|-
| <code>sat/diffusion_video.py</code> || L250-287 || <code>SATVideoDiffusionEngine.sample</code> method
|-
| <code>sat/sgm/modules/diffusionmodules/sampling.py</code> || L25-43 || <code>BaseDiffusionSampler</code> abstract class
|}

=== Signature ===

<syntaxhighlight lang="python">
class SATVideoDiffusionEngine:
def sample(
self,
cond: Dict,
uc: Dict = None,
batch_size: int = 1,
shape: Tuple = (T, C, H, W),
concat_images: torch.Tensor = None, # For I2V
ofs: torch.Tensor = None, # For I2V offset
) -> torch.Tensor:
"""Returns denoised latent tensor [B, T, C, H, W]"""
</syntaxhighlight>

=== Import ===

<syntaxhighlight lang="python">
from diffusion_video import SATVideoDiffusionEngine
</syntaxhighlight>

== I/O Contract ==

=== Inputs ===

{| class="wikitable" style="width:100%;"
|-
! Parameter !! Type !! Default !! Description
|-
| <code>cond</code> || <code>Dict</code> || Required || Conditioner output dict containing text embeddings (crossattn, vector, concat keys)
|-
| <code>uc</code> || <code>Dict</code> || <code>None</code> || Unconditional conditioner output for classifier-free guidance
|-
| <code>batch_size</code> || <code>int</code> || <code>1</code> || Number of samples to generate in parallel
|-
| <code>shape</code> || <code>Tuple[int, ...]</code> || Required || Latent shape <code>(T, C, H//F, W//F)</code> where <code>F=8</code>
|-
| <code>concat_images</code> || <code>torch.Tensor</code> || <code>None</code> || Image latents for I2V mode, concatenated along channel dimension
|-
| <code>ofs</code> || <code>torch.Tensor</code> || <code>None</code> || Temporal offset embedding for I2V, typically <code>[2.0]</code>
|}

=== Outputs ===

{| class="wikitable" style="width:100%;"
|-
! Output !! Type !! Description
|-
| Return value || <code>torch.Tensor</code> || Denoised latent tensor of shape <code>[B, T, C, H//F, W//F]</code>
|}

== Usage Examples ==

'''Example 1: Text-to-video sampling'''

<syntaxhighlight lang="python">
import torch
from diffusion_video import SATVideoDiffusionEngine

# Assume model is loaded and args are parsed
T = args.sampling_num_frames
H, W = args.sampling_image_size
C = 16 # Latent channels

# Encode text prompt
cond = model.conditioner(text_prompt)
uc = model.conditioner("") # Empty prompt for CFG

with torch.no_grad():
samples = model.sample(
cond=cond,
uc=uc,
batch_size=1,
shape=(T, C, H // 8, W // 8),
)
# samples shape: [1, T, C, H//8, W//8]
</syntaxhighlight>

'''Example 2: Image-to-video sampling'''

<syntaxhighlight lang="python">
import torch

# Encode source image through VAE
image_latents = model.encode_first_stage(source_image)

# Set I2V offset
ofs = torch.tensor([2.0], device="cuda")

with torch.no_grad():
samples = model.sample(
cond=cond,
uc=uc,
batch_size=1,
shape=(T, C, H // 8, W // 8),
concat_images=image_latents,
ofs=ofs,
)
</syntaxhighlight>

== Related Pages ==

* [[implements::Principle:Zai_org_CogVideo_Diffusion_Sampling]] -- Principle governing diffusion sampling with EulerEDM and CFG
* [[requires_env::Environment:Zai_org_CogVideo_SAT_Framework_Environment]]
* [[Implementation:Zai_org_CogVideo_SAT_Read_From_CLI_File]] -- Previous step: prompt input
* [[Implementation:Zai_org_CogVideo_SAT_Decode_First_Stage_Export]] -- Next step: decoding latents and exporting video
* [[Implementation:Zai_org_CogVideo_SAT_Get_Model_Load_Checkpoint]] -- Model loading that prepares the model for sampling

[[Category:Implementations]]

[[Category:Implementations]]

Implementation:Zai org CogVideo SAT Decode First Stage Export

2026-09-27T10:53:34Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Zai_org_CogVideo_SAT_Decode_First_Stage_Export}}
{{PageInfo|type=Implementation|title=Zai_org_CogVideo_SAT_Decode_First_Stage_Export}}
{| class="wikitable" style="float:right; margin-left:1em; width:300px;"
|-
! Attribute !! Value
|-
| '''Implementation Name''' || SAT Decode First Stage Export
|-
| '''Workflow''' || SAT Video Generation
|-
| '''Step''' || 5 of 5
|-
| '''Type''' || API Doc
|-
| '''Source File''' || <code>sat/diffusion_video.py:L197-229</code>, <code>sat/sample_video.py:L120-134</code>
|-
| '''Repository''' || [https://github.com/zai-org/CogVideo zai-org/CogVideo]
|-
| '''External Dependencies''' || imageio, einops, torch, numpy
|-
| '''Last Updated''' || 2026-02-10 00:00 GMT
|}

== Overview ==

Implementation of the VAE decoding and video export steps in the SAT video generation pipeline. The <code>decode_first_stage</code> method converts diffusion latents to pixel-space video, and <code>save_video_as_grid_and_mp4</code> exports the decoded frames as a playable MP4 file.

=== Description ===

Two functions work together to produce the final video output:

* '''<code>SATVideoDiffusionEngine.decode_first_stage(z)</code>''': Takes the denoised latent tensor, applies inverse scale factor, passes through the 3D VAE decoder, and returns pixel-space frames. Context-parallel decoding distributes temporal chunks across available GPUs.
* '''<code>save_video_as_grid_and_mp4(samples, save_path, fps)</code>''': Takes the decoded video tensor, rearranges dimensions using einops, clamps and normalizes values to <code>[0, 255]</code>, converts to numpy uint8, and writes to MP4 using imageio.

=== Usage ===

<syntaxhighlight lang="python">
# After sampling
with torch.no_grad():
decoded = model.decode_first_stage(samples)

save_video_as_grid_and_mp4(decoded, save_path="output/video_001.mp4", fps=8)
</syntaxhighlight>

== Code Reference ==

=== Source Location ===

{| class="wikitable"
|-
! File !! Lines !! Description
|-
| <code>sat/diffusion_video.py</code> || L197-229 || <code>decode_first_stage</code> method
|-
| <code>sat/sample_video.py</code> || L120-134 || <code>save_video_as_grid_and_mp4</code> function
|}

=== Signature ===

<syntaxhighlight lang="python">
class SATVideoDiffusionEngine:
def decode_first_stage(self, z: torch.Tensor) -> torch.Tensor:
"""Decode latents to pixel space."""

def save_video_as_grid_and_mp4(samples: torch.Tensor, save_path: str, fps: int):
"""Save decoded video tensor as MP4 using imageio."""
</syntaxhighlight>

=== Import ===

<syntaxhighlight lang="python">
from diffusion_video import SATVideoDiffusionEngine
from sample_video import save_video_as_grid_and_mp4
</syntaxhighlight>

== I/O Contract ==

=== Inputs ===

'''<code>decode_first_stage</code>'''

{| class="wikitable" style="width:100%;"
|-
! Parameter !! Type !! Default !! Description
|-
| <code>z</code> || <code>torch.Tensor</code> || Required || Denoised latent tensor of shape <code>[B, T, C, H//8, W//8]</code>
|}

'''<code>save_video_as_grid_and_mp4</code>'''

{| class="wikitable" style="width:100%;"
|-
! Parameter !! Type !! Default !! Description
|-
| <code>samples</code> || <code>torch.Tensor</code> || Required || Decoded video tensor in pixel space
|-
| <code>save_path</code> || <code>str</code> || Required || Output file path for the MP4 video
|-
| <code>fps</code> || <code>int</code> || Required || Frames per second for the output video (default 8 from args)
|}

=== Outputs ===

'''<code>decode_first_stage</code>'''

{| class="wikitable" style="width:100%;"
|-
! Output !! Type !! Description
|-
| Return value || <code>torch.Tensor</code> || Pixel-space video tensor of shape <code>[B, C, T, H, W]</code> with values in <code>[-1, 1]</code>
|}

'''<code>save_video_as_grid_and_mp4</code>'''

{| class="wikitable" style="width:100%;"
|-
! Output !! Type !! Description
|-
| Side effect || MP4 file || Video file written to <code>save_path</code>
|}

== Usage Examples ==

'''Example 1: Full decode and export pipeline'''

<syntaxhighlight lang="python">
import torch
from diffusion_video import SATVideoDiffusionEngine
from sample_video import save_video_as_grid_and_mp4

# After diffusion sampling produces denoised latents
with torch.no_grad():
decoded_video = model.decode_first_stage(samples)

# Save as MP4
save_video_as_grid_and_mp4(
samples=decoded_video,
save_path="outputs/generated_video.mp4",
fps=8
)
</syntaxhighlight>

'''Example 2: Batch export with custom FPS'''

<syntaxhighlight lang="python">
import os

output_dir = "outputs/batch_run"
os.makedirs(output_dir, exist_ok=True)

for idx, sample in enumerate(all_samples):
with torch.no_grad():
decoded = model.decode_first_stage(sample.unsqueeze(0))
save_video_as_grid_and_mp4(
decoded,
save_path=os.path.join(output_dir, f"video_{idx:04d}.mp4"),
fps=args.sampling_fps
)
</syntaxhighlight>

== Related Pages ==

* [[implements::Principle:Zai_org_CogVideo_SAT_Video_Decoding_and_Export]] -- Principle governing VAE decoding and video export
* [[requires_env::Environment:Zai_org_CogVideo_SAT_Framework_Environment]]
* [[Implementation:Zai_org_CogVideo_SAT_Diffusion_Sample]] -- Previous step: diffusion sampling that produces the latents
* [[Implementation:Zai_org_CogVideo_SAT_Inference_Get_Args]] -- Configuration providing FPS and output path parameters

[[Category:Implementations]]

[[Category:Implementations]]

Implementation:Zai org CogVideo Get Video Frames

2026-09-27T10:53:33Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Zai_org_CogVideo_Get_Video_Frames}}
{{PageInfo|type=Implementation|title=Zai_org_CogVideo_Get_Video_Frames}}
{| class="wikitable" style="float:right; margin-left:1em; width:300px;"
|-
! Attribute !! Value
|-
| '''Implementation Name''' || Get Video Frames
|-
| '''Workflow''' || Video Editing DDIM Inversion
|-
| '''Step''' || 1 of 6
|-
| '''Type''' || API Doc
|-
| '''Source File''' || <code>inference/ddim_inversion.py:L263-300</code>
|-
| '''Repository''' || [https://github.com/zai-org/CogVideo zai-org/CogVideo]
|-
| '''External Dependencies''' || decord, torchvision.transforms
|-
| '''Last Updated''' || 2026-02-10 00:00 GMT
|}

== Overview ==

Implementation of video loading, frame sampling, resizing, and normalization for the DDIM inversion pipeline. The <code>get_video_frames</code> function produces a tensor of preprocessed frames ready for VAE encoding.

=== Description ===

The <code>get_video_frames</code> function performs:

# Loads the video file using decord's <code>VideoReader</code>
# Applies start/end frame skipping
# Samples frames to the target count using uniform stepping or automatic stride calculation
# Resizes frames to the target resolution using torchvision transforms
# Normalizes pixel values from <code>[0, 255]</code> to <code>[-1, 1]</code>

The function enforces the VAE constraint that the frame count must satisfy <code>(F mod 4) == 1</code>.

=== Usage ===

<syntaxhighlight lang="python">
from inference.ddim_inversion import get_video_frames

video_frames = get_video_frames(
video_path="input_video.mp4",
width=720,
height=480,
max_num_frames=81,
)
# video_frames shape: [F, C, H, W] in [-1, 1]
</syntaxhighlight>

== Code Reference ==

=== Source Location ===

{| class="wikitable"
|-
! File !! Lines !! Description
|-
| <code>inference/ddim_inversion.py</code> || L263-300 || <code>get_video_frames</code> function
|}

=== Signature ===

<syntaxhighlight lang="python">
def get_video_frames(
video_path: str,
width: int = 720,
height: int = 480,
skip_frames_start: int = 0,
skip_frames_end: int = 0,
max_num_frames: int = 81,
frame_sample_step: Optional[int] = None,
) -> torch.FloatTensor: # [F, C, H, W] in [-1, 1]
</syntaxhighlight>

=== Import ===

<syntaxhighlight lang="python">
from inference.ddim_inversion import get_video_frames
</syntaxhighlight>

== I/O Contract ==

=== Inputs ===

{| class="wikitable" style="width:100%;"
|-
! Parameter !! Type !! Default !! Description
|-
| <code>video_path</code> || <code>str</code> || Required || Path to the input video file
|-
| <code>width</code> || <code>int</code> || <code>720</code> || Target width for resizing
|-
| <code>height</code> || <code>int</code> || <code>480</code> || Target height for resizing
|-
| <code>skip_frames_start</code> || <code>int</code> || <code>0</code> || Number of frames to skip at the beginning
|-
| <code>skip_frames_end</code> || <code>int</code> || <code>0</code> || Number of frames to skip at the end
|-
| <code>max_num_frames</code> || <code>int</code> || <code>81</code> || Maximum number of frames to sample (must satisfy <code>F mod 4 == 1</code>)
|-
| <code>frame_sample_step</code> || <code>Optional[int]</code> || <code>None</code> || Explicit frame sampling step; if None, computed automatically
|}

=== Outputs ===

{| class="wikitable" style="width:100%;"
|-
! Output !! Type !! Description
|-
| Return value || <code>torch.FloatTensor</code> || Video frames tensor of shape <code>[F, C, H, W]</code> with values in <code>[-1, 1]</code>
|}

== Usage Examples ==

'''Example 1: Default loading'''

<syntaxhighlight lang="python">
from inference.ddim_inversion import get_video_frames

frames = get_video_frames("input.mp4")
# frames.shape: [81, 3, 480, 720]
# frames.dtype: torch.float32
# frames.min() >= -1.0, frames.max() <= 1.0
</syntaxhighlight>

'''Example 2: Custom resolution and frame count'''

<syntaxhighlight lang="python">
frames = get_video_frames(
"input.mp4",
width=1360,
height=768,
max_num_frames=49,
skip_frames_start=10,
skip_frames_end=5,
)
# frames.shape: [49, 3, 768, 1360]
</syntaxhighlight>

'''Example 3: Explicit frame sampling step'''

<syntaxhighlight lang="python">
frames = get_video_frames(
"input.mp4",
frame_sample_step=3, # Take every 3rd frame
max_num_frames=25,
)
</syntaxhighlight>

== Related Pages ==

* [[implements::Principle:Zai_org_CogVideo_Video_Loading_and_Preprocessing]] -- Principle governing video loading and preprocessing
* [[requires_env::Environment:Zai_org_CogVideo_Diffusers_Inference_Environment]]
* [[Implementation:Zai_org_CogVideo_Encode_Video_Frames]] -- Next step: encoding frames to latent space
* [[Implementation:Zai_org_CogVideo_DDIM_CogVideoXPipeline_From_Pretrained]] -- Pipeline providing the VAE for subsequent encoding

[[Category:Implementations]]

[[Category:Implementations]]

Implementation:Zai org CogVideo Encode Video Frames

2026-09-27T10:53:33Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Zai_org_CogVideo_Encode_Video_Frames}}
{{PageInfo|type=Implementation|title=Zai_org_CogVideo_Encode_Video_Frames}}
{| class="wikitable" style="float:right; margin-left:1em; width:300px;"
|-
! Attribute !! Value
|-
| '''Implementation Name''' || Encode Video Frames
|-
| '''Workflow''' || Video Editing DDIM Inversion
|-
| '''Step''' || 3 of 6
|-
| '''Type''' || API Doc
|-
| '''Source File''' || <code>inference/ddim_inversion.py:L303-309</code>
|-
| '''Repository''' || [https://github.com/zai-org/CogVideo zai-org/CogVideo]
|-
| '''External Dependencies''' || diffusers (AutoencoderKLCogVideoX)
|-
| '''Last Updated''' || 2026-02-10 00:00 GMT
|}

== Overview ==

Implementation of video frame encoding using the CogVideoX 3D VAE. The <code>encode_video_frames</code> function converts preprocessed video frames from pixel space into the latent representation used by the diffusion model.

=== Description ===

The <code>encode_video_frames</code> function:

# Accepts preprocessed video frames as a <code>[F, C, H, W]</code> tensor
# Rearranges the tensor to match the VAE's expected input format
# Passes through the VAE encoder to obtain latent distribution parameters
# Samples from the distribution and applies the scaling factor
# Returns the latent tensor in <code>[B, T, C, H', W']</code> format

The function wraps the VAE's encode method and handles the scaling factor application in a single call.

=== Usage ===

<syntaxhighlight lang="python">
from inference.ddim_inversion import encode_video_frames

latents = encode_video_frames(pipe.vae, video_frames)
# latents shape: [B, T, C, H', W']
</syntaxhighlight>

== Code Reference ==

=== Source Location ===

{| class="wikitable"
|-
! File !! Lines !! Description
|-
| <code>inference/ddim_inversion.py</code> || L303-309 || <code>encode_video_frames</code> function
|}

=== Signature ===

<syntaxhighlight lang="python">
def encode_video_frames(
vae: AutoencoderKLCogVideoX,
video_frames: torch.FloatTensor # [F, C, H, W]
) -> torch.FloatTensor: # [B, T, C, H', W']
</syntaxhighlight>

=== Import ===

<syntaxhighlight lang="python">
from inference.ddim_inversion import encode_video_frames
</syntaxhighlight>

== I/O Contract ==

=== Inputs ===

{| class="wikitable" style="width:100%;"
|-
! Parameter !! Type !! Default !! Description
|-
| <code>vae</code> || <code>AutoencoderKLCogVideoX</code> || Required || The 3D VAE from the loaded CogVideoX pipeline (<code>pipe.vae</code>)
|-
| <code>video_frames</code> || <code>torch.FloatTensor</code> || Required || Preprocessed video frames of shape <code>[F, C, H, W]</code> with values in <code>[-1, 1]</code>
|}

=== Outputs ===

{| class="wikitable" style="width:100%;"
|-
! Output !! Type !! Description
|-
| Return value || <code>torch.FloatTensor</code> || Latent tensor of shape <code>[B, T, C, H', W']</code> where <code>H' = H // 8</code>, <code>W' = W // 8</code>, and <code>T</code> is the temporally compressed frame count
|}

== Usage Examples ==

'''Example 1: Basic video encoding'''

<syntaxhighlight lang="python">
from inference.ddim_inversion import get_video_frames, encode_video_frames
from diffusers import CogVideoXPipeline
import torch

pipe = CogVideoXPipeline.from_pretrained(
"THUDM/CogVideoX-5b", torch_dtype=torch.bfloat16
).to("cuda")

# Load and preprocess video
video_frames = get_video_frames("input.mp4", width=720, height=480)

# Encode to latent space
latents = encode_video_frames(pipe.vae, video_frames)
# latents.shape: [1, T, 16, 60, 90] for 480x720 input
</syntaxhighlight>

'''Example 2: Encoding as part of the inversion pipeline'''

<syntaxhighlight lang="python">
# Encode video frames
video_frames = get_video_frames(video_path, width=720, height=480, max_num_frames=49)
latents = encode_video_frames(pipe.vae, video_frames)

# latents are now ready for DDIM inversion
inverted = sample(pipe, latents, inverse_scheduler, prompt="")
</syntaxhighlight>

== Related Pages ==

* [[implements::Principle:Zai_org_CogVideo_Video_Encoding]] -- Principle governing video encoding with the 3D VAE
* [[requires_env::Environment:Zai_org_CogVideo_Diffusers_Inference_Environment]]
* [[Implementation:Zai_org_CogVideo_Get_Video_Frames]] -- Previous step: video loading and preprocessing
* [[Implementation:Zai_org_CogVideo_DDIM_Inversion_Sample]] -- Next step: DDIM inversion of the encoded latents
* [[Implementation:Zai_org_CogVideo_DDIM_Export_Latents_To_Video]] -- Decoding that inverts this encoding step

[[Category:Implementations]]

[[Category:Implementations]]

Implementation:Zai org CogVideo DDIM Inversion Sample

2026-09-27T10:53:32Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Zai_org_CogVideo_DDIM_Inversion_Sample}}
{{PageInfo|type=Implementation|title=Zai_org_CogVideo_DDIM_Inversion_Sample}}
{| class="wikitable" style="float:right; margin-left:1em; width:300px;"
|-
! Attribute !! Value
|-
| '''Implementation Name''' || DDIM Inversion Sample
|-
| '''Workflow''' || Video Editing DDIM Inversion
|-
| '''Step''' || 4 of 6
|-
| '''Type''' || API Doc
|-
| '''Source File''' || <code>inference/ddim_inversion.py:L321-452</code>, <code>inference/ddim_inversion.py:L489-498</code>
|-
| '''Repository''' || [https://github.com/zai-org/CogVideo zai-org/CogVideo]
|-
| '''External Dependencies''' || diffusers, torch
|-
| '''Last Updated''' || 2026-02-10 00:00 GMT
|}

== Overview ==

Implementation of the DDIM inversion sampling function. The <code>sample</code> function serves dual purpose: it performs both DDIM inversion (when called with the inverse scheduler and empty prompt) and forward DDIM reconstruction (when called with the forward scheduler and edit prompt). The function stores the full latent trajectory for use in attention injection.

=== Description ===

The <code>sample</code> function implements the core DDIM loop:

# Sets up the scheduler timesteps for the specified number of inference steps
# Encodes the prompt (or empty string for inversion) using the pipeline's text encoder
# Iterates over timesteps, at each step:
#* Concatenates the latent with itself for classifier-free guidance (if guidance_scale > 1)
#* Runs the transformer forward pass to predict noise
#* Applies CFG to combine conditional and unconditional predictions
#* Steps the scheduler (forward for reconstruction, inverse for inversion)
#* Stores the latent in the trajectory
# Returns the complete trajectory tensor

For inversion specifically (lines L489-498): the function is called with <code>DDIMInverseScheduler</code>, an empty prompt, and <code>reference_latents=None</code>. The trajectory is then reversed and passed as <code>reference_latents</code> to the reconstruction call.

=== Usage ===

<syntaxhighlight lang="python">
from inference.ddim_inversion import sample

# Inversion
inversion_trajectory = sample(
pipeline=pipe,
latents=encoded_latents,
scheduler=inverse_scheduler,
prompt="",
num_inference_steps=50,
)
</syntaxhighlight>

== Code Reference ==

=== Source Location ===

{| class="wikitable"
|-
! File !! Lines !! Description
|-
| <code>inference/ddim_inversion.py</code> || L321-452 || <code>sample</code> function (main DDIM loop)
|-
| <code>inference/ddim_inversion.py</code> || L489-498 || Inversion call site
|}

=== Signature ===

<syntaxhighlight lang="python">
def sample(
pipeline: CogVideoXPipeline,
latents: torch.FloatTensor,
scheduler: Union[DDIMInverseScheduler, CogVideoXDDIMScheduler],
prompt: Optional[str] = None,
num_inference_steps: int = 50,
guidance_scale: float = 6.0,
generator: Optional[torch.Generator] = None,
reference_latents: torch.FloatTensor = None,
) -> torch.FloatTensor: # trajectory [num_steps, B, T, C, H', W']
</syntaxhighlight>

=== Import ===

<syntaxhighlight lang="python">
from inference.ddim_inversion import sample
</syntaxhighlight>

== I/O Contract ==

=== Inputs ===

{| class="wikitable" style="width:100%;"
|-
! Parameter !! Type !! Default !! Description
|-
| <code>pipeline</code> || <code>CogVideoXPipeline</code> || Required || Loaded CogVideoX pipeline with transformer, text encoder, and VAE
|-
| <code>latents</code> || <code>torch.FloatTensor</code> || Required || Starting latents: encoded video for inversion, or random noise for reconstruction
|-
| <code>scheduler</code> || <code>Union[DDIMInverseScheduler, CogVideoXDDIMScheduler]</code> || Required || Inverse scheduler for inversion, forward scheduler for reconstruction
|-
| <code>prompt</code> || <code>Optional[str]</code> || <code>None</code> || Text prompt; empty string for inversion, edit prompt for reconstruction
|-
| <code>num_inference_steps</code> || <code>int</code> || <code>50</code> || Number of DDIM steps
|-
| <code>guidance_scale</code> || <code>float</code> || <code>6.0</code> || Classifier-free guidance scale
|-
| <code>generator</code> || <code>Optional[torch.Generator]</code> || <code>None</code> || Random number generator for reproducibility
|-
| <code>reference_latents</code> || <code>torch.FloatTensor</code> || <code>None</code> || Inversion trajectory for attention injection during reconstruction; None for inversion
|}

=== Outputs ===

{| class="wikitable" style="width:100%;"
|-
! Output !! Type !! Description
|-
| Return value || <code>torch.FloatTensor</code> || Latent trajectory tensor of shape <code>[num_steps, B, T, C, H', W']</code> containing latents at each timestep
|}

== Usage Examples ==

'''Example 1: DDIM inversion (finding noise representation)'''

<syntaxhighlight lang="python">
from diffusers import DDIMInverseScheduler
from inference.ddim_inversion import sample, encode_video_frames, get_video_frames

# Prepare inverse scheduler
inverse_scheduler = DDIMInverseScheduler.from_config(pipe.scheduler.config)

# Load and encode video
video_frames = get_video_frames("input.mp4")
latents = encode_video_frames(pipe.vae, video_frames)

# Run inversion
inversion_trajectory = sample(
pipeline=pipe,
latents=latents,
scheduler=inverse_scheduler,
prompt="", # Empty prompt for unconditional inversion
num_inference_steps=50,
guidance_scale=1.0, # No CFG during inversion
)
# inversion_trajectory.shape: [50, 1, T, 16, H', W']
</syntaxhighlight>

'''Example 2: Forward reconstruction (verifying inversion quality)'''

<syntaxhighlight lang="python">
from diffusers import CogVideoXDDIMScheduler

forward_scheduler = CogVideoXDDIMScheduler.from_config(pipe.scheduler.config)

# Reverse the trajectory for reconstruction
reversed_trajectory = inversion_trajectory.flip(0)

reconstruction = sample(
pipeline=pipe,
latents=inversion_trajectory[-1], # Start from noise
scheduler=forward_scheduler,
prompt="original prompt",
num_inference_steps=50,
reference_latents=reversed_trajectory,
)
</syntaxhighlight>

== Related Pages ==

* [[implements::Principle:Zai_org_CogVideo_DDIM_Inversion]] -- Principle governing DDIM inversion
* [[requires_env::Environment:Zai_org_CogVideo_Diffusers_Inference_Environment]]
* [[Implementation:Zai_org_CogVideo_Encode_Video_Frames]] -- Previous step: video encoding that produces input latents
* [[Implementation:Zai_org_CogVideo_DDIM_Attention_Injection_Reconstruction]] -- Next step: prompted reconstruction with attention injection
* [[Implementation:Zai_org_CogVideo_DDIM_Export_Latents_To_Video]] -- Export step for trajectory endpoints

[[Category:Implementations]]

[[Category:Implementations]]

Implementation:Zai org CogVideo DDIM Export Latents To Video

2026-09-27T10:53:31Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Zai_org_CogVideo_DDIM_Export_Latents_To_Video}}
{{PageInfo|type=Implementation|title=Zai_org_CogVideo_DDIM_Export_Latents_To_Video}}
{| class="wikitable" style="float:right; margin-left:1em; width:300px;"
|-
! Attribute !! Value
|-
| '''Implementation Name''' || DDIM Export Latents To Video
|-
| '''Workflow''' || Video Editing DDIM Inversion
|-
| '''Step''' || 6 of 6
|-
| '''Type''' || API Doc
|-
| '''Source File''' || <code>inference/ddim_inversion.py:L312-317</code>
|-
| '''Repository''' || [https://github.com/zai-org/CogVideo zai-org/CogVideo]
|-
| '''External Dependencies''' || diffusers (CogVideoXPipeline)
|-
| '''Last Updated''' || 2026-02-10 00:00 GMT
|}

== Overview ==

Implementation of the latent-to-video export function for the DDIM inversion pipeline. The <code>export_latents_to_video</code> function decodes latent tensors through the pipeline's VAE and saves the result as an MP4 video file.

=== Description ===

The <code>export_latents_to_video</code> function:

# Calls <code>pipeline.decode_latents(latents)</code> to convert latent-space tensors to pixel-space video
# Calls <code>pipeline.video_processor.postprocess_video(video, output_type="pil")</code> to convert to PIL format
# Exports the PIL frames as an MP4 video file at the specified FPS using <code>export_to_video</code>

This function is called twice in the typical DDIM editing workflow: once for the inversion reconstruction (to verify quality) and once for the edited reconstruction.

=== Usage ===

<syntaxhighlight lang="python">
from inference.ddim_inversion import export_latents_to_video

# Export the final trajectory step as video
export_latents_to_video(pipe, trajectory[-1], "output.mp4", fps=8)
</syntaxhighlight>

== Code Reference ==

=== Source Location ===

{| class="wikitable"
|-
! File !! Lines !! Description
|-
| <code>inference/ddim_inversion.py</code> || L312-317 || <code>export_latents_to_video</code> function
|}

=== Signature ===

<syntaxhighlight lang="python">
def export_latents_to_video(
pipeline: CogVideoXPipeline,
latents: torch.FloatTensor,
video_path: str,
fps: int = 8
) -> None:
</syntaxhighlight>

=== Import ===

<syntaxhighlight lang="python">
from inference.ddim_inversion import export_latents_to_video
</syntaxhighlight>

== I/O Contract ==

=== Inputs ===

{| class="wikitable" style="width:100%;"
|-
! Parameter !! Type !! Default !! Description
|-
| <code>pipeline</code> || <code>CogVideoXPipeline</code> || Required || Loaded CogVideoX pipeline with VAE decoder and video processor
|-
| <code>latents</code> || <code>torch.FloatTensor</code> || Required || Latent tensor of shape <code>[B, T, C, H', W']</code> (typically the final step of a trajectory)
|-
| <code>video_path</code> || <code>str</code> || Required || Output file path for the MP4 video
|-
| <code>fps</code> || <code>int</code> || <code>8</code> || Frames per second for the output video
|}

=== Outputs ===

{| class="wikitable" style="width:100%;"
|-
! Output !! Type !! Description
|-
| Side effect || MP4 file || Video file written to <code>video_path</code>
|}

== Usage Examples ==

'''Example 1: Export inversion reconstruction for verification'''

<syntaxhighlight lang="python">
from inference.ddim_inversion import export_latents_to_video

# After DDIM inversion
inversion_trajectory = sample(pipe, latents, inverse_scheduler, prompt="")

# Export the inversion reconstruction (should match source video)
export_latents_to_video(
pipeline=pipe,
latents=inversion_trajectory[0], # First step = clean latents
video_path="inversion_verification.mp4",
fps=8
)
</syntaxhighlight>

'''Example 2: Export edited reconstruction'''

<syntaxhighlight lang="python">
# After prompted reconstruction
with OverrideAttnProcessors(pipe.transformer):
reconstruction = sample(
pipe, noise, forward_scheduler,
prompt="A cat running through autumn leaves",
reference_latents=reversed_trajectory,
)

# Export the edited video
export_latents_to_video(
pipeline=pipe,
latents=reconstruction[-1], # Last step = denoised result
video_path="edited_video.mp4",
fps=8
)
</syntaxhighlight>

'''Example 3: Side-by-side comparison'''

<syntaxhighlight lang="python">
# Export both for comparison
export_latents_to_video(pipe, inversion_trajectory[0],
"original_reconstruction.mp4", fps=8)
export_latents_to_video(pipe, reconstruction[-1],
"edited_result.mp4", fps=8)
</syntaxhighlight>

== Related Pages ==

* [[implements::Principle:Zai_org_CogVideo_DDIM_Video_Export]] -- Principle governing latent decoding and video export
* [[requires_env::Environment:Zai_org_CogVideo_Diffusers_Inference_Environment]]
* [[Implementation:Zai_org_CogVideo_DDIM_Attention_Injection_Reconstruction]] -- Previous step: prompted reconstruction
* [[Implementation:Zai_org_CogVideo_DDIM_Inversion_Sample]] -- Inversion step producing the trajectory to export
* [[Implementation:Zai_org_CogVideo_Encode_Video_Frames]] -- Encoding step that is inverted by this export

[[Category:Implementations]]

[[Category:Implementations]]

Implementation:Zai org CogVideo DDIM CogVideoXPipeline From Pretrained

2026-09-27T10:53:30Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Zai_org_CogVideo_DDIM_CogVideoXPipeline_From_Pretrained}}
{{PageInfo|type=Implementation|title=Zai_org_CogVideo_DDIM_CogVideoXPipeline_From_Pretrained}}
{| class="wikitable" style="float:right; margin-left:1em; width:300px;"
|-
! Attribute !! Value
|-
| '''Implementation Name''' || DDIM CogVideoXPipeline From Pretrained
|-
| '''Workflow''' || Video Editing DDIM Inversion
|-
| '''Step''' || 2 of 6
|-
| '''Type''' || Wrapper Doc
|-
| '''Source File''' || <code>inference/ddim_inversion.py:L474-478</code>
|-
| '''Repository''' || [https://github.com/zai-org/CogVideo zai-org/CogVideo]
|-
| '''External Dependencies''' || diffusers (CogVideoXPipeline)
|-
| '''Last Updated''' || 2026-02-10 00:00 GMT
|}

== Overview ==

Implementation of the CogVideoX pipeline loading for DDIM inversion. The pipeline is loaded from a pretrained CogVideoX-5B model path with bfloat16 precision and moved directly to CUDA.

=== Description ===

The pipeline loading is a straightforward call to <code>CogVideoXPipeline.from_pretrained</code> with two key constraints:

# '''Model variant''': Must use a CogVideoX-5B variant (requires rotary positional embeddings). The 2B variant is not supported.
# '''No CPU offloading''': The pipeline is loaded directly to GPU via <code>.to(device="cuda")</code> rather than using <code>enable_model_cpu_offload()</code>, since both forward and inverse passes are needed in the same session.

The loaded pipeline provides access to all components needed for DDIM inversion: <code>pipe.vae</code>, <code>pipe.transformer</code>, <code>pipe.text_encoder</code>, <code>pipe.tokenizer</code>, and <code>pipe.scheduler</code>.

=== Usage ===

<syntaxhighlight lang="python">
from diffusers import CogVideoXPipeline
import torch

pipe = CogVideoXPipeline.from_pretrained(
"THUDM/CogVideoX-5b",
torch_dtype=torch.bfloat16
).to(device="cuda")
</syntaxhighlight>

== Code Reference ==

=== Source Location ===

{| class="wikitable"
|-
! File !! Lines !! Description
|-
| <code>inference/ddim_inversion.py</code> || L474-478 || Pipeline loading
|}

=== Signature ===

<syntaxhighlight lang="python">
pipe = CogVideoXPipeline.from_pretrained(
model_path: str, # Must be CogVideoX-5B variant
torch_dtype: torch.dtype = torch.bfloat16
).to(device="cuda")
</syntaxhighlight>

=== Import ===

<syntaxhighlight lang="python">
from diffusers import CogVideoXPipeline
</syntaxhighlight>

== I/O Contract ==

=== Inputs ===

{| class="wikitable" style="width:100%;"
|-
! Parameter !! Type !! Default !! Description
|-
| <code>model_path</code> || <code>str</code> || Required || Path or HuggingFace model ID for a CogVideoX-5B variant (e.g., <code>"THUDM/CogVideoX-5b"</code>)
|-
| <code>torch_dtype</code> || <code>torch.dtype</code> || <code>torch.bfloat16</code> || Model precision; bfloat16 recommended for memory efficiency
|}

=== Outputs ===

{| class="wikitable" style="width:100%;"
|-
! Output !! Type !! Description
|-
| <code>pipe</code> || <code>CogVideoXPipeline</code> || Loaded pipeline on CUDA with VAE, transformer, text encoder, tokenizer, and scheduler
|}

== Usage Examples ==

'''Example 1: Load from HuggingFace Hub'''

<syntaxhighlight lang="python">
from diffusers import CogVideoXPipeline
import torch

pipe = CogVideoXPipeline.from_pretrained(
"THUDM/CogVideoX-5b",
torch_dtype=torch.bfloat16
).to(device="cuda")

# Access pipeline components
vae = pipe.vae
transformer = pipe.transformer
text_encoder = pipe.text_encoder
</syntaxhighlight>

'''Example 2: Load from local path'''

<syntaxhighlight lang="python">
pipe = CogVideoXPipeline.from_pretrained(
"/models/CogVideoX-5b",
torch_dtype=torch.bfloat16
).to(device="cuda")
</syntaxhighlight>

'''Example 3: Verify scheduler compatibility'''

<syntaxhighlight lang="python">
from diffusers import CogVideoXDDIMScheduler, DDIMInverseScheduler

# The pipeline's default scheduler can be replaced for inversion
inverse_scheduler = DDIMInverseScheduler.from_config(pipe.scheduler.config)
forward_scheduler = CogVideoXDDIMScheduler.from_config(pipe.scheduler.config)
</syntaxhighlight>

== Related Pages ==

* [[implements::Principle:Zai_org_CogVideo_DDIM_Pipeline_Loading]] -- Principle governing DDIM pipeline loading
* [[requires_env::Environment:Zai_org_CogVideo_Diffusers_Inference_Environment]]
* [[Implementation:Zai_org_CogVideo_Get_Video_Frames]] -- Previous step: video frame loading and preprocessing
* [[Implementation:Zai_org_CogVideo_Encode_Video_Frames]] -- Next step: encoding frames using the pipeline's VAE
* [[Implementation:Zai_org_CogVideo_DDIM_Inversion_Sample]] -- Inversion step using the loaded pipeline

[[Category:Implementations]]

[[Category:Implementations]]

Implementation:Zai org CogVideo DDIM Attention Injection Reconstruction

2026-09-27T10:53:30Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Zai_org_CogVideo_DDIM_Attention_Injection_Reconstruction}}
{{PageInfo|type=Implementation|title=Zai_org_CogVideo_DDIM_Attention_Injection_Reconstruction}}
{| class="wikitable" style="float:right; margin-left:1em; width:300px;"
|-
! Attribute !! Value
|-
| '''Implementation Name''' || DDIM Attention Injection Reconstruction
|-
| '''Workflow''' || Video Editing DDIM Inversion
|-
| '''Step''' || 5 of 6
|-
| '''Type''' || API Doc
|-
| '''Source File''' || <code>inference/ddim_inversion.py:L118-243</code>, <code>inference/ddim_inversion.py:L246-260</code>, <code>inference/ddim_inversion.py:L499-509</code>
|-
| '''Repository''' || [https://github.com/zai-org/CogVideo zai-org/CogVideo]
|-
| '''External Dependencies''' || diffusers (CogVideoXAttnProcessor2_0, CogVideoXBlock, CogVideoXTransformer3DModel), torch.nn.functional
|-
| '''Last Updated''' || 2026-02-10 00:00 GMT
|}

== Overview ==

Implementation of the prompted reconstruction step in the DDIM inversion video editing pipeline. This includes the custom attention processor (<code>CogVideoXAttnProcessor2_0ForDDIMInversion</code>), the context manager for attention processor replacement (<code>OverrideAttnProcessors</code>), and the reconstruction call that combines these components.

=== Description ===

Three components work together for prompted reconstruction:

# '''<code>CogVideoXAttnProcessor2_0ForDDIMInversion</code>''' (L118-243): Extends the standard <code>CogVideoXAttnProcessor2_0</code> to inject reference attention features from the source video's inversion trajectory. During each attention computation, it blends reference keys/values with current keys/values.
# '''<code>OverrideAttnProcessors</code>''' (L246-260): A Python context manager that temporarily replaces all attention processors in the transformer with the DDIM inversion variant. On entry, it swaps processors; on exit, it restores the originals.
# '''Reconstruction call''' (L499-509): Uses the context manager and calls the <code>sample</code> function with the forward scheduler, edit prompt, and reversed inversion trajectory as reference latents.

=== Usage ===

<syntaxhighlight lang="python">
from inference.ddim_inversion import OverrideAttnProcessors, sample

with OverrideAttnProcessors(pipe.transformer):
reconstruction_trajectory = sample(
pipeline=pipe,
latents=torch.randn_like(latents),
scheduler=pipe.scheduler,
prompt=edit_prompt,
reference_latents=reversed_inversion_trajectory,
)
</syntaxhighlight>

== Code Reference ==

=== Source Location ===

{| class="wikitable"
|-
! File !! Lines !! Description
|-
| <code>inference/ddim_inversion.py</code> || L118-243 || <code>CogVideoXAttnProcessor2_0ForDDIMInversion</code> class
|-
| <code>inference/ddim_inversion.py</code> || L246-260 || <code>OverrideAttnProcessors</code> context manager
|-
| <code>inference/ddim_inversion.py</code> || L499-509 || Reconstruction call site
|}

=== Signature ===

<syntaxhighlight lang="python">
class CogVideoXAttnProcessor2_0ForDDIMInversion(CogVideoXAttnProcessor2_0):
"""Custom attention processor that injects reference attention features."""

class OverrideAttnProcessors:
"""Context manager to temporarily replace attention processors."""
def __init__(self, transformer: CogVideoXTransformer3DModel): ...

# Usage:
with OverrideAttnProcessors(pipe.transformer):
reconstruction_trajectory = sample(
pipeline=pipe,
latents=torch.randn_like(latents),
scheduler=pipe.scheduler, # CogVideoXDDIMScheduler
prompt=edit_prompt,
reference_latents=reversed_inversion_trajectory,
)
</syntaxhighlight>

=== Import ===

<syntaxhighlight lang="python">
from inference.ddim_inversion import (
CogVideoXAttnProcessor2_0ForDDIMInversion,
OverrideAttnProcessors,
sample,
)
</syntaxhighlight>

== I/O Contract ==

=== Inputs ===

'''<code>CogVideoXAttnProcessor2_0ForDDIMInversion</code>'''

{| class="wikitable" style="width:100%;"
|-
! Parameter !! Type !! Default !! Description
|-
| Inherits from <code>CogVideoXAttnProcessor2_0</code> || -- || -- || All standard attention processor inputs (hidden_states, encoder_hidden_states, attention_mask, etc.)
|-
| Reference features || <code>torch.FloatTensor</code> || Via reference_latents || Attention keys/values from the inversion trajectory at the current timestep
|}

'''<code>OverrideAttnProcessors</code>'''

{| class="wikitable" style="width:100%;"
|-
! Parameter !! Type !! Default !! Description
|-
| <code>transformer</code> || <code>CogVideoXTransformer3DModel</code> || Required || The pipeline's transformer model whose attention processors will be replaced
|}

'''Reconstruction call'''

{| class="wikitable" style="width:100%;"
|-
! Parameter !! Type !! Default !! Description
|-
| <code>pipeline</code> || <code>CogVideoXPipeline</code> || Required || Loaded CogVideoX pipeline
|-
| <code>latents</code> || <code>torch.FloatTensor</code> || Required || Random noise tensor (same shape as encoded video latents)
|-
| <code>scheduler</code> || <code>CogVideoXDDIMScheduler</code> || Required || Forward DDIM scheduler
|-
| <code>prompt</code> || <code>str</code> || Required || Edit prompt describing the desired output
|-
| <code>reference_latents</code> || <code>torch.FloatTensor</code> || Required || Reversed inversion trajectory of shape <code>[num_steps, B, T, C, H', W']</code>
|}

=== Outputs ===

{| class="wikitable" style="width:100%;"
|-
! Output !! Type !! Description
|-
| <code>reconstruction_trajectory</code> || <code>torch.FloatTensor</code> || Reconstruction trajectory of shape <code>[num_steps, B, T, C, H', W']</code>; final step contains the edited video latents
|}

== Usage Examples ==

'''Example 1: Full video editing pipeline'''

<syntaxhighlight lang="python">
from diffusers import CogVideoXPipeline, CogVideoXDDIMScheduler, DDIMInverseScheduler
from inference.ddim_inversion import (
get_video_frames, encode_video_frames, sample,
OverrideAttnProcessors, export_latents_to_video,
)
import torch

# Load pipeline
pipe = CogVideoXPipeline.from_pretrained(
"THUDM/CogVideoX-5b", torch_dtype=torch.bfloat16
).to("cuda")

# Prepare schedulers
inverse_scheduler = DDIMInverseScheduler.from_config(pipe.scheduler.config)
forward_scheduler = CogVideoXDDIMScheduler.from_config(pipe.scheduler.config)

# Load and encode video
video_frames = get_video_frames("input.mp4")
latents = encode_video_frames(pipe.vae, video_frames)

# Step 1: Inversion
inversion_trajectory = sample(
pipe, latents, inverse_scheduler, prompt="", num_inference_steps=50
)

# Step 2: Reconstruction with edit
reversed_trajectory = inversion_trajectory.flip(0)

with OverrideAttnProcessors(pipe.transformer):
reconstruction = sample(
pipe,
torch.randn_like(latents),
forward_scheduler,
prompt="A dog playing in snow",
reference_latents=reversed_trajectory,
num_inference_steps=50,
)

# Export edited video
export_latents_to_video(pipe, reconstruction[-1], "edited_output.mp4")
</syntaxhighlight>

'''Example 2: Using the context manager pattern'''

<syntaxhighlight lang="python">
# The OverrideAttnProcessors context manager ensures
# original processors are restored after reconstruction
with OverrideAttnProcessors(pipe.transformer):
# Inside: attention processors are replaced with DDIM inversion variants
result = sample(pipe, noise, forward_scheduler, "new prompt",
reference_latents=ref)
# Outside: original processors are restored

# Pipeline can be used normally for other tasks
</syntaxhighlight>

== Related Pages ==

* [[implements::Principle:Zai_org_CogVideo_Prompted_Reconstruction]] -- Principle governing attention injection and prompted reconstruction
* [[requires_env::Environment:Zai_org_CogVideo_Diffusers_Inference_Environment]]
* [[Implementation:Zai_org_CogVideo_DDIM_Inversion_Sample]] -- Previous step: DDIM inversion producing the reference trajectory
* [[Implementation:Zai_org_CogVideo_DDIM_Export_Latents_To_Video]] -- Next step: exporting the edited video
* [[Implementation:Zai_org_CogVideo_DDIM_CogVideoXPipeline_From_Pretrained]] -- Pipeline loading

[[Category:Implementations]]

[[Category:Implementations]]

Implementation:Zai org CogVideo CogVLM2 Predict

2026-09-27T10:53:29Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Zai_org_CogVideo_CogVLM2_Predict}}
{{PageInfo|type=Implementation|title=Zai_org_CogVideo_CogVLM2_Predict}}
{| class="wikitable" style="float:right; margin-left:1em; width:300px;"
|-
! Attribute !! Value
|-
| '''Implementation Name''' || CogVLM2 Predict
|-
| '''Workflow''' || Video Captioning
|-
| '''Step''' || 4 of 5
|-
| '''Type''' || API Doc
|-
| '''Source File''' || <code>tools/caption/video_caption.py:L72-100</code>
|-
| '''Repository''' || [https://github.com/zai-org/CogVideo zai-org/CogVideo]
|-
| '''External Dependencies''' || transformers, torch
|-
| '''Last Updated''' || 2026-02-10 00:00 GMT
|}

== Overview ==

Implementation of the caption prediction function for the CogVLM2 video captioning pipeline. The <code>predict</code> function orchestrates video frame loading, input construction, and autoregressive text generation to produce a natural language description of the video content.

=== Description ===

The <code>predict</code> function:

# Calls <code>load_video(video_data)</code> to extract representative frames
# Uses the model's <code>build_conversation_input_ids</code> to construct multimodal input
# Moves all input tensors to the target device with appropriate dtypes
# Calls <code>model.generate()</code> with controlled generation parameters
# Decodes the generated token IDs to text using the tokenizer
# Returns the caption string

Key generation parameters are hardcoded for deterministic, high-quality captions:
* <code>max_new_tokens=2048</code>
* <code>pad_token_id=128002</code> (Llama3 EOS token)
* <code>top_k=1</code>
* <code>do_sample=False</code>
* <code>top_p=0.1</code>

=== Usage ===

<syntaxhighlight lang="python">
from tools.caption.video_caption import predict

with open("video.mp4", "rb") as f:
video_data = f.read()

caption = predict(
prompt="Please describe this video in detail.",
video_data=video_data,
temperature=0.1
)
print(caption)
</syntaxhighlight>

== Code Reference ==

=== Source Location ===

{| class="wikitable"
|-
! File !! Lines !! Description
|-
| <code>tools/caption/video_caption.py</code> || L72-100 || <code>predict</code> function
|}

=== Signature ===

<syntaxhighlight lang="python">
def predict(
prompt: str, # e.g. "Please describe this video in detail."
video_data: bytes, # Raw video file bytes
temperature: float # e.g. 0.1
) -> str: # Generated caption
</syntaxhighlight>

=== Import ===

<syntaxhighlight lang="python">
from tools.caption.video_caption import predict
</syntaxhighlight>

== I/O Contract ==

=== Inputs ===

{| class="wikitable" style="width:100%;"
|-
! Parameter !! Type !! Default !! Description
|-
| <code>prompt</code> || <code>str</code> || Required || Instruction prompt for the model (e.g., <code>"Please describe this video in detail."</code>)
|-
| <code>video_data</code> || <code>bytes</code> || Required || Raw video file bytes
|-
| <code>temperature</code> || <code>float</code> || Required || Temperature for generation (typically 0.1 for deterministic captions)
|}

'''Internal generation kwargs (hardcoded)'''

{| class="wikitable" style="width:100%;"
|-
! Parameter !! Value !! Description
|-
| <code>max_new_tokens</code> || <code>2048</code> || Maximum number of tokens to generate
|-
| <code>pad_token_id</code> || <code>128002</code> || Llama3 EOS token ID used for padding
|-
| <code>top_k</code> || <code>1</code> || Greedy decoding (select most probable token)
|-
| <code>do_sample</code> || <code>False</code> || Disable stochastic sampling
|-
| <code>top_p</code> || <code>0.1</code> || Nucleus sampling threshold
|}

=== Outputs ===

{| class="wikitable" style="width:100%;"
|-
! Output !! Type !! Description
|-
| Return value || <code>str</code> || Generated caption text describing the video content
|}

== Usage Examples ==

'''Example 1: Basic caption generation'''

<syntaxhighlight lang="python">
from tools.caption.video_caption import predict

with open("cooking_video.mp4", "rb") as f:
video_data = f.read()

caption = predict(
prompt="Please describe this video in detail.",
video_data=video_data,
temperature=0.1
)
print(caption)
# Output: "The video shows a person in a kitchen preparing a meal.
# They begin by chopping vegetables on a wooden cutting board..."
</syntaxhighlight>

'''Example 2: Specific aspect captioning'''

<syntaxhighlight lang="python">
caption = predict(
prompt="Describe the main actions happening in this video.",
video_data=video_data,
temperature=0.1
)
</syntaxhighlight>

'''Example 3: Batch captioning multiple videos'''

<syntaxhighlight lang="python">
import os

video_dir = "/data/videos/"
captions = {}

for filename in os.listdir(video_dir):
if filename.endswith(".mp4"):
with open(os.path.join(video_dir, filename), "rb") as f:
video_data = f.read()
caption = predict(
prompt="Please describe this video in detail.",
video_data=video_data,
temperature=0.1
)
captions[filename] = caption
print(f"{filename}: {caption[:100]}...")
</syntaxhighlight>

== Related Pages ==

* [[implements::Principle:Zai_org_CogVideo_Caption_Generation]] -- Principle governing caption generation
* [[requires_env::Environment:Zai_org_CogVideo_Video_Captioning_Environment]]
* [[Implementation:Zai_org_CogVideo_Caption_Load_Video]] -- Frame extraction called internally by predict
* [[Implementation:Zai_org_CogVideo_Caption_File_Output]] -- Next step: saving the generated caption
* [[Implementation:Zai_org_CogVideo_CogVLM2_Model_Loading]] -- Model loading that provides the model and tokenizer used by predict

[[Category:Implementations]]

[[Category:Implementations]]

Implementation:Zai org CogVideo CogVLM2 Model Loading

2026-09-27T10:53:28Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Zai_org_CogVideo_CogVLM2_Model_Loading}}
{{PageInfo|type=Implementation|title=Zai_org_CogVideo_CogVLM2_Model_Loading}}
{| class="wikitable" style="float:right; margin-left:1em; width:300px;"
|-
! Attribute !! Value
|-
| '''Implementation Name''' || CogVLM2 Model Loading
|-
| '''Workflow''' || Video Captioning
|-
| '''Step''' || 2 of 5
|-
| '''Type''' || Wrapper Doc
|-
| '''Source File''' || <code>tools/caption/video_caption.py:L60-69</code>
|-
| '''Repository''' || [https://github.com/zai-org/CogVideo zai-org/CogVideo]
|-
| '''External Dependencies''' || transformers (AutoModelForCausalLM, AutoTokenizer)
|-
| '''Last Updated''' || 2026-02-10 00:00 GMT
|}

== Overview ==

Implementation of CogVLM2 model and tokenizer loading for the video captioning pipeline. The model is loaded from the HuggingFace Hub or a local path with appropriate precision and set to evaluation mode.

=== Description ===

The model loading code:

# Loads the tokenizer using <code>AutoTokenizer.from_pretrained</code> with <code>trust_remote_code=True</code>
# Loads the model using <code>AutoModelForCausalLM.from_pretrained</code> with the selected torch dtype
# Sets the model to eval mode with <code>.eval()</code>
# Moves the model to the target device with <code>.to(DEVICE)</code>

The model path defaults to <code>"THUDM/cogvlm2-llama3-caption"</code>, a CogVLM2 variant specifically fine-tuned for video captioning.

=== Usage ===

<syntaxhighlight lang="python">
from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

MODEL_PATH = "THUDM/cogvlm2-llama3-caption"
TORCH_TYPE = torch.bfloat16 if torch.cuda.is_bf16_supported() else torch.float16
DEVICE = "cuda"

tokenizer = AutoTokenizer.from_pretrained(MODEL_PATH, trust_remote_code=True)
model = AutoModelForCausalLM.from_pretrained(
MODEL_PATH, torch_dtype=TORCH_TYPE, trust_remote_code=True
).eval().to(DEVICE)
</syntaxhighlight>

== Code Reference ==

=== Source Location ===

{| class="wikitable"
|-
! File !! Lines !! Description
|-
| <code>tools/caption/video_caption.py</code> || L60-69 || Model and tokenizer loading
|}

=== Signature ===

<syntaxhighlight lang="python">
tokenizer = AutoTokenizer.from_pretrained(
MODEL_PATH, # "THUDM/cogvlm2-llama3-caption"
trust_remote_code=True
)
model = AutoModelForCausalLM.from_pretrained(
MODEL_PATH,
torch_dtype=TORCH_TYPE, # bfloat16 or float16
trust_remote_code=True
).eval().to(DEVICE)
</syntaxhighlight>

=== Import ===

<syntaxhighlight lang="python">
from transformers import AutoModelForCausalLM, AutoTokenizer
</syntaxhighlight>

== I/O Contract ==

=== Inputs ===

{| class="wikitable" style="width:100%;"
|-
! Parameter !! Type !! Default !! Description
|-
| <code>MODEL_PATH</code> || <code>str</code> || <code>"THUDM/cogvlm2-llama3-caption"</code> || HuggingFace model ID or local path to CogVLM2 weights
|-
| <code>TORCH_TYPE</code> || <code>torch.dtype</code> || Auto-detected || <code>torch.bfloat16</code> if supported, else <code>torch.float16</code>
|-
| <code>DEVICE</code> || <code>str</code> || <code>"cuda"</code> || Target device for model inference
|-
| <code>trust_remote_code</code> || <code>bool</code> || <code>True</code> || Required for CogVLM2 custom model code
|}

=== Outputs ===

{| class="wikitable" style="width:100%;"
|-
! Output !! Type !! Description
|-
| <code>tokenizer</code> || <code>AutoTokenizer</code> || Loaded Llama3-based tokenizer for text encoding/decoding
|-
| <code>model</code> || <code>AutoModelForCausalLM</code> || Loaded CogVLM2 model in eval mode on target device
|}

== Usage Examples ==

'''Example 1: Standard loading'''

<syntaxhighlight lang="python">
from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

MODEL_PATH = "THUDM/cogvlm2-llama3-caption"
TORCH_TYPE = torch.bfloat16 if torch.cuda.is_bf16_supported() else torch.float16
DEVICE = "cuda"

tokenizer = AutoTokenizer.from_pretrained(MODEL_PATH, trust_remote_code=True)
model = AutoModelForCausalLM.from_pretrained(
MODEL_PATH, torch_dtype=TORCH_TYPE, trust_remote_code=True
).eval().to(DEVICE)
</syntaxhighlight>

'''Example 2: Loading from local path'''

<syntaxhighlight lang="python">
MODEL_PATH = "/models/cogvlm2-llama3-caption"
tokenizer = AutoTokenizer.from_pretrained(MODEL_PATH, trust_remote_code=True)
model = AutoModelForCausalLM.from_pretrained(
MODEL_PATH, torch_dtype=torch.bfloat16, trust_remote_code=True
).eval().to("cuda")
</syntaxhighlight>

'''Example 3: Loading with 4-bit quantization'''

<syntaxhighlight lang="python">
from transformers import BitsAndBytesConfig

quant_config = BitsAndBytesConfig(
load_in_4bit=True,
bnb_4bit_compute_dtype=torch.bfloat16,
)

model = AutoModelForCausalLM.from_pretrained(
MODEL_PATH,
torch_dtype=TORCH_TYPE,
trust_remote_code=True,
quantization_config=quant_config,
).eval()
</syntaxhighlight>

== Related Pages ==

* [[implements::Principle:Zai_org_CogVideo_Caption_Model_Loading]] -- Principle governing caption model loading
* [[requires_env::Environment:Zai_org_CogVideo_Video_Captioning_Environment]]
* [[uses_heuristic::Heuristic:Zai_org_CogVideo_BF16_FP16_Precision_Selection]]
* [[Implementation:Zai_org_CogVideo_Captioning_Requirements_Install]] -- Previous step: environment setup
* [[Implementation:Zai_org_CogVideo_Caption_Load_Video]] -- Next step: loading video frames for captioning
* [[Implementation:Zai_org_CogVideo_CogVLM2_Predict]] -- Prediction step using the loaded model

[[Category:Implementations]]

[[Category:Implementations]]

Implementation:Zai org CogVideo Captioning Requirements Install

2026-09-27T10:53:28Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Zai_org_CogVideo_Captioning_Requirements_Install}}
{{PageInfo|type=Implementation|title=Zai_org_CogVideo_Captioning_Requirements_Install}}
{| class="wikitable" style="float:right; margin-left:1em; width:300px;"
|-
! Attribute !! Value
|-
| '''Implementation Name''' || Captioning Requirements Install
|-
| '''Workflow''' || Video Captioning
|-
| '''Step''' || 1 of 5
|-
| '''Type''' || External Tool Doc
|-
| '''Source File''' || <code>tools/caption/requirements.txt:L1-23</code>
|-
| '''Repository''' || [https://github.com/zai-org/CogVideo zai-org/CogVideo]
|-
| '''Last Updated''' || 2026-02-10 00:00 GMT
|}

== Overview ==

Implementation of the environment setup for the video captioning pipeline. Dependencies are specified in a requirements.txt file and installed via pip.

=== Description ===

The requirements file specifies all Python packages needed for the captioning workflow:

* '''transformers''': HuggingFace model loading and tokenization
* '''torch''': Tensor computation and GPU acceleration
* '''decord''': Efficient video frame extraction
* '''numpy''': Numerical array operations
* '''accelerate''': Model loading and device management
* '''sentencepiece''': Tokenizer backend for Llama3
* '''xformers''' (optional): Memory-efficient attention for reduced GPU memory

The installation command installs all dependencies in a single pip invocation.

=== Usage ===

<syntaxhighlight lang="bash">
pip install -r tools/caption/requirements.txt
</syntaxhighlight>

== Code Reference ==

=== Source Location ===

{| class="wikitable"
|-
! File !! Lines !! Description
|-
| <code>tools/caption/requirements.txt</code> || L1-23 || Package dependency list
|}

=== Signature ===

<syntaxhighlight lang="bash">
pip install -r tools/caption/requirements.txt
</syntaxhighlight>

=== Import ===

Not applicable (installation command).

== I/O Contract ==

=== Inputs ===

{| class="wikitable" style="width:100%;"
|-
! Parameter !! Type !! Default !! Description
|-
| <code>requirements.txt</code> || File || Required || Dependency specification file at <code>tools/caption/requirements.txt</code>
|}

=== Outputs ===

{| class="wikitable" style="width:100%;"
|-
! Output !! Type !! Description
|-
| Side effect || Installed packages || All required Python packages installed in the current environment
|}

== Usage Examples ==

'''Example 1: Standard installation'''

<syntaxhighlight lang="bash">
cd /path/to/CogVideo
pip install -r tools/caption/requirements.txt
</syntaxhighlight>

'''Example 2: Installation in a virtual environment'''

<syntaxhighlight lang="bash">
python -m venv caption_env
source caption_env/bin/activate
pip install -r tools/caption/requirements.txt
</syntaxhighlight>

'''Example 3: Installation with optional xformers'''

<syntaxhighlight lang="bash">
pip install -r tools/caption/requirements.txt
pip install xformers # Optional, for memory-efficient attention
</syntaxhighlight>

'''Example 4: Verify installation'''

<syntaxhighlight lang="python">
import torch
import decord
import transformers
import sentencepiece

print(f"torch: {torch.__version__}")
print(f"CUDA available: {torch.cuda.is_available()}")
print(f"bfloat16 supported: {torch.cuda.is_bf16_supported()}")
</syntaxhighlight>

== Related Pages ==

* [[implements::Principle:Zai_org_CogVideo_Captioning_Environment_Setup]] -- Principle governing captioning environment setup
* [[requires_env::Environment:Zai_org_CogVideo_Video_Captioning_Environment]]
* [[Implementation:Zai_org_CogVideo_CogVLM2_Model_Loading]] -- Next step: loading the model using the installed packages
* [[Implementation:Zai_org_CogVideo_Caption_Load_Video]] -- Frame extraction using the installed decord package

[[Category:Implementations]]

[[Category:Implementations]]

Implementation:Zai org CogVideo Caption Load Video

2026-09-27T10:53:27Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Zai_org_CogVideo_Caption_Load_Video}}
{{PageInfo|type=Implementation|title=Zai_org_CogVideo_Caption_Load_Video}}
{| class="wikitable" style="float:right; margin-left:1em; width:300px;"
|-
! Attribute !! Value
|-
| '''Implementation Name''' || Caption Load Video
|-
| '''Workflow''' || Video Captioning
|-
| '''Step''' || 3 of 5
|-
| '''Type''' || API Doc
|-
| '''Source File''' || <code>tools/caption/video_caption.py:L25-57</code>
|-
| '''Repository''' || [https://github.com/zai-org/CogVideo zai-org/CogVideo]
|-
| '''External Dependencies''' || decord, numpy
|-
| '''Last Updated''' || 2026-02-10 00:00 GMT
|}

== Overview ==

Implementation of video frame extraction for the captioning pipeline. The <code>load_video</code> function extracts a fixed number of representative frames from raw video bytes using configurable temporal sampling strategies.

=== Description ===

The <code>load_video</code> function:

# Creates a decord <code>VideoReader</code> from the raw video bytes
# Determines the total number of frames in the video
# Selects frame indices based on the chosen strategy:
#* '''Chat mode''': Computes 1-FPS sampling indices up to 24 frames
#* '''Base mode''': Computes uniform sampling indices for exactly 24 frames
# Extracts the selected frames using decord's batch frame access
# Returns the frames as a tensor in <code>[C, T, H, W]</code> format

The function accepts raw video bytes rather than a file path, enabling in-memory video processing without intermediate file I/O.

=== Usage ===

<syntaxhighlight lang="python">
from tools.caption.video_caption import load_video

with open("video.mp4", "rb") as f:
video_data = f.read()

frames = load_video(video_data, strategy="chat")
# frames.shape: [3, 24, H, W]
</syntaxhighlight>

== Code Reference ==

=== Source Location ===

{| class="wikitable"
|-
! File !! Lines !! Description
|-
| <code>tools/caption/video_caption.py</code> || L25-57 || <code>load_video</code> function
|}

=== Signature ===

<syntaxhighlight lang="python">
def load_video(
video_data: bytes,
strategy: str = "chat" # "chat" or "base"
) -> torch.Tensor: # [C, T, H, W]
</syntaxhighlight>

=== Import ===

<syntaxhighlight lang="python">
from tools.caption.video_caption import load_video
</syntaxhighlight>

== I/O Contract ==

=== Inputs ===

{| class="wikitable" style="width:100%;"
|-
! Parameter !! Type !! Default !! Description
|-
| <code>video_data</code> || <code>bytes</code> || Required || Raw video file bytes (e.g., from <code>open("video.mp4", "rb").read()</code>)
|-
| <code>strategy</code> || <code>str</code> || <code>"chat"</code> || Sampling strategy: <code>"chat"</code> (1 FPS up to 24 frames) or <code>"base"</code> (uniform 24 frames)
|}

=== Outputs ===

{| class="wikitable" style="width:100%;"
|-
! Output !! Type !! Description
|-
| Return value || <code>torch.Tensor</code> || Video frames tensor of shape <code>[C, T, H, W]</code> where <code>C=3</code> (RGB), <code>T<=24</code>, and <code>H, W</code> are the original video dimensions
|}

== Usage Examples ==

'''Example 1: Chat mode (1 FPS sampling)'''

<syntaxhighlight lang="python">
from tools.caption.video_caption import load_video

with open("natural_scene.mp4", "rb") as f:
video_data = f.read()

frames = load_video(video_data, strategy="chat")
print(f"Extracted {frames.shape[1]} frames")
# For a 30-second video: 24 frames (capped)
# For a 10-second video: 10 frames
</syntaxhighlight>

'''Example 2: Base mode (uniform sampling)'''

<syntaxhighlight lang="python">
frames = load_video(video_data, strategy="base")
print(f"Extracted {frames.shape[1]} frames")
# Always 24 frames regardless of video length
</syntaxhighlight>

'''Example 3: Integration with prediction'''

<syntaxhighlight lang="python">
from tools.caption.video_caption import load_video, predict

with open("input_video.mp4", "rb") as f:
video_data = f.read()

# load_video is called internally by predict()
caption = predict(
prompt="Please describe this video in detail.",
video_data=video_data,
temperature=0.1
)
print(caption)
</syntaxhighlight>

== Related Pages ==

* [[implements::Principle:Zai_org_CogVideo_Video_Frame_Extraction]] -- Principle governing video frame extraction
* [[requires_env::Environment:Zai_org_CogVideo_Video_Captioning_Environment]]
* [[uses_heuristic::Heuristic:Zai_org_CogVideo_Decord_Import_Order_Bug]]
* [[Implementation:Zai_org_CogVideo_CogVLM2_Model_Loading]] -- Previous step: model loading
* [[Implementation:Zai_org_CogVideo_CogVLM2_Predict]] -- Next step: caption generation using extracted frames

[[Category:Implementations]]

[[Category:Implementations]]

Implementation:Zai org CogVideo Caption File Output

2026-09-27T10:53:27Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Zai_org_CogVideo_Caption_File_Output}}
{{PageInfo|type=Implementation|title=Zai_org_CogVideo_Caption_File_Output}}
{| class="wikitable" style="float:right; margin-left:1em; width:300px;"
|-
! Attribute !! Value
|-
| '''Implementation Name''' || Caption File Output
|-
| '''Workflow''' || Video Captioning
|-
| '''Step''' || 5 of 5
|-
| '''Type''' || Pattern Doc
|-
| '''Source File''' || <code>tools/caption/video_caption.py:L103-112</code>
|-
| '''Repository''' || [https://github.com/zai-org/CogVideo zai-org/CogVideo]
|-
| '''Last Updated''' || 2026-02-10 00:00 GMT
|}

== Overview ==

Implementation of caption text output for the video captioning pipeline. This pattern document describes how to save generated captions to files compatible with the CogVideoX fine-tuning dataset format.

=== Description ===

The caption file output pattern:

# Calls <code>predict()</code> to generate the caption text for a video
# Writes the caption to a file using standard Python I/O
# The output format matches the fine-tuning dataset's <code>caption_column</code> expectations

The implementation uses a simple append-mode file write to build up a prompts file across multiple videos. Each caption is written on a separate line.

=== Usage ===

<syntaxhighlight lang="python">
from tools.caption.video_caption import predict

with open("video.mp4", "rb") as f:
video_data = f.read()

response = predict("Please describe this video in detail.", video_data, 0.1)

with open("prompts.txt", "a") as f:
f.write(response + "\n")
</syntaxhighlight>

== Code Reference ==

=== Source Location ===

{| class="wikitable"
|-
! File !! Lines !! Description
|-
| <code>tools/caption/video_caption.py</code> || L103-112 || Caption output section
|}

=== Signature ===

<syntaxhighlight lang="python">
# Pattern: Save caption text to file
# The output format should match the dataset's caption_column expectations
response = predict(prompt, video_data, temperature)
# Save to file (user implements this pattern):
with open("prompts.txt", "a") as f:
f.write(response + "\n")
</syntaxhighlight>

=== Import ===

<syntaxhighlight lang="python">
# Standard Python I/O - no additional imports needed
</syntaxhighlight>

== I/O Contract ==

=== Inputs ===

{| class="wikitable" style="width:100%;"
|-
! Parameter !! Type !! Default !! Description
|-
| <code>response</code> || <code>str</code> || Required || Generated caption text from <code>predict()</code>
|-
| Output file path || <code>str</code> || <code>"prompts.txt"</code> || Path to the output caption file
|}

=== Outputs ===

{| class="wikitable" style="width:100%;"
|-
! Output !! Type !! Description
|-
| Side effect || Text file || Caption text appended to the output file, one caption per line
|}

== Usage Examples ==

'''Example 1: Single video caption to file'''

<syntaxhighlight lang="python">
from tools.caption.video_caption import predict

with open("my_video.mp4", "rb") as f:
video_data = f.read()

caption = predict(
"Please describe this video in detail.",
video_data,
0.1
)

with open("prompts.txt", "w") as f:
f.write(caption + "\n")
</syntaxhighlight>

'''Example 2: Batch captioning with aggregated output'''

<syntaxhighlight lang="python">
import os
from tools.caption.video_caption import predict

video_dir = "/data/training_videos/"
output_file = "prompts.txt"

with open(output_file, "w") as out_f:
for filename in sorted(os.listdir(video_dir)):
if filename.endswith(".mp4"):
video_path = os.path.join(video_dir, filename)
with open(video_path, "rb") as f:
video_data = f.read()

caption = predict(
"Please describe this video in detail.",
video_data,
0.1
)
out_f.write(caption + "\n")
print(f"Captioned: {filename}")
</syntaxhighlight>

'''Example 3: Per-video caption files'''

<syntaxhighlight lang="python">
import os
from tools.caption.video_caption import predict

video_dir = "/data/training_videos/"
caption_dir = "/data/captions/"
os.makedirs(caption_dir, exist_ok=True)

for filename in sorted(os.listdir(video_dir)):
if filename.endswith(".mp4"):
video_path = os.path.join(video_dir, filename)
caption_path = os.path.join(
caption_dir,
filename.replace(".mp4", ".txt")
)

with open(video_path, "rb") as f:
video_data = f.read()

caption = predict(
"Please describe this video in detail.",
video_data,
0.1
)

with open(caption_path, "w") as f:
f.write(caption)
print(f"Saved: {caption_path}")
</syntaxhighlight>

'''Example 4: CSV format for dataset integration'''

<syntaxhighlight lang="python">
import csv
import os
from tools.caption.video_caption import predict

video_dir = "/data/training_videos/"

with open("dataset.csv", "w", newline="") as csvfile:
writer = csv.writer(csvfile)
writer.writerow(["video_path", "caption"])

for filename in sorted(os.listdir(video_dir)):
if filename.endswith(".mp4"):
video_path = os.path.join(video_dir, filename)
with open(video_path, "rb") as f:
video_data = f.read()

caption = predict(
"Please describe this video in detail.",
video_data,
0.1
)
writer.writerow([video_path, caption])
</syntaxhighlight>

== Related Pages ==

* [[implements::Principle:Zai_org_CogVideo_Caption_Output]] -- Principle governing caption output to files
* [[requires_env::Environment:Zai_org_CogVideo_Video_Captioning_Environment]]
* [[Implementation:Zai_org_CogVideo_CogVLM2_Predict]] -- Previous step: caption generation providing the text to save
* [[Implementation:Zai_org_CogVideo_Captioning_Requirements_Install]] -- Environment setup for the captioning pipeline

[[Category:Implementations]]

[[Category:Implementations]]

Implementation:Webdriverio Webdriverio SpecReporter Class

2026-09-27T10:53:26Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Webdriverio_Webdriverio_SpecReporter_Class}}
== Overview ==

Concrete tool for formatted console test result reporting provided by the <code>@wdio/spec-reporter</code> package.

== Metadata ==

{| class="wikitable"
|-
! Field !! Value
|-
| '''Page Type''' || Implementation
|-
| '''Repository''' || [https://github.com/webdriverio/webdriverio webdriverio/webdriverio]
|-
| '''Package''' || <code>@wdio/spec-reporter</code>
|-
| '''Source File''' || <code>packages/wdio-spec-reporter/src/index.ts</code>, Lines L17-697
|-
| '''Types''' || <code>packages/wdio-spec-reporter/src/types.ts</code>
|-
| '''Related Principle''' || [[Principle:Webdriverio_Webdriverio_Test_Result_Reporting|Principle: Test_Result_Reporting]]
|}

== Description ==

The <code>SpecReporter</code> class extends <code>WDIOReporter</code> to produce formatted, colored console output showing test suite hierarchy, individual test results (checkmark for pass, X for fail, dash for skipped), timing information, and error stacks for failures. It is the default and most commonly used reporter for WDIO projects.

The reporter tracks suite ordering, maintains state counts (passed, failed, skipped, pending, retried), computes indentation for nested suites, and produces a final summary with pass/fail counts and total duration. It supports real-time reporting (printing results as tests complete) and deferred reporting (printing a complete summary after all tests in a worker finish).

For Sauce Labs users, the reporter can generate sharable test result links. It also handles multiremote sessions, Cucumber data tables and docstrings, and suite-level retries.

== Source Reference ==

{| class="wikitable"
|-
! File !! Lines !! Description
|-
| <code>packages/wdio-spec-reporter/src/index.ts</code> || L17-697 || SpecReporter class with all event handlers and formatting logic
|-
| <code>packages/wdio-spec-reporter/src/types.ts</code> || L1-95 || SpecReporterOptions, StateCount, Symbols, State enum, ChalkColors
|-
| <code>packages/wdio-spec-reporter/src/utils.ts</code> || -- || Table formatting utilities for Cucumber data tables
|}

== Signature ==

<syntaxhighlight lang="typescript">
class SpecReporter extends WDIOReporter {
constructor(options: SpecReporterOptions)

// Event handlers
onRunnerStart(runner: RunnerStats): void
onSuiteStart(suite: SuiteStats): void
onSuiteEnd(): void
onSuiteRetry(): void
onHookEnd(hook: HookStats): void
onTestStart(): void
onTestPass(testStat: TestStats): void
onTestFail(testStat: TestStats): void
onTestSkip(testStat: TestStats): void
onTestPending(testStat: TestStats): void
onRunnerEnd(runner: RunnerStats): void

// Formatting methods
printReport(runner: RunnerStats): void
getResultDisplay(preface?: string): string[]
getCountDisplay(duration: string): string[]
getFailureDisplay(): string[]
getHeaderDisplay(runner: RunnerStats): string[]
getOrderedSuites(): SuiteStats[]
getEventsToReport(suite: SuiteStats): (HookStats | TestStats)[]
getEnviromentCombo(capability: Capabilities, verbose?: boolean, isMultiremote?: boolean): string
}
</syntaxhighlight>

== Import ==

Configured via the reporters array in <code>wdio.conf.ts</code>:

<syntaxhighlight lang="typescript">
// String form (default options)
reporters: ['spec']

// Array form (with options)
reporters: [['spec', {
onlyFailures: true,
addConsoleLogs: true,
realtimeReporting: false,
showPreface: true,
color: true
}]]
</syntaxhighlight>

Or as a direct import for programmatic use:

<syntaxhighlight lang="typescript">
import SpecReporter from '@wdio/spec-reporter'
</syntaxhighlight>

== Options ==

{| class="wikitable"
|-
! Option !! Type !! Default !! Description
|-
| <code>onlyFailures</code> || <code>boolean</code> || <code>false</code> || Only print results for runners that had failures
|-
| <code>addConsoleLogs</code> || <code>boolean</code> || <code>false</code> || Capture and display console.log output from tests
|-
| <code>realtimeReporting</code> || <code>boolean</code> || <code>false</code> || Print test results as they complete (not just at runner end)
|-
| <code>showPreface</code> || <code>boolean</code> || <code>true</code> || Show browser/capability prefix on each line (e.g., <code>[Chrome 120 #0]</code>)
|-
| <code>color</code> || <code>boolean</code> || <code>true</code> || Enable/disable colored output via Chalk
|-
| <code>symbols</code> || <code>Partial<Symbols></code> || <code>{passed: '✓', failed: '✖', skipped: '-', pending: '?', retried: '↻'}</code> || Custom symbols for test states
|-
| <code>sauceLabsSharableLinks</code> || <code>boolean</code> || <code>true</code> || Generate sharable Sauce Labs test result links
|}

== Inputs / Outputs Contract ==

=== Inputs (Event Handlers) ===

{| class="wikitable"
|-
! Event Handler !! Input Type !! Description
|-
| <code>onRunnerStart</code> || <code>RunnerStats</code> || Worker started: capabilities, cid, session info
|-
| <code>onSuiteStart</code> || <code>SuiteStats</code> || Suite (describe/feature) started: title, file
|-
| <code>onSuiteEnd</code> || -- || Suite completed
|-
| <code>onSuiteRetry</code> || -- || Suite is being retried (adjusts state counts)
|-
| <code>onHookEnd</code> || <code>HookStats</code> || Hook completed (counts as failure if hook.error exists)
|-
| <code>onTestStart</code> || -- || Test started (resets console output buffer)
|-
| <code>onTestPass</code> || <code>TestStats</code> || Test passed
|-
| <code>onTestFail</code> || <code>TestStats</code> || Test failed
|-
| <code>onTestSkip</code> || <code>TestStats</code> || Test skipped
|-
| <code>onTestPending</code> || <code>TestStats</code> || Test pending (with pendingReason)
|-
| <code>onRunnerEnd</code> || <code>RunnerStats</code> || Worker finished: triggers final report output
|}

=== Outputs ===

Formatted console output with the following structure:

<syntaxhighlight lang="text">
------------------------------------------------------------------
[Chrome 120 linux #0] Running: Chrome 120 linux
[Chrome 120 linux #0] Session ID: abc123def456
[Chrome 120 linux #0]
[Chrome 120 linux #0] >> test/specs/login.spec.ts
[Chrome 120 linux #0] Login Page
[Chrome 120 linux #0] ✓ should display the login form
[Chrome 120 linux #0] ✓ should accept valid credentials
[Chrome 120 linux #0] ✖ should show error for invalid credentials
[Chrome 120 linux #0]
[Chrome 120 linux #0] 2 passing (3.2s)
[Chrome 120 linux #0] 1 failing
[Chrome 120 linux #0]
[Chrome 120 linux #0] 1) Login Page should show error for invalid credentials
[Chrome 120 linux #0] Expected "Login failed" to equal "Invalid credentials"
[Chrome 120 linux #0] at Context.<anonymous> (test/specs/login.spec.ts:25:9)
</syntaxhighlight>

== Color Scheme ==

{| class="wikitable"
|-
! State !! Color !! Symbol
|-
| Passed || Green || <code>✓</code>
|-
| Failed || Red || <code>✖</code>
|-
| Skipped || Cyan || <code>-</code>
|-
| Pending || Cyan || <code>?</code>
|-
| Retried || Yellow || <code>↻</code>
|-
| Unknown/Default || Gray || (none)
|}

Implemented via the <code>getColor()</code> method and Chalk:

<syntaxhighlight lang="typescript">
// packages/wdio-spec-reporter/src/index.ts L622-643
getColor(state?: string): ChalkColors {
let color = ChalkColors.GRAY
switch (state) {
case State.PASSED: color = ChalkColors.GREEN; break
case State.PENDING:
case State.SKIPPED: color = ChalkColors.CYAN; break
case State.FAILED: color = ChalkColors.RED; break
case State.RETRIED: color = ChalkColors.YELLOW; break
}
return color
}
</syntaxhighlight>

== Usage Example ==

=== Basic Configuration ===

<syntaxhighlight lang="typescript">
// wdio.conf.ts
export const config: WebdriverIO.Config = {
reporters: ['spec'],
// ... other config
}
</syntaxhighlight>

=== Show Only Failures (CI-friendly) ===

<syntaxhighlight lang="typescript">
// wdio.conf.ts
export const config: WebdriverIO.Config = {
reporters: [['spec', {
onlyFailures: true,
showPreface: false
}]],
// ... other config
}
</syntaxhighlight>

=== With Console Log Capture ===

<syntaxhighlight lang="typescript">
// wdio.conf.ts
export const config: WebdriverIO.Config = {
reporters: [['spec', {
addConsoleLogs: true,
realtimeReporting: true
}]],
// ... other config
}
</syntaxhighlight>

== Internal State Management ==

The SpecReporter tracks state using several internal structures:

<syntaxhighlight lang="typescript">
// packages/wdio-spec-reporter/src/index.ts L38-44
private _stateCounts: StateCount = {
passed: 0,
failed: 0,
skipped: 0,
pending: 0,
retried: 0
}
</syntaxhighlight>

Suite ordering is maintained by tracking UIDs in the order suites are started:

<syntaxhighlight lang="typescript">
// packages/wdio-spec-reporter/src/index.ts L96-106
onSuiteStart(suite: SuiteStats) {
this._suiteName = suite.file?.replace(process.cwd(), '')
this.printCurrentStats(suite)
this._suiteUids.add(suite.uid)
if (suite.type === 'feature') {
this._indents = 0
this._suiteIndents[suite.uid] = this._indents
} else {
this._suiteIndents[suite.uid] = ++this._indents
}
}
</syntaxhighlight>

The <code>getEventsToReport()</code> method filters events to show only the latest retry of each test and only failed hooks, avoiding duplicate output for retried tests:

<syntaxhighlight lang="typescript">
// packages/wdio-spec-reporter/src/index.ts L331-359
getEventsToReport(suite: SuiteStats) {
return [
...suite.hooksAndTests.reduce((accumulator, currentItem) => {
if (currentItem instanceof TestStats) {
const existingTestIndex = accumulator.findIndex(
(test) => test instanceof TestStats &&
test.fullTitle === currentItem.fullTitle
)
if (existingTestIndex === -1) {
accumulator.push(currentItem)
} else {
// Keep the test with the highest retry count
const existingTest = accumulator[existingTestIndex] as TestStats
if (currentItem.retries > existingTest.retries) {
accumulator.splice(existingTestIndex, 1, currentItem)
}
}
} else {
accumulator.push(currentItem)
}
return accumulator
}, []).filter((item) => {
return item.type === 'test' || Boolean(item.error)
})
]
}
</syntaxhighlight>

== Related Pages ==

* '''Implements:''' [[Principle:Webdriverio_Webdriverio_Test_Result_Reporting|Principle: Test_Result_Reporting]]
* '''Receives events from:''' [[Implementation:Webdriverio_Webdriverio_Mocha_BDD_Globals|Implementation: Mocha_BDD_Globals]]
* '''Orchestrated by:''' [[Implementation:Webdriverio_Webdriverio_Launcher_Class|Implementation: Launcher_Class]]

[[Category:Implementations]]

Implementation:Webdriverio Webdriverio Page Object Class Pattern

2026-09-27T10:53:25Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Webdriverio_Webdriverio_Page_Object_Class_Pattern}}
== Metadata ==
{| class="wikitable"
|-
! Field !! Value
|-
| '''Page ID''' || Page_Object_Class_Pattern
|-
| '''Wiki''' || Webdriverio_Webdriverio
|-
| '''Type''' || Implementation (Pattern Doc)
|-
| '''Domains''' || Testing, Design_Patterns
|-
| '''Knowledge Sources''' || Repo (https://github.com/webdriverio/webdriverio), Doc (https://webdriver.io/docs/pageobjects)
|-
| '''Related Principles''' || [[Principle:Webdriverio_Webdriverio_Page_Object_Model|Principle: Page_Object_Model]]
|}

== Overview ==

Interface specification for implementing the Page Object Model pattern in WebdriverIO test projects. The pattern consists of a base <code>Page</code> class with an <code>open(path)</code> method, and subclasses that define element getters using <code>$('selector')</code> and action methods. Page objects are exported as singletons. Tests import these singletons and call their methods.

== Description ==

The Page Object Class Pattern in WebdriverIO is implemented through a class inheritance hierarchy:

* A '''base Page class''' defines the <code>open(path)</code> method that delegates to <code>browser.url(path)</code>.
* '''Page-specific subclasses''' extend the base class and define element getters using <code>$('selector')</code> (without <code>await</code>) and action methods that compose element interactions.
* Each page module exports a '''singleton instance''' (<code>export default new PageClass()</code>).
* '''Test specs''' import these singletons and invoke their methods using <code>await</code>.

The getter pattern leverages WebdriverIO's '''ChainablePromiseElement''' -- calling <code>$('#username')</code> returns a thenable wrapper that resolves the element only when an action is performed. This means element lookups are always fresh and never stale.

== Source ==

{| class="wikitable"
|-
! File !! Lines !! Description
|-
| <code>examples/pageobject/pageobjects/page.js</code> || L1-5 || Base Page class with open(path) method
|-
| <code>examples/pageobject/pageobjects/form.page.js</code> || L1-24 || FormPage subclass with element getters and action methods
|-
| <code>examples/pageobject/specs/form.spec.js</code> || L1-26 || Test spec using FormPage singleton
|}

== Pattern Interface ==

=== Base Page Class ===

<syntaxhighlight lang="javascript">
// examples/pageobject/pageobjects/page.js
export default class Page {
open (path) {
return browser.url(path)
}
}
</syntaxhighlight>

'''Interface contract:'''
* '''Input:''' <code>path</code> (string) -- the URL path segment to navigate to.
* '''Output:''' Returns the result of <code>browser.url(path)</code>, a Promise that resolves when navigation completes.
* '''Behavior:''' Navigates the browser to the given path. Subclasses call <code>super.open('specific-path')</code> to navigate to their page.

=== Page Subclass ===

<syntaxhighlight lang="javascript">
// examples/pageobject/pageobjects/form.page.js
import Page from './page.js'

class FormPage extends Page {
/**
* define elements
*/
get username () { return $('#username') }
get password () { return $('#password') }
get submitButton () { return $('#login button[type=submit]') }
get flash () { return $('#flash') }

/**
* define or overwrite page methods
*/
open () {
return super.open('login')
}

submit () {
return this.submitButton.click()
}
}

export default new FormPage()
</syntaxhighlight>

'''Interface contract:'''
* '''Element getters:''' Each getter returns a <code>ChainablePromiseElement</code> via <code>$('selector')</code>. No <code>await</code> is used in the getter body.
** '''Input:''' None (getter property).
** '''Output:''' <code>ChainablePromiseElement</code> -- a thenable that resolves to a WebdriverIO Element when acted upon.
* '''Action methods:''' Compose element interactions into domain-specific actions (e.g., <code>submit()</code>).
** '''Input:''' Method-specific parameters (none for <code>submit()</code>).
** '''Output:''' Promise from the underlying WebdriverIO command.
* '''Singleton export:''' <code>export default new FormPage()</code> provides a shared instance.

=== Test Usage ===

<syntaxhighlight lang="javascript">
// examples/pageobject/specs/form.spec.js
import FormPage from '../pageobjects/form.page.js'

describe('auth form', () => {
it('should deny access with wrong creds', async () => {
await FormPage.open()
await FormPage.username.addValue('foo')
await FormPage.password.addValue('bar')
await FormPage.submit()

await expect(FormPage.flash).toHaveText(
expect.stringContaining('Your username is invalid!')
)
})

it('should allow access with correct creds', async () => {
await FormPage.open()
await FormPage.username.addValue('tomsmith')
await FormPage.password.addValue('SuperSecretPassword!')
await FormPage.submit()

await FormPage.flash.waitForDisplayed()
await expect(FormPage.flash).toHaveText(
expect.stringContaining('You logged into a secure area!')
)
})
})
</syntaxhighlight>

'''Test contract:'''
* '''Input:''' Page object method calls with test data.
* '''Output:''' Assertions on element state using <code>expect-webdriverio</code> matchers.
* '''Pattern:''' Open page, interact with elements, assert on outcomes.

== Directory Convention ==

{| class="wikitable"
|-
! Directory !! Purpose
|-
| <code>pageobjects/</code> || Page object classes (base + page-specific)
|-
| <code>specs/</code> || Test specification files
|-
| <code>wdio.conf.js</code> || WebdriverIO configuration at project root
|}

== I/O Contract Summary ==

{| class="wikitable"
|-
! Component !! Input !! Output
|-
| <code>Page.open(path)</code> || URL path string || Promise (navigation complete)
|-
| Element getter (<code>get username()</code>) || None || <code>ChainablePromiseElement</code>
|-
| Action method (<code>submit()</code>) || Method-specific params || Promise (action complete)
|-
| Singleton export || None || Page object instance
|}

== Usage Examples ==

=== Creating a new page object ===

<syntaxhighlight lang="javascript">
import Page from './page.js'

class DashboardPage extends Page {
get welcomeMessage () { return $('[data-testid="welcome"]') }
get logoutButton () { return $('button.logout') }
get navItems () { return $$('.nav-item') }

open () {
return super.open('dashboard')
}

logout () {
return this.logoutButton.click()
}
}

export default new DashboardPage()
</syntaxhighlight>

=== Using multiple page objects in a test ===

<syntaxhighlight lang="javascript">
import LoginPage from '../pageobjects/login.page.js'
import DashboardPage from '../pageobjects/dashboard.page.js'

describe('user flow', () => {
it('should login and see dashboard', async () => {
await LoginPage.open()
await LoginPage.username.addValue('admin')
await LoginPage.password.addValue('secret')
await LoginPage.submit()

await expect(DashboardPage.welcomeMessage).toBeDisplayed()
await expect(DashboardPage.welcomeMessage).toHaveTextContaining('Welcome')
})
})
</syntaxhighlight>

== Related Pages ==

* '''implements''' [[Principle:Webdriverio_Webdriverio_Page_Object_Model|Principle: Page_Object_Model]]

[[Category:Implementations]]

Implementation:Webdriverio Webdriverio Mocha BDD Globals

2026-09-27T10:53:24Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Webdriverio_Webdriverio_Mocha_BDD_Globals}}
== Overview ==

Wrapper documentation for Mocha BDD test syntax with WebdriverIO-injected globals for browser automation testing.

== Metadata ==

{| class="wikitable"
|-
! Field !! Value
|-
| '''Page Type''' || Implementation (Wrapper Doc)
|-
| '''Repository''' || [https://github.com/webdriverio/webdriverio webdriverio/webdriverio]
|-
| '''Packages''' || <code>@wdio/mocha-framework</code>, <code>@wdio/globals</code>
|-
| '''External Reference''' || [https://mochajs.org/ Mocha BDD Interface], [https://webdriver.io/docs/api/globals WDIO Globals API]
|-
| '''Related Principle''' || [[Principle:Webdriverio_Webdriverio_Test_Spec_Authoring|Principle: Test_Spec_Authoring]]
|}

== Description ==

When using the WDIO testrunner with <code>framework: 'mocha'</code>, the '''MochaAdapter''' sets up Mocha's BDD interface (<code>describe</code>, <code>it</code>, <code>before</code>, <code>after</code>, <code>beforeEach</code>, <code>afterEach</code>) and the '''<code>@wdio/globals</code>''' module injects <code>browser</code>, <code>$</code>, <code>$$</code>, and <code>expect</code> into the test worker scope. Tests use <code>describe</code>/<code>it</code> for structure and the globals for browser interaction without explicit imports.

The MochaAdapter wraps the standard Mocha test runner with WDIO-specific lifecycle management: it maps Mocha events to WDIO reporter events, wraps hook execution with <code>executeHooksWithArgs</code> for proper error handling, and provides UID-based tracking for nested suite/test hierarchies.

The globals module uses a '''Proxy-based''' delegation pattern. Each exported global (<code>browser</code>, <code>$</code>, <code>$$</code>, <code>expect</code>) is a Proxy that intercepts property access and delegates to the real object stored in a global <code>Map</code> (<code>globalThis._wdioGlobals</code>). This enables the globals to work across both ESM and CJS module boundaries within the same worker process.

== Source References ==

{| class="wikitable"
|-
! File !! Lines !! Description
|-
| <code>packages/wdio-mocha-framework/src/index.ts</code> || L30-288 || MochaAdapter class: initializes Mocha, loads specs, runs tests, emits events
|-
| <code>packages/wdio-mocha-framework/src/common.ts</code> || L151-176 || <code>setupEnv()</code>: configures BDD/TDD/QUnit interface and wraps global test methods
|-
| <code>packages/wdio-mocha-framework/src/constants.ts</code> || L1-30 || INTERFACES, TEST_INTERFACES, EVENTS mapping (Mocha events to WDIO events)
|-
| <code>packages/wdio-globals/src/index.ts</code> || L1-134 || Proxy-based globals: browser, driver, $, $$, expect, _setGlobal()
|}

== APIs ==

=== Mocha BDD Interface (injected globally) ===

{| class="wikitable"
|-
! Function !! Signature !! Description
|-
| <code>describe</code> || <code>describe(title: string, fn: () => void): void</code> || Define a test suite
|-
| <code>it</code> || <code>it(title: string, fn: () => Promise<void>): void</code> || Define an individual test case
|-
| <code>before</code> || <code>before(fn: () => Promise<void>): void</code> || Run once before all tests in a suite
|-
| <code>beforeEach</code> || <code>beforeEach(fn: () => Promise<void>): void</code> || Run before each test in a suite
|-
| <code>after</code> || <code>after(fn: () => Promise<void>): void</code> || Run once after all tests in a suite
|-
| <code>afterEach</code> || <code>afterEach(fn: () => Promise<void>): void</code> || Run after each test in a suite
|}

=== WDIO Globals (injected by testrunner) ===

{| class="wikitable"
|-
! Global !! Type !! Description
|-
| <code>browser</code> || <code>WebdriverIO.Browser</code> (Proxy) || The automated browser session; provides <code>url()</code>, <code>getTitle()</code>, <code>execute()</code>, etc.
|-
| <code>$</code> || <code>(selector: string) => WebdriverIO.Element</code> || Shorthand for <code>browser.$(selector)</code>; returns a single element
|-
| <code>$$</code> || <code>(selector: string) => WebdriverIO.Element[]</code> || Shorthand for <code>browser.$$(selector)</code>; returns multiple elements
|-
| <code>expect</code> || <code>ExpectWebdriverIO.Expect</code> || Assertion function with WDIO-specific matchers (toBeDisplayed, toHaveText, etc.)
|-
| <code>driver</code> || <code>WebdriverIO.Browser</code> (Proxy) || Alias for <code>browser</code>
|}

== Import ==

No import is needed -- globals are injected by the testrunner automatically. If explicit imports are desired (e.g., for IDE autocompletion outside the testrunner):

<syntaxhighlight lang="typescript">
import { browser, $, $$, expect } from '@wdio/globals'
</syntaxhighlight>

== Mocha Event Mapping ==

The MochaAdapter maps Mocha runner events to WDIO reporter events:

{| class="wikitable"
|-
! Mocha Event !! WDIO Event
|-
| <code>suite</code> || <code>suite:start</code>
|-
| <code>suite end</code> || <code>suite:end</code>
|-
| <code>test</code> || <code>test:start</code>
|-
| <code>test end</code> || <code>test:end</code>
|-
| <code>hook</code> || <code>hook:start</code>
|-
| <code>hook end</code> || <code>hook:end</code>
|-
| <code>pass</code> || <code>test:pass</code>
|-
| <code>fail</code> || <code>test:fail</code>
|-
| <code>retry</code> || <code>test:retry</code>
|-
| <code>pending</code> || <code>test:pending</code>
|}

== Supported UI Types ==

The MochaAdapter supports multiple Mocha interfaces, configured via <code>mochaOpts.ui</code>:

{| class="wikitable"
|-
! UI Type !! Test Functions !! Hook Functions
|-
| <code>bdd</code> (default) || <code>it</code>, <code>specify</code> || <code>before</code>, <code>beforeEach</code>, <code>after</code>, <code>afterEach</code>
|-
| <code>tdd</code> || <code>test</code> || <code>suiteSetup</code>, <code>setup</code>, <code>suiteTeardown</code>, <code>teardown</code>
|-
| <code>qunit</code> || <code>test</code> || <code>before</code>, <code>beforeEach</code>, <code>after</code>, <code>afterEach</code>
|}

== Usage Example ==

<syntaxhighlight lang="typescript">
// test/specs/login.spec.ts
// No imports needed -- describe, it, browser, $, $$, expect are all globals

describe('Login Page', () => {
before(async () => {
// Runs once before all tests in this describe block
await browser.url('/login')
})

it('should display the login form', async () => {
const form = await $('#login-form')
await expect(form).toBeDisplayed()
})

it('should accept valid credentials', async () => {
await $('#username').setValue('testuser')
await $('#password').setValue('secret')
await $('button[type="submit"]').click()

// WDIO-specific assertion matcher
await expect(browser).toHaveUrl(expect.stringContaining('/dashboard'))
})

it('should show all navigation links', async () => {
const links = await $$('nav a')
await expect(links).toBeElementsArrayOfSize({ gte: 3 })
})
})
</syntaxhighlight>

=== Configuration for Mocha framework ===

<syntaxhighlight lang="typescript">
// wdio.conf.ts
export const config: WebdriverIO.Config = {
framework: 'mocha',
mochaOpts: {
ui: 'bdd', // default
timeout: 60000, // test timeout in ms
retries: 1, // retry failed tests once
grep: 'login', // only run tests matching pattern
invert: false
},
// ...
}
</syntaxhighlight>

== Globals Proxy Mechanism ==

The <code>@wdio/globals</code> package uses a Proxy handler to lazily delegate access:

<syntaxhighlight lang="typescript">
// packages/wdio-globals/src/index.ts L27-42
function proxyHandler(key: SupportedGlobals) {
return {
get: (self: never, prop: any) => {
if (!globals.has(key)) {
throw new Error(
'No browser instance registered. Don\'t import @wdio/globals ' +
'outside of the WDIO testrunner context.'
)
}
const receiver = globals.get(key)
const field = receiver[prop]
return typeof field === 'function'
? field.bind(receiver)
: field
}
}
}

export const browser: WebdriverIO.Browser = new Proxy(
class Browser {} as unknown as WebdriverIO.Browser,
proxyHandler('browser')
)
</syntaxhighlight>

The testrunner registers actual implementations via the private <code>_setGlobal(key, value)</code> function, which stores the value in the shared <code>Map</code> and optionally sets it on <code>globalThis</code>.

== Related Pages ==

* '''Implements:''' [[Principle:Webdriverio_Webdriverio_Test_Spec_Authoring|Principle: Test_Spec_Authoring]]
* '''Results consumed by:''' [[Implementation:Webdriverio_Webdriverio_SpecReporter_Class|Implementation: SpecReporter_Class]]
* '''Executed by:''' [[Implementation:Webdriverio_Webdriverio_Launcher_Class|Implementation: Launcher_Class]]
* [[requires_env::Environment:Webdriverio_Webdriverio_Node_Runtime_Environment]]

[[Category:Implementations]]

Implementation:Webdriverio Webdriverio Launcher Class

2026-09-27T10:53:24Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Webdriverio_Webdriverio_Launcher_Class}}
== Overview ==

Concrete tool for orchestrating parallel test execution provided by the <code>@wdio/cli</code> package.

== Metadata ==

{| class="wikitable"
|-
! Field !! Value
|-
| '''Page Type''' || Implementation
|-
| '''Repository''' || [https://github.com/webdriverio/webdriverio webdriverio/webdriverio]
|-
| '''Package''' || <code>@wdio/cli</code>
|-
| '''Source File''' || <code>packages/wdio-cli/src/launcher.ts</code>, Lines L40-683
|-
| '''CLI Handler''' || <code>packages/wdio-cli/src/commands/run.ts</code>, Lines L17-272
|-
| '''Related Principle''' || [[Principle:Webdriverio_Webdriverio_Test_Execution_Orchestration|Principle: Test_Execution_Orchestration]]
|}

== Description ==

The <code>Launcher</code> class is the top-level test execution coordinator. It parses configuration via <code>ConfigParser</code>, initializes services (<code>onPrepare</code> hooks), creates a schedule of spec-to-capability assignments, spawns worker processes via the Runner (typically <code>LocalRunner</code>), monitors progress, handles retries, and collects results. It provides both CLI (<code>npx wdio run</code>) and programmatic interfaces.

The Launcher manages the full lifecycle:

# '''Initialization:''' Loads <code>tsx</code> for TypeScript support, initializes ConfigParser, validates config
# '''Service setup:''' Initializes launcher services, runs <code>onPrepare</code> hooks
# '''Driver setup:''' Pre-configures browser drivers via <code>setupDriver</code> and <code>setupBrowser</code>
# '''Scheduling:''' Creates a schedule mapping spec files to capabilities with instance limits
# '''Execution:''' Spawns workers, monitors completion, handles retries
# '''Cleanup:''' Runs <code>onComplete</code> hooks, shuts down the runner, returns exit code

== Source Reference ==

{| class="wikitable"
|-
! File !! Lines !! Description
|-
| <code>packages/wdio-cli/src/launcher.ts</code> || L40-683 || Launcher class with full orchestration logic
|-
| <code>packages/wdio-cli/src/commands/run.ts</code> || L17-272 || CLI command handler, tsconfig resolution, watch mode entry point
|-
| <code>packages/wdio-cli/src/watcher.ts</code> || -- || Watch mode file monitoring and re-execution
|-
| <code>packages/wdio-cli/src/interface.ts</code> || -- || CLInterface for terminal output management
|}

== Signature ==

<syntaxhighlight lang="typescript">
class Launcher {
public configParser: ConfigParser
public isMultiremote: boolean
public isParallelMultiremote: boolean
public runner?: Services.RunnerInstance
public interface?: CLInterface

constructor(
_configFilePath: string,
_args?: Partial<RunCommandArguments>,
_isWatchMode?: boolean
)

async initialize(): Promise<void>
async run(): Promise<undefined | number>
}
</syntaxhighlight>

== Import ==

<syntaxhighlight lang="typescript">
import Launcher from '@wdio/cli'
</syntaxhighlight>

== Inputs / Outputs Contract ==

=== Inputs ===

{| class="wikitable"
|-
! Parameter !! Type !! Required !! Description
|-
| <code>_configFilePath</code> || <code>string</code> || Yes || Path to the wdio.conf.ts/js configuration file
|-
| <code>_args</code> || <code>Partial<RunCommandArguments></code> || No || CLI overrides: spec, suite, watch, bail, baseUrl, logLevel, shard, etc.
|-
| <code>_isWatchMode</code> || <code>boolean</code> || No || Whether to run in watch mode (default: false)
|}

=== CLI Arguments (RunCommandArguments) ===

{| class="wikitable"
|-
! Argument !! Type !! Description
|-
| <code>--spec</code> || <code>string[]</code> || Run specific spec files (overrides config specs)
|-
| <code>--suite</code> || <code>string[]</code> || Run named suites defined in config
|-
| <code>--exclude</code> || <code>string[]</code> || Exclude spec files or suite names
|-
| <code>--watch</code> || <code>boolean</code> || Enable watch mode
|-
| <code>--bail</code> || <code>number</code> || Stop after N failures
|-
| <code>--baseUrl</code> || <code>string</code> || Override base URL
|-
| <code>--logLevel</code> || <code>string</code> || Override log level (trace/debug/info/warn/error/silent)
|-
| <code>--shard</code> || <code>string</code> || Shard spec: "current/total" (e.g., "1/4")
|-
| <code>--repeat</code> || <code>number</code> || Repeat specs N times (requires --spec or --suite)
|-
| <code>--coverage</code> || <code>boolean</code> || Enable coverage for browser runner
|}

=== Outputs ===

{| class="wikitable"
|-
! Output !! Type !! Description
|-
| Exit code || <code>number</code> || <code>0</code> = all tests passed, <code>1</code> = one or more failures
|-
| Worker processes || Child processes || Spawned via Runner for each spec-capability pair
|-
| Console output || via CLInterface || Progress indicators, reporter output, error messages
|}

== Execution Chain ==

The full execution chain from CLI to test execution:

<syntaxhighlight lang="text">
CLI (npx wdio run wdio.conf.ts)
-> handler() in packages/wdio-cli/src/commands/run.ts
-> new Launcher(configPath, params)
-> new ConfigParser(configPath, args)
-> launcher.run()
-> launcher.initialize()
-> load tsx for TypeScript support
-> configParser.initialize(args)
-> configParser.getConfig()
-> configParser.getCapabilities()
-> initializeLauncherService(config, caps)
-> runner.initialize()
-> runLauncherHook(config.onPrepare)
-> setupDriver(config, caps)
-> _runMode(config, caps)
-> build schedule (spec-to-capability mapping)
-> _runSpecs() loop
-> _startInstance(specs, caps, cid, rid, retries)
-> runLauncherHook(config.onWorkerStart)
-> runner.run({ cid, command, configFile, args, caps, specs })
-> worker.on('exit', _endHandler)
-> _endHandler()
-> handle retries if specFileRetries > 0
-> update schedule, spawn next spec
-> resolve when all complete
-> runner.shutdown()
-> runOnCompleteHook(config.onComplete)
-> return exitCode
</syntaxhighlight>

== Usage Example ==

=== Programmatic Usage ===

<syntaxhighlight lang="typescript">
import Launcher from '@wdio/cli'

// Basic test run
const launcher = new Launcher('./wdio.conf.ts')
const exitCode = await launcher.run()
console.log(`Tests completed with exit code: ${exitCode}`)

// With CLI overrides
const launcher2 = new Launcher('./wdio.conf.ts', {
spec: ['./test/specs/smoke/*.ts'],
baseUrl: 'http://staging.example.com',
logLevel: 'debug',
bail: 1
})
const exitCode2 = await launcher2.run()

// Access parsed config after initialization
await launcher2.initialize()
const config = launcher2.configParser.getConfig()
console.log(`Framework: ${config.framework}`)
console.log(`Max instances: ${config.maxInstances}`)
</syntaxhighlight>

=== CLI Handler Flow ===

<syntaxhighlight lang="typescript">
// packages/wdio-cli/src/commands/run.ts L161-177
export async function launch(wdioConfPath: string, params: Partial<RunCommandArguments>) {
const launcher = new Launcher(wdioConfPath, params)
return launcher.run()
.then((...args) => {
if (!process.env.WDIO_UNIT_TESTS) {
process.exit(...args)
}
})
.catch(err => {
console.error(err)
if (!process.env.WDIO_UNIT_TESTS) {
process.exit(1)
}
})
}
</syntaxhighlight>

== Scheduling Algorithm ==

The <code>_runSpecs()</code> method implements the scheduling loop:

<syntaxhighlight lang="typescript">
// packages/wdio-cli/src/launcher.ts L371-435 (simplified)
private _runSpecs(): boolean {
const config = this.configParser.getConfig()
while (this._getNumberOfRunningInstances() < config.maxInstances) {
const schedulableCaps = this._schedule
.filter((session) => {
// Bail check: stop if too many failures
if (config.bail > 0 && config.bail <= this._runnerFailed) return false
// Global maxInstances check
if (this._getNumberOfRunningInstances() >= config.maxInstances) return false
// Capability has available slots and pending specs
return session.availableInstances > 0 && session.specs.length > 0
})
// Load balance: run capability with fewest running instances first
.sort((a, b) => a.runningInstances - b.runningInstances)

if (schedulableCaps.length === 0) break

const specs = schedulableCaps[0].specs.shift()
this._startInstance(specs.files, schedulableCaps[0].caps, ...)
schedulableCaps[0].availableInstances--
schedulableCaps[0].runningInstances++
}
// Return true when all done
return this._getNumberOfRunningInstances() === 0 &&
this._getNumberOfSpecsLeft() === 0
}
</syntaxhighlight>

== Retry Handling ==

When a worker exits with a non-zero code and retries remain, the spec is re-queued:

<syntaxhighlight lang="typescript">
// packages/wdio-cli/src/launcher.ts L596-606
if (!passed && retries > 0) {
// specFileRetriesDeferred: true -> push (run after others)
// specFileRetriesDeferred: false -> unshift (run immediately)
const requeue = this.configParser.getConfig().specFileRetriesDeferred
? 'push' : 'unshift'
this._schedule[cid].specs[requeue]({
files: specs, retries: retries - 1, rid
})
}
</syntaxhighlight>

== Related Pages ==

* '''Implements:''' [[Principle:Webdriverio_Webdriverio_Test_Execution_Orchestration|Principle: Test_Execution_Orchestration]]
* '''Uses:''' [[Implementation:Webdriverio_Webdriverio_ConfigParser_Class|Implementation: ConfigParser_Class]]
* '''Executes:''' [[Implementation:Webdriverio_Webdriverio_Mocha_BDD_Globals|Implementation: Mocha_BDD_Globals]]
* '''Reports to:''' [[Implementation:Webdriverio_Webdriverio_SpecReporter_Class|Implementation: SpecReporter_Class]]
* [[requires_env::Environment:Webdriverio_Webdriverio_Node_Runtime_Environment]]

[[Category:Implementations]]

Implementation:Webdriverio Webdriverio ConfigParser Class

2026-09-27T10:53:23Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Webdriverio_Webdriverio_ConfigParser_Class}}
== Overview ==

Concrete tool for parsing and validating WebdriverIO configuration files provided by the <code>@wdio/config</code> package.

== Metadata ==

{| class="wikitable"
|-
! Field !! Value
|-
| '''Page Type''' || Implementation
|-
| '''Repository''' || [https://github.com/webdriverio/webdriverio webdriverio/webdriverio]
|-
| '''Package''' || <code>@wdio/config</code>
|-
| '''Source File''' || <code>packages/wdio-config/src/node/ConfigParser.ts</code>, Lines L42-563
|-
| '''Related Principle''' || [[Principle:Webdriverio_Webdriverio_Test_Configuration_Parsing|Principle: Test_Configuration_Parsing]]
|}

== Description ==

The <code>ConfigParser</code> class reads a <code>wdio.conf.ts</code> or <code>wdio.conf.js</code> configuration file, applies defaults from <code>DEFAULT_CONFIGS()</code>, merges CLI overrides, resolves spec file paths using glob patterns, validates the result, and provides the finalized configuration via <code>getConfig()</code>. It uses <code>deepmerge-ts</code> for merging nested objects with a custom merge strategy that deduplicates array entries for <code>services</code>, <code>reporters</code>, and <code>capabilities</code>.

The class follows a two-phase initialization pattern: the constructor performs synchronous setup (applying defaults and merging initial CLI config), while the asynchronous <code>initialize()</code> method loads the config file (which may require ESM dynamic import) and completes the merge. The <code>getConfig()</code> and <code>getCapabilities()</code> methods throw if called before initialization.

== Source Reference ==

{| class="wikitable"
|-
! File !! Lines !! Description
|-
| <code>packages/wdio-config/src/node/ConfigParser.ts</code> || L42-563 || Main ConfigParser class
|-
| <code>packages/wdio-config/src/constants.ts</code> || L7-89 || DEFAULT_CONFIGS, SUPPORTED_HOOKS, SUPPORTED_FILE_EXTENSIONS
|-
| <code>packages/wdio-config/src/node/FileSystemPathService.ts</code> || -- || PathService implementation for glob resolution
|}

== Signature ==

<syntaxhighlight lang="typescript">
class ConfigParser {
constructor(
configFilePath: string,
_initialConfig?: Partial<TestrunnerOptionsWithParameters>,
_pathService?: PathService
)
async initialize(object?: MergeConfig): Promise<void>
getConfig(): Required<WebdriverIO.Config>
getCapabilities(i?: number): Capabilities.TestrunnerCapabilities | Capabilities.RequestedStandaloneCapabilities
getSpecs(capSpecs?: Spec[], capExclude?: Spec[]): string[]
addService(service: Services.Hooks): void
static getFilePaths(patterns: Spec[], rootDir: string, findAndGlob?: PathService, hierarchyDepth?: number): Spec[]
}
</syntaxhighlight>

== Import ==

<syntaxhighlight lang="typescript">
import { ConfigParser } from '@wdio/config/node'
</syntaxhighlight>

== Inputs / Outputs Contract ==

=== Inputs ===

{| class="wikitable"
|-
! Parameter !! Type !! Required !! Description
|-
| <code>configFilePath</code> || <code>string</code> || Yes || Path to the wdio.conf.ts/js configuration file
|-
| <code>_initialConfig</code> || <code>Partial<TestrunnerOptionsWithParameters></code> || No || CLI argument overrides (spec, suite, watch, bail, coverage, etc.)
|-
| <code>_pathService</code> || <code>PathService</code> || No || Custom path service for glob resolution (defaults to FileSystemPathService)
|}

=== Outputs ===

{| class="wikitable"
|-
! Method !! Return Type !! Description
|-
| <code>getConfig()</code> || <code>Required<WebdriverIO.Config></code> || Fully-merged configuration object with all defaults applied
|-
| <code>getCapabilities()</code> || <code>Capabilities.TestrunnerCapabilities</code> || Merged capabilities array or multiremote object
|-
| <code>getSpecs()</code> || <code>string[]</code> || Resolved spec file paths filtered by exclude patterns, suite selection, and shard settings
|}

== Key Configuration Properties ==

The parsed configuration object includes these key properties:

{| class="wikitable"
|-
! Property !! Type !! Description
|-
| <code>specs</code> || <code>string[]</code> || Glob patterns for spec files
|-
| <code>capabilities</code> || <code>Capabilities.TestrunnerCapabilities</code> || Browser capability definitions
|-
| <code>framework</code> || <code>'mocha' | 'jasmine' | 'cucumber'</code> || Test framework adapter
|-
| <code>reporters</code> || <code>string[]</code> || Reporter plugins for output formatting
|-
| <code>services</code> || <code>string[]</code> || Service plugins (driver management, etc.)
|-
| <code>baseUrl</code> || <code>string</code> || Base URL for relative navigation commands
|-
| <code>logLevel</code> || <code>'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent'</code> || Logging verbosity
|-
| <code>maxInstances</code> || <code>number</code> || Maximum concurrent worker processes
|-
| <code>mochaOpts</code> || <code>MochaOpts</code> || Mocha framework options (timeout, ui, etc.)
|-
| <code>cucumberOpts</code> || <code>CucumberOpts</code> || Cucumber framework options
|-
| <code>shard</code> || <code>{ current: number, total: number }</code> || Shard configuration for distributed execution
|}

== Usage Example ==

<syntaxhighlight lang="typescript">
import { ConfigParser } from '@wdio/config/node'

// Create parser with config file path and CLI overrides
const configParser = new ConfigParser('./wdio.conf.ts', {
spec: ['./test/specs/login.ts'],
baseUrl: 'http://staging.example.com',
logLevel: 'debug'
})

// Initialize (loads config file asynchronously)
await configParser.initialize()

// Access the finalized configuration
const config = configParser.getConfig()
console.log(config.framework) // 'mocha'
console.log(config.baseUrl) // 'http://staging.example.com' (CLI override applied)
console.log(config.logLevel) // 'debug' (CLI override applied)

// Get resolved spec file paths
const specs = configParser.getSpecs()
console.log(specs) // ['/absolute/path/to/test/specs/login.ts']

// Get capabilities
const caps = configParser.getCapabilities()
console.log(caps) // [{ browserName: 'chrome' }]
</syntaxhighlight>

=== Programmatic usage in the Launcher ===

<syntaxhighlight lang="typescript">
// The Launcher class creates a ConfigParser internally
// packages/wdio-cli/src/launcher.ts L59-64
class Launcher {
public configParser: ConfigParser
constructor(configFilePath: string, args: Partial<RunCommandArguments> = {}) {
this.configParser = new ConfigParser(configFilePath, args)
}
async run(): Promise<number | undefined> {
await this.configParser.initialize(this._args)
const config = this.configParser.getConfig()
// ... orchestrate test execution using config
}
}
</syntaxhighlight>

== Internal Behavior ==

The merge strategy uses <code>deepmergeCustom</code> from <code>deepmerge-ts</code> with special handling for arrays:

<syntaxhighlight lang="typescript">
// packages/wdio-config/src/node/ConfigParser.ts L186-195
const customDeepMerge = deepmergeCustom({
mergeArrays: ([oldValue, newValue], utils, meta) => {
const key = meta?.key as KeyWithMergeDuplication
if (meta && MERGE_DUPLICATION.includes(key)) {
// For 'services', 'reporters', 'capabilities':
// filter non-object entries from old, merge with new, deduplicate
const origWithoutObjectEntries = oldValue.filter(
(value) => typeof value !== 'object'
)
return Array.from(new Set(deepmerge(newValue, origWithoutObjectEntries)))
}
return utils.actions.defaultMerge
}
})
</syntaxhighlight>

Spec resolution supports both flat string arrays and grouped arrays (string[][]) for parallel execution of related specs. The <code>getSpecs()</code> method handles suite selection (<code>--suite</code>), exclusion patterns (<code>--exclude</code>), sharding (<code>--shard</code>), and repetition (<code>--repeat</code>).

== Related Pages ==

* '''Implements:''' [[Principle:Webdriverio_Webdriverio_Test_Configuration_Parsing|Principle: Test_Configuration_Parsing]]
* '''Used by:''' [[Implementation:Webdriverio_Webdriverio_Launcher_Class|Implementation: Launcher_Class]]
* [[requires_env::Environment:Webdriverio_Webdriverio_Node_Runtime_Environment]]
* [[uses_heuristic::Heuristic:Webdriverio_Webdriverio_Default_Timeout_Configuration]]

[[Category:Implementations]]

Implementation:Webdriverio Webdriverio Cloud Capabilities Config

2026-09-27T10:53:22Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Webdriverio_Webdriverio_Cloud_Capabilities_Config}}
== Metadata ==
{| class="wikitable"
|-
! Field !! Value
|-
| '''Page ID''' || Cloud_Capabilities_Config
|-
| '''Wiki''' || Webdriverio_Webdriverio
|-
| '''Type''' || Implementation (API Doc)
|-
| '''Domains''' || Testing, Cloud, Configuration
|-
| '''Knowledge Sources''' || Repo (https://github.com/webdriverio/webdriverio), Doc (https://webdriver.io/docs/browserstack-service), Doc (https://www.browserstack.com/docs/automate/selenium/getting-started/nodejs)
|-
| '''Related Principles''' || [[Principle:Webdriverio_Webdriverio_Cloud_Capabilities_Definition|Principle: Cloud_Capabilities_Definition]]
|}

== Overview ==

Concrete configuration interface for cloud provider capabilities provided by WDIO cloud service packages. Cloud capabilities are defined using W3C capability objects augmented with vendor extensions. The <code>BrowserstackConfig</code>, <code>SauceServiceConfig</code>, and <code>TestingbotOptions</code> interfaces define the provider-specific configuration. These are used in the <code>capabilities</code> array and <code>services</code> configuration in <code>wdio.conf.ts</code>.

== Description ==

Cloud capabilities are configured at two levels:

# '''Capabilities level''' -- W3C capability objects with vendor-namespaced extensions (<code>bstack:options</code>, <code>sauce:options</code>, <code>tb:options</code>) define per-session browser and platform settings.
# '''Service level''' -- Service configuration interfaces (<code>BrowserstackConfig</code>, <code>SauceServiceConfig</code>, <code>TestingbotOptions</code>) define cross-session settings like local tunneling, session naming behavior, test reporting, and accessibility automation.

== Source ==

{| class="wikitable"
|-
! File !! Lines !! Description
|-
| <code>packages/wdio-browserstack-service/src/types.ts</code> || L62-212 || <code>BrowserstackConfig</code> service configuration interface
|-
| <code>packages/wdio-sauce-service/src/types.ts</code> || L4-51 || <code>SauceServiceConfig</code> service configuration interface
|-
| <code>packages/wdio-testingbot-service/src/types.ts</code> || L49-60 || <code>TestingbotOptions</code> service configuration interface
|}

== BrowserStack Configuration ==

=== BrowserstackConfig Interface ===

<syntaxhighlight lang="typescript">
// packages/wdio-browserstack-service/src/types.ts (L62-212)
export interface BrowserstackConfig {
buildIdentifier?: string; // Unique build ID (supports ${BUILD_NUMBER}, ${DATE_TIME})
testObservability?: boolean; // Enable Test Reporting and Analytics (default: true) [deprecated]
testReporting?: boolean; // Enable Test Reporting and Analytics (default: true)
testObservabilityOptions?: TestObservabilityOptions; // Reporting options [deprecated]
testReportingOptions?: TestReportingOptions; // Reporting options
percy?: boolean; // Enable Percy visual testing (default: false)
percyCaptureMode?: string; // Screenshot capture mode: 'auto'|'click'|'testcase'|'screenshot'|'manual'
accessibility?: boolean; // Enable Accessibility Automation (default: false)
accessibilityOptions?: { [key: string]: unknown }; // Accessibility config
app?: string | AppConfig; // App file path or hashed ID for app testing
browserstackLocal?: boolean; // Enable local tunnel (default: false)
forcedStop?: boolean; // Kill tunnel without waiting for callback (default: false)
opts?: Partial<BSOptions>; // BrowserStack Local binary options
preferScenarioName?: boolean; // Use Cucumber Scenario name as session name (default: false)
sessionNameFormat?: Function; // Custom session name formatter
sessionNameOmitTestTitle?: boolean; // Omit test title from session name (default: false)
sessionNamePrependTopLevelSuiteTitle?: boolean; // Prepend suite title (default: false)
setSessionName?: boolean; // Auto-set session name (default: true)
setSessionStatus?: boolean; // Auto-set session status (default: true)
turboScale?: boolean; // Enable TurboScale grid (default: false)
selfHeal?: boolean; // Enable self-healing selectors
testOrchestrationOptions?: TestOrchestrationOptions; // Smart test selection config
}
</syntaxhighlight>

=== BrowserStack Capability Extensions ===

'''I/O Contract -- <code>bstack:options</code> namespace:'''
{| class="wikitable"
|-
! Property !! Type !! Description
|-
| <code>os</code> || <code>string</code> || Operating system (e.g., <code>'Windows'</code>, <code>'OS X'</code>)
|-
| <code>osVersion</code> || <code>string</code> || OS version (e.g., <code>'11'</code>, <code>'Ventura'</code>)
|-
| <code>buildName</code> || <code>string</code> || Build name for grouping sessions in dashboard
|-
| <code>sessionName</code> || <code>string</code> || Session name for individual test identification
|-
| <code>debug</code> || <code>boolean</code> || Enable visual logs (screenshots at each step)
|-
| <code>video</code> || <code>boolean</code> || Enable video recording of the session
|-
| <code>networkLogs</code> || <code>boolean</code> || Enable network traffic logging
|-
| <code>consoleLogs</code> || <code>string</code> || Console log level (<code>'disable'</code>, <code>'errors'</code>, <code>'warnings'</code>, <code>'info'</code>, <code>'verbose'</code>)
|-
| <code>local</code> || <code>boolean</code> || Route traffic through BrowserStack Local tunnel
|-
| <code>localIdentifier</code> || <code>string</code> || Tunnel identifier for multiple concurrent tunnels
|}

== Sauce Labs Configuration ==

=== SauceServiceConfig Interface ===

<syntaxhighlight lang="typescript">
// packages/wdio-sauce-service/src/types.ts (L4-51)
export interface SauceServiceConfig {
maxErrorStackLength?: number; // Max error stack lines sent to Sauce Labs
tunnelName?: string; // Sauce Connect tunnel identifier
tunnelOwner?: string; // Tunnel owner account
sauceConnect?: boolean; // Enable Sauce Connect tunnel (default: false)
sauceConnectOpts?: SauceConnectOptions; // Sauce Connect binary options
uploadLogs?: boolean; // Upload WDIO logs to Sauce Labs (default: true)
setJobName?: Function; // Custom job name formatter
}
</syntaxhighlight>

=== Sauce Labs Capability Extensions ===

'''I/O Contract -- <code>sauce:options</code> namespace:'''
{| class="wikitable"
|-
! Property !! Type !! Description
|-
| <code>build</code> || <code>string</code> || Build identifier for grouping jobs
|-
| <code>name</code> || <code>string</code> || Test/job name
|-
| <code>tags</code> || <code>string[]</code> || Tags for filtering and searching jobs
|-
| <code>tunnelName</code> || <code>string</code> || Sauce Connect tunnel identifier
|-
| <code>tunnelOwner</code> || <code>string</code> || Owner of the shared tunnel
|-
| <code>screenResolution</code> || <code>string</code> || Browser window resolution (e.g., <code>'1920x1080'</code>)
|-
| <code>extendedDebugging</code> || <code>boolean</code> || Enable extended debugging features
|}

== TestingBot Configuration ==

=== TestingbotOptions Interface ===

<syntaxhighlight lang="typescript">
// packages/wdio-testingbot-service/src/types.ts (L49-60)
export interface TestingbotOptions {
tbTunnel?: boolean; // Enable TestingBot Tunnel (default: false)
tbTunnelOpts?: TunnelLauncherOptions; // Tunnel binary options
}
</syntaxhighlight>

=== TestingBot Capability Extensions ===

'''I/O Contract -- <code>tb:options</code> namespace:'''
{| class="wikitable"
|-
! Property !! Type !! Description
|-
| <code>tunnel-identifier</code> || <code>string</code> || Tunnel identifier for routing traffic
|-
| <code>build</code> || <code>string</code> || Build name for grouping sessions
|-
| <code>name</code> || <code>string</code> || Test session name
|}

== Full Example: BrowserStack Capabilities Configuration ==

<syntaxhighlight lang="typescript">
// wdio.conf.ts
export const config: WebdriverIO.Config = {
user: process.env.BROWSERSTACK_USERNAME,
key: process.env.BROWSERSTACK_ACCESS_KEY,

services: [['browserstack', {
browserstackLocal: false,
testReporting: true,
testReportingOptions: {
buildName: 'My Project - CI Build',
projectName: 'My Project'
},
setSessionName: true,
setSessionStatus: true
}]],

capabilities: [
// Chrome on Windows 11
{
browserName: 'chrome',
browserVersion: 'latest',
'bstack:options': {
os: 'Windows',
osVersion: '11',
buildName: 'Regression Suite',
sessionName: 'Chrome Windows Test',
debug: true,
video: true,
networkLogs: true
}
},
// Safari on macOS
{
browserName: 'safari',
browserVersion: 'latest',
'bstack:options': {
os: 'OS X',
osVersion: 'Ventura',
buildName: 'Regression Suite',
sessionName: 'Safari macOS Test',
debug: true,
video: true
}
},
// Firefox on Windows 10
{
browserName: 'firefox',
browserVersion: 'latest',
'bstack:options': {
os: 'Windows',
osVersion: '10',
buildName: 'Regression Suite',
sessionName: 'Firefox Windows Test'
}
}
]
}
</syntaxhighlight>

== Full Example: Sauce Labs Capabilities Configuration ==

<syntaxhighlight lang="typescript">
// wdio.conf.ts
export const config: WebdriverIO.Config = {
user: process.env.SAUCE_USERNAME,
key: process.env.SAUCE_ACCESS_KEY,

services: [['sauce', {
sauceConnect: false,
uploadLogs: true
}]],

capabilities: [{
browserName: 'chrome',
browserVersion: 'latest',
platformName: 'Windows 11',
'sauce:options': {
build: 'CI Build #42',
name: 'Login Flow Tests',
tags: ['regression', 'login'],
screenResolution: '1920x1080',
extendedDebugging: true
}
}]
}
</syntaxhighlight>

== Usage Examples ==

=== Multi-browser matrix ===

<syntaxhighlight lang="typescript">
capabilities: [
{ browserName: 'chrome', 'bstack:options': { os: 'Windows', osVersion: '11' } },
{ browserName: 'firefox', 'bstack:options': { os: 'Windows', osVersion: '11' } },
{ browserName: 'safari', 'bstack:options': { os: 'OS X', osVersion: 'Ventura' } },
{ browserName: 'edge', 'bstack:options': { os: 'Windows', osVersion: '11' } }
]
</syntaxhighlight>

=== Mobile device testing ===

<syntaxhighlight lang="typescript">
capabilities: [{
browserName: 'safari',
'bstack:options': {
deviceName: 'iPhone 14',
osVersion: '16',
realMobile: true,
buildName: 'Mobile Tests'
}
}]
</syntaxhighlight>

== Related Pages ==

* '''implements''' [[Principle:Webdriverio_Webdriverio_Cloud_Capabilities_Definition|Principle: Cloud_Capabilities_Definition]]
* [[requires_env::Environment:Webdriverio_Webdriverio_Cloud_Service_Credentials]]

[[Category:Implementations]]

Implementation:Webdriverio Webdriverio Browser Runner Render

2026-09-27T10:53:22Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Webdriverio_Webdriverio_Browser_Runner_Render}}
== Metadata ==
{| class="wikitable"
|-
! Field !! Value
|-
| '''Page ID''' || Browser_Runner_Render
|-
| '''Wiki''' || Webdriverio_Webdriverio
|-
| '''Type''' || Implementation (Wrapper Doc)
|-
| '''Domains''' || Testing, Component_Testing, Frontend
|-
| '''Knowledge Sources''' || Repo (https://github.com/webdriverio/webdriverio), Doc (https://webdriver.io/docs/component-testing)
|-
| '''Related Principles''' || [[Principle:Webdriverio_Webdriverio_Component_Test_Rendering|Principle: Component_Test_Rendering]]
|}

== Overview ==

Wrapper documentation for component rendering in WebdriverIO browser runner tests using framework testing libraries. When using the WDIO browser runner, components are rendered using framework-specific testing libraries (e.g., <code>@testing-library/vue</code> for Vue, <code>@testing-library/react</code> for React). The <code>render()</code> function mounts a component into the browser DOM. After rendering, <code>$()</code> and <code>$$()</code> query the component's DOM, and <code>expect()</code> validates output. The browser runner includes mock/spy support via <code>@vitest/spy</code>.

== Description ==

The browser runner render flow involves three stages:

# '''Rendering''' -- The framework-specific <code>render()</code> function mounts a component into the real browser DOM with specified props and slots.
# '''Querying''' -- Testing Library query utilities (<code>getByText</code>, <code>getByRole</code>, etc.) or WebdriverIO selectors (<code>$()</code>, <code>$$()</code>) locate elements in the rendered output.
# '''Asserting''' -- WebdriverIO's <code>expect()</code> function with <code>expect-webdriverio</code> matchers validates the component's output and behavior.

The browser runner's expect system is implemented in <code>packages/wdio-browser-runner/src/browser/expect.ts</code>, which creates matcher factories that serialize assertions and send them to the Node.js worker process for evaluation. The mocking system in <code>packages/wdio-browser-runner/src/browser/spy.ts</code> re-exports <code>@vitest/spy</code> and provides <code>mock()</code>, <code>unmock()</code>, and <code>mocked()</code> functions.

== Source ==

{| class="wikitable"
|-
! File !! Lines !! Description
|-
| <code>examples/wdio/vite-vue-example/src/components/HelloWorld.test.ts</code> || L1-27 || Full Vue component test example
|-
| <code>packages/wdio-browser-runner/src/browser/expect.ts</code> || L1-50+ || Browser-side expect matcher factory
|-
| <code>packages/wdio-browser-runner/src/browser/spy.ts</code> || L1-55 || Mock/spy module (re-exports @vitest/spy, provides mock/unmock)
|-
| <code>examples/wdio/vite-vue-example/src/components/HelloWorld.vue</code> || L1-38 || Vue component under test
|}

== APIs ==

=== render(Component, options?) ===

Mounts a UI component into the browser DOM. Provided by the framework-specific testing library.

'''For Vue:'''
<syntaxhighlight lang="typescript">
import { render } from '@testing-library/vue'
import Component from './MyComponent.vue'

const { getByText, getByRole, container } = render(Component, {
props: { msg: 'Hello' },
slots: { default: '<span>slot content</span>' }
})
</syntaxhighlight>

'''I/O Contract:'''
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>Component</code> || Framework component || The component to render
|-
| <code>options.props</code> || Object (optional) || Props to pass to the component
|-
| <code>options.slots</code> || Object (optional) || Slot content (Vue-specific)
|-
| '''Returns''' || RenderResult || Object with query utilities: <code>getByText</code>, <code>getByRole</code>, <code>container</code>, etc.
|}

=== $('selector') / $$('selector') ===

WebdriverIO global selectors for querying the rendered DOM. Can also wrap DOM elements returned by Testing Library queries.

<syntaxhighlight lang="typescript">
// Query by CSS selector
const button = await $('button.submit')

// Wrap a Testing Library query result
const { getByText } = render(Component)
const element = await $(getByText('Click me'))
</syntaxhighlight>

'''I/O Contract:'''
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>selector</code> || string or HTMLElement || CSS selector string or DOM element
|-
| '''Returns''' || <code>ChainablePromiseElement</code> || WebdriverIO element wrapper with full command API
|}

=== expect(element).matcher() ===

Assertion function using <code>expect-webdriverio</code> matchers. The browser runner's expect implementation serializes matcher calls and evaluates them in the Node.js worker process.

<syntaxhighlight lang="typescript">
await expect(button).toHaveText('count is 2')
await expect($('.message')).toBeDisplayed()
await expect($('input')).toHaveValue('test')
</syntaxhighlight>

=== mock(path, factory?) / unmock(moduleName) ===

Module mocking functions provided by the browser runner's spy module.

<syntaxhighlight lang="typescript">
import { fn, spyOn } from '@wdio/browser-runner'

// Mock a module with a factory
mock('./api.js', () => ({
fetchData: fn().mockResolvedValue({ items: [] })
}))

// Remove a mock
unmock('./api.js')
</syntaxhighlight>

'''I/O Contract:'''
{| class="wikitable"
|-
! Function !! Parameters !! Description
|-
| <code>mock(path, factory?)</code> || path: string, factory: function (optional) || Replaces module imports with factory return value
|-
| <code>unmock(moduleName)</code> || moduleName: string || Removes a previously registered mock
|-
| <code>mocked(item)</code> || item: T || Type utility for casting to MaybeMocked<T>
|-
| <code>fn()</code> || None || Creates a mock function (from @vitest/spy)
|-
| <code>spyOn(obj, method)</code> || obj: object, method: string || Creates a spy on an object method (from @vitest/spy)
|}

== Full Example: Vue Component Test ==

'''Component under test (<code>HelloWorld.vue</code>):'''

<syntaxhighlight lang="html">
<script setup lang="ts">
import { ref } from 'vue'

defineProps<{ msg: string }>()

const count = ref(0)
</script>

<template>
<h1>{{ msg }}</h1>
<div class="card">
<button type="button" @click="count++">count is {{ count }}</button>
</div>
</template>
</syntaxhighlight>

'''Test file (<code>HelloWorld.test.ts</code>):'''

<syntaxhighlight lang="typescript">
import { expect, $ } from '@wdio/globals'
import { render } from '@testing-library/vue'

import * as matchers from '@testing-library/jest-dom/matchers'
expect.extend(matchers as any)

import Component from './HelloWorld.vue'

describe('Vue Component Tests', () => {
it('should do something cool', async () => {
// The render method returns a collection of utilities to query your component.
const { getByText } = render(Component)

// getByText returns the first matching node for the provided text, and
// throws an error if no elements match or if more than one match is found.
getByText('count is 0')

const button = await $(getByText('count is 0'))

// Dispatch a native click event to our button element.
await button.click()
await button.click()

getByText('count is 2')
await expect(button).toHaveText('count is 2')
})
})
</syntaxhighlight>

'''Test flow:'''
# Import <code>render</code> from <code>@testing-library/vue</code> and the component.
# Call <code>render(Component)</code> to mount the component in the real browser DOM.
# Use <code>getByText('count is 0')</code> to verify initial render text.
# Wrap the DOM element with <code>$(getByText(...))</code> to get a WebdriverIO element.
# Call <code>.click()</code> twice to simulate user interaction.
# Assert the button text changed to <code>'count is 2'</code> using <code>toHaveText()</code>.

== Import Summary ==

<syntaxhighlight lang="typescript">
// WebdriverIO globals (available in browser runner context)
import { expect, $ } from '@wdio/globals'

// Framework-specific render function
import { render } from '@testing-library/vue' // Vue
import { render } from '@testing-library/react' // React
import { render } from '@testing-library/svelte' // Svelte

// Mocking (from browser runner)
import { fn, spyOn, mock, unmock } from '@wdio/browser-runner'
</syntaxhighlight>

== Related Pages ==

* '''implements''' [[Principle:Webdriverio_Webdriverio_Component_Test_Rendering|Principle: Component_Test_Rendering]]

[[Category:Implementations]]

Implementation:Webdriverio Webdriverio Browser Runner Config

2026-09-27T10:53:21Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Webdriverio_Webdriverio_Browser_Runner_Config}}
== Metadata ==
{| class="wikitable"
|-
! Field !! Value
|-
| '''Page ID''' || Browser_Runner_Config
|-
| '''Wiki''' || Webdriverio_Webdriverio
|-
| '''Type''' || Implementation (API Doc)
|-
| '''Domains''' || Testing, Configuration, Frontend
|-
| '''Knowledge Sources''' || Repo (https://github.com/webdriverio/webdriverio), Doc (https://webdriver.io/docs/component-testing/vue)
|-
| '''Related Principles''' || [[Principle:Webdriverio_Webdriverio_Browser_Runner_Configuration|Principle: Browser_Runner_Configuration]]
|}

== Overview ==

Concrete tool for configuring the Vite-based browser runner provided by the <code>@wdio/browser-runner</code> package. The browser runner configuration is specified as the <code>runner</code> property in <code>wdio.conf.ts</code>. It configures Vite dev server settings, framework presets, and project paths. The <code>PRESET_DEPENDENCIES</code> constant maps framework names to their required Vite plugins. The <code>DEFAULT_VITE_CONFIG</code> provides sensible defaults for testing.

== Description ==

The browser runner configuration controls how Vite serves test files to the browser. It consists of three layers:

# '''User configuration''' -- The <code>BrowserRunnerOptions</code> interface in <code>wdio.conf.ts</code> specifying preset, viteConfig, rootDir, and other options.
# '''Preset resolution''' -- The <code>PRESET_DEPENDENCIES</code> constant that maps preset names to Vite plugin packages and their export names.
# '''Default Vite config''' -- The <code>DEFAULT_VITE_CONFIG</code> that provides sensible defaults including CJS dependency optimization, source maps, and logging.

== Source ==

{| class="wikitable"
|-
! File !! Lines !! Description
|-
| <code>packages/wdio-browser-runner/src/types.ts</code> || L75-125 || <code>BrowserRunnerOptions</code> interface definition
|-
| <code>packages/wdio-browser-runner/src/vite/constants.ts</code> || L14-31 || <code>PRESET_DEPENDENCIES</code> mapping framework presets to Vite plugins
|-
| <code>packages/wdio-browser-runner/src/vite/constants.ts</code> || L33-80 || <code>DEFAULT_VITE_CONFIG</code> with optimized defaults
|-
| <code>packages/wdio-browser-runner/src/vite/frameworks/index.ts</code> || L7-26 || <code>updateViteConfig</code> function for framework-specific optimizations
|-
| <code>packages/wdio-browser-runner/src/types.ts</code> || L13 || <code>FrameworkPreset</code> type definition
|-
| <code>examples/wdio/vite-vue-example/wdio.conf.ts</code> || L1-300 || Full example wdio.conf.ts with browser runner
|}

== Configuration Format ==

The browser runner is configured via the <code>runner</code> property in <code>wdio.conf.ts</code>:

<syntaxhighlight lang="typescript">
runner: ['browser', BrowserRunnerOptions]
</syntaxhighlight>

=== BrowserRunnerOptions Interface ===

<syntaxhighlight lang="typescript">
// packages/wdio-browser-runner/src/types.ts
export interface BrowserRunnerOptions {
rootDir?: string // Project root directory (default: process.cwd())
preset?: FrameworkPreset // Framework preset for auto-configuration
viteConfig?: string | InlineConfig | ((env: ConfigEnv) => InlineConfig | Promise<InlineConfig>)
headless?: boolean // Run in headless mode (default: false, true in CI)
coverage?: CoverageOptions // Test coverage settings
automock?: boolean // Auto-mock dependencies in automockDir (default: true)
automockDir?: string // Path to auto-mock directory (default: ./__mocks__)
host?: string // Custom hostname for remote grids (default: http://0.0.0.0)
}
</syntaxhighlight>

'''I/O Contract:'''
{| class="wikitable"
|-
! Property !! Type !! Default !! Description
|-
| <code>rootDir</code> || <code>string</code> || <code>process.cwd()</code> || Project root for file resolution
|-
| <code>preset</code> || <code>FrameworkPreset</code> || <code>undefined</code> || Auto-configures Vite plugin for framework
|-
| <code>viteConfig</code> || <code>string | InlineConfig | Function</code> || <code>undefined</code> || Custom Vite configuration (merged with defaults)
|-
| <code>headless</code> || <code>boolean</code> || <code>false</code> (CI: <code>true</code>) || Headless browser mode
|-
| <code>coverage</code> || <code>CoverageOptions</code> || <code>undefined</code> || Istanbul coverage settings
|-
| <code>automock</code> || <code>boolean</code> || <code>true</code> || Auto-mock from <code>automockDir</code>
|-
| <code>automockDir</code> || <code>string</code> || <code>./__mocks__</code> || Directory for auto-mock files
|-
| <code>host</code> || <code>string</code> || <code>http://0.0.0.0</code> || Server hostname for remote grids
|}

=== FrameworkPreset Type ===

<syntaxhighlight lang="typescript">
// packages/wdio-browser-runner/src/types.ts
export type FrameworkPreset = 'react' | 'preact' | 'vue' | 'svelte' | 'lit' | 'solid' | 'stencil'
</syntaxhighlight>

=== PRESET_DEPENDENCIES Mapping ===

<syntaxhighlight lang="typescript">
// packages/wdio-browser-runner/src/vite/constants.ts
export const PRESET_DEPENDENCIES: Record<FrameworkPreset, [string, string, unknown] | undefined> = {
react: ['@vitejs/plugin-react', 'default', {
babel: {
assumptions: { setPublicClassFields: true },
parserOpts: { plugins: ['decorators-legacy', 'classProperties'] }
}
}],
preact: ['@preact/preset-vite', 'default', undefined],
vue: ['@vitejs/plugin-vue', 'default', undefined],
svelte: ['@sveltejs/vite-plugin-svelte', 'svelte', undefined],
solid: ['vite-plugin-solid', 'default', undefined],
stencil: undefined,
lit: undefined
}
</syntaxhighlight>

'''Mapping structure:''' Each entry is a tuple <code>[packageName, exportName, pluginOptions]</code> or <code>undefined</code> (for frameworks that do not need a Vite plugin).

=== DEFAULT_VITE_CONFIG ===

<syntaxhighlight lang="typescript">
// packages/wdio-browser-runner/src/vite/constants.ts
export const DEFAULT_VITE_CONFIG: Partial<InlineConfig> = {
configFile: false,
server: { host: 'localhost' },
logLevel: 'info',
plugins: [topLevelAwait()],
build: {
sourcemap: 'inline',
commonjsOptions: { include: [/node_modules/] }
},
optimizeDeps: {
include: [
'expect', 'minimatch', 'css-shorthand-properties', 'lodash.merge',
'lodash.zip', 'ws', 'lodash.clonedeep', 'lodash.pickby',
'lodash.flattendeep', 'aria-query', 'grapheme-splitter',
'css-value', 'rgb2hex', 'p-iteration', 'deepmerge-ts',
'jest-util', 'jest-matcher-utils', 'split2'
],
esbuildOptions: {
logLevel: 'silent',
define: { global: 'globalThis' },
plugins: [
esbuildCommonjs(['@testing-library/vue']),
codeFrameFix()
]
}
}
}
</syntaxhighlight>

== Framework-Specific Optimizations ==

The <code>updateViteConfig</code> function in <code>packages/wdio-browser-runner/src/vite/frameworks/index.ts</code> auto-detects and applies optimizations for specific project types:

<syntaxhighlight lang="typescript">
// packages/wdio-browser-runner/src/vite/frameworks/index.ts
export default async function updateViteConfig (
options: WebdriverIO.BrowserRunnerOptions,
config: WebdriverIO.Config
) {
const optimizations: InlineConfig = {}
const rootDir = options.rootDir || config.rootDir || process.cwd()

if (await isNuxtFramework(rootDir)) {
Object.assign(optimizations, await optimizeForNuxt(options, config))
}
if (await isUsingTailwindCSS(rootDir)) {
Object.assign(optimizations, await optimizeForTailwindCSS(rootDir))
}
if (await isUsingStencilJS(rootDir, options)) {
Object.assign(optimizations, await optimizeForStencil(rootDir))
}

return optimizations
}
</syntaxhighlight>

== Full Example: wdio.conf.ts for Vue Component Testing ==

<syntaxhighlight lang="typescript">
// examples/wdio/vite-vue-example/wdio.conf.ts
import url from 'node:url'
import viteConfig from './vite.config.js'

const __dirname = url.fileURLToPath(new URL('.', import.meta.url))

export const config: WebdriverIO.Config = {
runner: ['browser', {
viteConfig,
rootDir: __dirname
}],
specs: ['./src/**/*.test.ts'],
maxInstances: 10,
capabilities: [{
maxInstances: 5,
browserName: 'chrome'
}],
logLevel: 'info',
bail: 0,
baseUrl: '',
waitforTimeout: 10000,
connectionRetryTimeout: 120000,
connectionRetryCount: 3,
services: [],
framework: 'mocha',
reporters: ['spec'],
mochaOpts: {
ui: 'bdd',
timeout: 60000
}
}
</syntaxhighlight>

== Usage Examples ==

=== Minimal Vue setup ===

<syntaxhighlight lang="typescript">
// wdio.conf.ts
export const config: WebdriverIO.Config = {
runner: ['browser', { preset: 'vue' }],
specs: ['./src/**/*.test.ts'],
capabilities: [{ browserName: 'chrome' }],
framework: 'mocha'
}
</syntaxhighlight>

=== React with coverage ===

<syntaxhighlight lang="typescript">
// wdio.conf.ts
export const config: WebdriverIO.Config = {
runner: ['browser', {
preset: 'react',
coverage: {
enabled: true,
reportsDirectory: './coverage',
reporter: ['text', 'html', 'json-summary'],
lines: 80,
functions: 80,
branches: 80,
statements: 80
}
}],
specs: ['./src/**/*.test.tsx'],
capabilities: [{ browserName: 'chrome' }],
framework: 'mocha'
}
</syntaxhighlight>

=== Svelte with headless mode ===

<syntaxhighlight lang="typescript">
// wdio.conf.ts
export const config: WebdriverIO.Config = {
runner: ['browser', {
preset: 'svelte',
headless: true
}],
specs: ['./src/**/*.test.ts'],
capabilities: [{ browserName: 'chrome' }],
framework: 'mocha'
}
</syntaxhighlight>

== Related Pages ==

* '''implements''' [[Principle:Webdriverio_Webdriverio_Browser_Runner_Configuration|Principle: Browser_Runner_Configuration]]
* [[requires_env::Environment:Webdriverio_Webdriverio_Node_Runtime_Environment]]
* [[requires_env::Environment:Webdriverio_Webdriverio_Browser_Driver_Environment]]

[[Category:Implementations]]

Implementation:Webdriverio Webdriverio BrowserStack Launcher Tunnel

2026-09-27T10:53:20Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Webdriverio_Webdriverio_BrowserStack_Launcher_Tunnel}}
== Metadata ==
{| class="wikitable"
|-
! Field !! Value
|-
| '''Page ID''' || BrowserStack_Launcher_Tunnel
|-
| '''Wiki''' || Webdriverio_Webdriverio
|-
| '''Type''' || Implementation (API Doc)
|-
| '''Domains''' || Testing, Cloud, Networking
|-
| '''Knowledge Sources''' || Repo (https://github.com/webdriverio/webdriverio), Doc (https://www.browserstack.com/docs/local-testing)
|-
| '''Related Principles''' || [[Principle:Webdriverio_Webdriverio_Local_Tunnel_Connectivity|Principle: Local_Tunnel_Connectivity]]
|}

== Overview ==

Concrete tool for managing local tunnels within the WDIO service lifecycle for cloud testing providers. This document covers the BrowserStack Local tunnel (primary), Sauce Connect tunnel, and TestingBot tunnel implementations. Each service manages the tunnel binary lifecycle: starting in <code>onPrepare</code> (before any tests run), automatically injecting tunnel identifiers into capabilities, and stopping in <code>onComplete</code> (after all tests finish).

== Description ==

The tunnel launcher services follow a consistent pattern across all three providers:

# '''Constructor''' -- Receives service options and WDIO configuration.
# '''<code>onPrepare</code>''' -- Checks if tunneling is enabled, configures tunnel options, injects tunnel identifiers into capabilities, starts the tunnel binary, and measures boot time.
# '''<code>onComplete</code>''' -- Stops the tunnel binary and cleans up.

The BrowserStack implementation is the most feature-rich, with support for local testing, test reporting, Percy visual testing, accessibility automation, and test orchestration. The tunnel management is one component of the larger <code>BrowserstackLauncherService</code>.

== Source ==

{| class="wikitable"
|-
! File !! Lines !! Description
|-
| <code>packages/wdio-browserstack-service/src/launcher.ts</code> || L70-577 || <code>BrowserstackLauncherService</code> class with tunnel management in <code>onPrepare</code>
|-
| <code>packages/wdio-browserstack-service/src/launcher.ts</code> || L529-577 || BrowserStack Local tunnel start logic
|-
| <code>packages/wdio-browserstack-service/src/launcher.ts</code> || L580-670+ || <code>onComplete</code> hook with tunnel stop logic
|-
| <code>packages/wdio-sauce-service/src/launcher.ts</code> || L20-143 || <code>SauceLauncher</code> with Sauce Connect tunnel management
|-
| <code>packages/wdio-testingbot-service/src/launcher.ts</code> || L12-78 || <code>TestingBotLauncher</code> with TestingBot Tunnel management
|-
| <code>packages/wdio-browserstack-service/src/types.ts</code> || L62-212 || <code>BrowserstackConfig</code> interface (tunnel options)
|-
| <code>packages/wdio-sauce-service/src/types.ts</code> || L4-51 || <code>SauceServiceConfig</code> interface (tunnel options)
|-
| <code>packages/wdio-testingbot-service/src/types.ts</code> || L49-60 || <code>TestingbotOptions</code> interface (tunnel options)
|}

== BrowserStack Local Tunnel ==

=== Configuration ===

<syntaxhighlight lang="typescript">
services: [['browserstack', {
browserstackLocal: boolean, // Enable/disable the tunnel (default: false)
forcedStop: boolean, // Kill tunnel without waiting for callback (default: false)
opts: Partial<BSOptions> // BrowserStack Local binary options
}]]
</syntaxhighlight>

'''I/O Contract -- Service Configuration:'''
{| class="wikitable"
|-
! Parameter !! Type !! Default !! Description
|-
| <code>browserstackLocal</code> || <code>boolean</code> || <code>false</code> || Enable local tunnel
|-
| <code>forcedStop</code> || <code>boolean</code> || <code>false</code> || Force-kill tunnel binary on completion
|-
| <code>opts</code> || <code>Partial<BSOptions></code> || <code>{}</code> || Binary options (localIdentifier, verbose, proxy, etc.)
|-
| <code>opts.localIdentifier</code> || <code>string</code> || auto-generated || Unique identifier for this tunnel instance
|}

=== Tunnel Start (onPrepare) ===

<syntaxhighlight lang="typescript">
// packages/wdio-browserstack-service/src/launcher.ts (L529-577)
// Simplified tunnel start logic:

if (!this._options.browserstackLocal) {
return BStackLogger.info('browserstackLocal is not enabled - skipping...')
}

const opts = {
key: this._config.key,
...this._options.opts
}

this.browserstackLocal = new BrowserstackLocalLauncher.Local()

// Inject 'local' flag into all capabilities
this._updateCaps(capabilities, 'local')
if (opts.localIdentifier) {
this._updateCaps(capabilities, 'localIdentifier', opts.localIdentifier)
}

// Start with 60-second timeout
performance.mark('tbTunnelStart')
return Promise.race([
promisify(this.browserstackLocal.start.bind(this.browserstackLocal))(opts),
new Promise((resolve, reject) => {
timer = setTimeout(function () {
reject('Browserstack Local failed to start within 60 seconds!')
}, 60000)
})
])
</syntaxhighlight>

'''I/O Contract -- onPrepare:'''
{| class="wikitable"
|-
! Input !! Type !! Description
|-
| <code>config</code> || <code>Options.Testrunner</code> || WDIO configuration (includes <code>key</code> for authentication)
|-
| <code>capabilities</code> || <code>Capabilities.TestrunnerCapabilities</code> || Capabilities array (mutated to add tunnel flags)
|-
! Output !! Type !! Description
|-
| Returns || <code>Promise<void></code> || Resolves when tunnel is ready, rejects on timeout (60s) or error
|-
| Side effects || Capability mutation || Adds <code>local: true</code> and <code>localIdentifier</code> to all capabilities
|}

=== Tunnel Stop (onComplete) ===

<syntaxhighlight lang="typescript">
// packages/wdio-browserstack-service/src/launcher.ts (L653-670+)
if (!this.browserstackLocal || !this.browserstackLocal.isRunning()) {
return
}

const pid = this.browserstackLocal.pid
this.browserstackLocal.stop((err: Error) => {
// cleanup callback
})
</syntaxhighlight>

== Sauce Connect Tunnel ==

=== Configuration ===

<syntaxhighlight lang="typescript">
services: [['sauce', {
sauceConnect: boolean, // Enable/disable Sauce Connect (default: false)
sauceConnectOpts: SauceConnectOptions // Sauce Connect options
}]]
</syntaxhighlight>

=== Tunnel Start (onPrepare) ===

<syntaxhighlight lang="typescript">
// packages/wdio-sauce-service/src/launcher.ts (L35-101)
async onPrepare (config, capabilities) {
if (!this._options.sauceConnect) {
return
}

const sauceConnectTunnelName = (
this._options.sauceConnectOpts?.tunnelName ||
`SC-tunnel-${Math.random().toString().slice(2)}`
)

const sauceConnectOpts: SauceConnectOptions = {
tunnelName: sauceConnectTunnelName,
...this._options.sauceConnectOpts,
metadata: metadata
}

// Inject tunnel name into all capabilities
const prepareCapability = makeCapabilityFactory(sauceConnectTunnelName)
for (const capability of capabilities) {
prepareCapability(capability)
}

log.info('Starting Sauce Connect Tunnel')
performance.mark('sauceConnectStart')
this._sauceConnectProcess = await this.startTunnel(sauceConnectOpts)
performance.mark('sauceConnectEnd')
}
</syntaxhighlight>

'''I/O Contract -- SauceServiceConfig tunnel options:'''
{| class="wikitable"
|-
! Parameter !! Type !! Default !! Description
|-
| <code>sauceConnect</code> || <code>boolean</code> || <code>false</code> || Enable Sauce Connect tunnel
|-
| <code>sauceConnectOpts</code> || <code>SauceConnectOptions</code> || <code>{}</code> || Sauce Connect binary options
|-
| <code>sauceConnectOpts.tunnelName</code> || <code>string</code> || auto-generated || Unique tunnel identifier
|}

=== Tunnel Stop (onComplete) ===

<syntaxhighlight lang="typescript">
// packages/wdio-sauce-service/src/launcher.ts (L136-142)
onComplete () {
if (!this._sauceConnectProcess) {
return
}
return this._sauceConnectProcess.close()
}
</syntaxhighlight>

== TestingBot Tunnel ==

=== Configuration ===

<syntaxhighlight lang="typescript">
services: [['testingbot', {
tbTunnel: boolean, // Enable/disable TestingBot Tunnel (default: false)
tbTunnelOpts: TunnelLauncherOptions // Tunnel binary options
}]]
</syntaxhighlight>

=== Tunnel Start (onPrepare) ===

<syntaxhighlight lang="typescript">
// packages/wdio-testingbot-service/src/launcher.ts (L20-65)
async onPrepare (config, capabilities) {
if (!this.options.tbTunnel || !config.user || !config.key) {
return
}

const tbTunnelIdentifier = (
this.options.tbTunnelOpts?.tunnelIdentifier ||
`TB-tunnel-${Math.random().toString().slice(2)}`
)

this.tbTunnelOpts = Object.assign({
apiKey: config.user,
apiSecret: config.key,
'tunnel-identifier': tbTunnelIdentifier,
}, this.options.tbTunnelOpts)

// Inject tunnel identifier into all capabilities
for (const capability of capabilitiesEntries) {
const c = (caps as Capabilities.W3CCapabilities).alwaysMatch || caps
if (!c['tb:options']) {
c['tb:options'] = {}
}
c['tb:options']['tunnel-identifier'] = tbTunnelIdentifier
}

performance.mark('tbTunnelStart')
this.tunnel = await promisify(testingbotTunnel)(this.tbTunnelOpts)
performance.mark('tbTunnelEnd')
}
</syntaxhighlight>

'''I/O Contract -- TestingbotOptions tunnel options:'''
{| class="wikitable"
|-
! Parameter !! Type !! Default !! Description
|-
| <code>tbTunnel</code> || <code>boolean</code> || <code>false</code> || Enable TestingBot Tunnel
|-
| <code>tbTunnelOpts</code> || <code>TunnelLauncherOptions</code> || <code>{}</code> || Tunnel binary options
|-
| <code>tbTunnelOpts.tunnelIdentifier</code> || <code>string</code> || auto-generated || Unique tunnel identifier
|-
| <code>tbTunnelOpts.apiKey</code> || <code>string</code> || from <code>config.user</code> || TestingBot API key
|-
| <code>tbTunnelOpts.apiSecret</code> || <code>string</code> || from <code>config.key</code> || TestingBot API secret
|}

=== Tunnel Stop (onComplete) ===

<syntaxhighlight lang="typescript">
// packages/wdio-testingbot-service/src/launcher.ts (L71-77)
onComplete () {
if (!this.tunnel) {
return
}
return new Promise(resolve => this.tunnel!.close(resolve))
}
</syntaxhighlight>

== Cross-Provider Comparison ==

{| class="wikitable"
|-
! Feature !! BrowserStack !! Sauce Labs !! TestingBot
|-
| Enable flag || <code>browserstackLocal: true</code> || <code>sauceConnect: true</code> || <code>tbTunnel: true</code>
|-
| Options key || <code>opts</code> || <code>sauceConnectOpts</code> || <code>tbTunnelOpts</code>
|-
| Tunnel ID property || <code>opts.localIdentifier</code> || <code>sauceConnectOpts.tunnelName</code> || <code>tbTunnelOpts.tunnelIdentifier</code>
|-
| Capability namespace || <code>bstack:options.localIdentifier</code> || <code>sauce:options.tunnelName</code> || <code>tb:options['tunnel-identifier']</code>
|-
| Auto-ID generation || No (requires manual ID) || Yes (<code>SC-tunnel-*</code>) || Yes (<code>TB-tunnel-*</code>)
|-
| Start timeout || 60 seconds || No explicit timeout || No explicit timeout
|-
| Retry on failure || No || Yes (3 retries for ENOENT) || No
|-
| Boot time measurement || Yes (PerformanceObserver) || Yes (PerformanceObserver) || Yes (PerformanceObserver)
|}

== Full Example: BrowserStack Local Configuration ==

<syntaxhighlight lang="typescript">
// wdio.conf.ts
export const config: WebdriverIO.Config = {
user: process.env.BROWSERSTACK_USERNAME,
key: process.env.BROWSERSTACK_ACCESS_KEY,

services: [['browserstack', {
browserstackLocal: true,
opts: {
localIdentifier: 'ci-tunnel-' + process.env.BUILD_NUMBER,
verbose: true
},
forcedStop: false,
setSessionName: true,
setSessionStatus: true
}]],

capabilities: [{
browserName: 'chrome',
browserVersion: 'latest',
'bstack:options': {
os: 'Windows',
osVersion: '11',
local: true,
localIdentifier: 'ci-tunnel-' + process.env.BUILD_NUMBER,
buildName: 'Local Dev Build',
video: true
}
}],

baseUrl: 'http://localhost:3000',
specs: ['./test/specs/**/*.spec.ts'],
framework: 'mocha'
}
</syntaxhighlight>

== Related Pages ==

* '''implements''' [[Principle:Webdriverio_Webdriverio_Local_Tunnel_Connectivity|Principle: Local_Tunnel_Connectivity]]
* [[requires_env::Environment:Webdriverio_Webdriverio_Cloud_Service_Credentials]]

[[Category:Implementations]]

Implementation:Vespa engine Vespa Vespa Logctl

2026-09-27T10:53:19Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Vespa_engine_Vespa_Vespa_Logctl}}
{{PageInfo|type=Implementation|title=Vespa_engine_Vespa_Vespa_Logctl}}
== vespa-logctl ==

[[domain::Logging]] [[domain::Observability]]

=== Tool Signature ===

<syntaxhighlight lang="bash">
vespa-logctl [options] <service>[:component] [<level-mods>]
</syntaxhighlight>

=== Source Location ===

* '''CLI source''': [https://github.com/vespa-engine/vespa/blob/master/vespalog/src/logctl/logctl.cpp vespalog/src/logctl/logctl.cpp] (Lines L94-230)
* '''ControlFile class''': [https://github.com/vespa-engine/vespa/blob/master/vespalog/src/vespa/log/control-file.cpp vespalog/src/vespa/log/control-file.cpp] (Lines L1-450)
* '''ControlFile header''': [https://github.com/vespa-engine/vespa/blob/master/vespalog/src/vespa/log/control-file.h vespalog/src/vespa/log/control-file.h] (Lines L1-89)
* '''Type''': External Tool Doc

=== Description ===

<code>vespa-logctl</code> is a '''command-line tool''' for viewing and modifying the runtime log level settings of running Vespa processes. It operates by directly reading and writing the '''memory-mapped log control files''' that each Vespa process creates at startup. Because the control files are memory-mapped by the target processes, level changes take effect '''immediately''' without any signal or restart.

=== CLI Flags ===

{| class="wikitable"
! Flag !! Long Form !! Description
|-
| <code>-c</code> || || Create the control file if it does not exist
|-
| <code>-n</code> || || Create a new entry for the specified component if it does not exist
|-
| <code>-a</code> || || Apply the operation to '''all''' control files in the control directory
|-
| <code>-f <file></code> || || Specify an explicit control file path instead of deriving it from the service name
|-
| <code>-d <dir></code> || || Specify the control file directory (default: <code>$VESPA_LOG_CONTROL_DIR</code> or <code>/var/log/vespa/logcontrol</code>)
|-
| <code>-r</code> || || Reset all levels for the specified component to their default values
|}

=== Level Modification Syntax ===

Level modifications are specified as a '''comma-separated list''' of assignments:

<syntaxhighlight lang="text">
<level>=<on|off>[,<level>=<on|off>]...
</syntaxhighlight>

The special level name <code>all</code> applies to all 8 levels simultaneously:

{| class="wikitable"
! Modifier !! Effect
|-
| <code>all=on</code> || Enable all 8 log levels (fatal, error, warning, config, info, event, debug, spam)
|-
| <code>all=off</code> || Disable all 8 log levels
|-
| <code>debug=on</code> || Enable only the debug level
|-
| <code>spam=off</code> || Disable only the spam level
|-
| <code>all=on,debug=off,spam=off</code> || Enable all levels except debug and spam (the default configuration)
|}

Modifiers are applied '''left to right''', so <code>all=on,debug=off</code> first enables everything and then disables debug.

=== Usage Examples ===

==== View Current Levels ====

<syntaxhighlight lang="bash">
# Show all component levels for the searchnode service
vespa-logctl searchnode
</syntaxhighlight>

Output:

<syntaxhighlight lang="text">
searchnode.com.yahoo.search.handler ON ON ON ON ON ON OFF OFF
searchnode.com.yahoo.container ON ON ON ON ON ON OFF OFF
searchnode.com.yahoo.jdisc ON ON ON ON ON ON OFF OFF
</syntaxhighlight>

The columns correspond to: fatal, error, warning, config, info, event, debug, spam.

==== Enable Debug for a Specific Component ====

<syntaxhighlight lang="bash">
# Enable debug logging for query handler only
vespa-logctl searchnode:com.yahoo.search.handler debug=on
</syntaxhighlight>

==== Enable Debug for All Components ====

<syntaxhighlight lang="bash">
# Enable debug for everything in searchnode
vespa-logctl searchnode debug=on
</syntaxhighlight>

==== Reset to Defaults ====

<syntaxhighlight lang="bash">
# Reset all components of configserver to default levels
vespa-logctl -r configserver
</syntaxhighlight>

==== Use Explicit Control File ====

<syntaxhighlight lang="bash">
# Modify levels using a specific control file path
vespa-logctl -f /var/log/vespa/logcontrol/searchnode.logcontrol \
searchnode:com.yahoo.search debug=on
</syntaxhighlight>

==== Pre-Create Component Entry ====

<syntaxhighlight lang="bash">
# Create a control file entry before the component has logged anything
vespa-logctl -n searchnode:com.yahoo.search.newmodule all=on
</syntaxhighlight>

=== ControlFile C++ Class ===

The <code>vespa-logctl</code> tool uses the <code>ControlFile</code> C++ class to manipulate the memory-mapped control files.

==== Class Declaration ====

<syntaxhighlight lang="cpp">
class ControlFile {
public:
enum Mode { READONLY, READWRITE, CREATE };

ControlFile(const char *filename, Mode mode);
~ControlFile();

unsigned int *getLevels(const char *name);
char *getComponentName(unsigned int offset);
void ensureComponent(const char *pattern);
void flush();

ComponentIterator begin();
ComponentIterator end();

private:
int _fd;
char *_mapBase;
size_t _mapSize;
// ...
};
</syntaxhighlight>

==== Modes ====

{| class="wikitable"
! Mode !! Description !! Used By
|-
| <code>READONLY</code> || Open for reading only. Used when listing current levels. || <code>vespa-logctl</code> (no level-mods argument)
|-
| <code>READWRITE</code> || Open for reading and writing. Used when modifying levels. || <code>vespa-logctl</code> (with level-mods argument)
|-
| <code>CREATE</code> || Create the file if it does not exist. Write header and prefix. || <code>vespa-logctl -c</code>, Vespa processes at startup
|}

==== Key Methods ====

===== getLevels =====

<syntaxhighlight lang="cpp">
unsigned int *getLevels(const char *name);
</syntaxhighlight>

Returns a pointer to the level bitmask for the named component. The pointer points directly into the memory-mapped region, so modifications are immediately visible to the target process.

===== ensureComponent =====

<syntaxhighlight lang="cpp">
void ensureComponent(const char *pattern);
</syntaxhighlight>

Ensures that an entry exists for the specified component. If no entry exists, one is created with default level settings. This is used with the <code>-n</code> flag to pre-register components.

===== flush =====

<syntaxhighlight lang="cpp">
void flush();
</syntaxhighlight>

Forces any pending memory-mapped writes to be synchronized to disk. Called after level modifications to ensure persistence.

==== ComponentIterator ====

The <code>ComponentIterator</code> allows enumeration of all registered components:

<syntaxhighlight lang="cpp">
for (auto it = controlFile.begin(); it != controlFile.end(); ++it) {
printf("%s\t", it->name());
unsigned int *levels = it->levels();
for (int i = 0; i < 8; i++) {
printf("%s ", levels[i] ? "ON" : "OFF");
}
printf("\n");
}
</syntaxhighlight>

This is the mechanism used by <code>vespa-logctl</code> to display the current level table when invoked without level modifications.

=== Internal Operation Flow ===

When <code>vespa-logctl</code> is invoked with level modifications, it performs the following steps:

# '''Parse arguments''': Extract the service name, optional component, and level modifications from the command line.
# '''Locate control file''': Either use the explicit <code>-f</code> path, or derive it from the service name and control directory as <code><dir>/<service>.logcontrol</code>.
# '''Open control file''': Create a <code>ControlFile</code> object in <code>READWRITE</code> mode (or <code>CREATE</code> mode with <code>-c</code>).
# '''Find or create component entry''': Use <code>getLevels()</code> or <code>ensureComponent()</code> to locate the entry.
# '''Apply level modifications''': Parse the level-mods string and set each level byte to 1 (on) or 0 (off).
# '''Flush changes''': Call <code>flush()</code> to ensure the changes are persisted.
# '''Close control file''': The <code>ControlFile</code> destructor unmaps and closes the file.

=== Interaction with Java Processes ===

The control file format is identical for Java and C++ processes. When <code>vespa-logctl</code> modifies the control file:

* '''Java processes''' see the change through their <code>MappedByteBuffer</code>, which maps the same physical file.
* '''C++ processes''' see the change through their <code>mmap()</code> mapping of the same file.

No inter-process communication (signals, sockets, etc.) is needed. The memory-mapped file '''is''' the communication channel.

=== Error Handling ===

* If the control file does not exist and <code>-c</code> is not specified, the tool prints an error and exits with a non-zero status.
* If the specified component does not exist in the control file and <code>-n</code> is not specified, the tool prints a warning. With the <code>-a</code> flag, non-matching components are silently skipped.
* If the level-mods string is malformed, a usage message is printed.

=== Implements Principle ===

[[Principle:Vespa_engine_Vespa_Runtime_Level_Control|Runtime Level Control]]

=== Related Implementations ===

* [[Implementation:Vespa_engine_Vespa_VespaLevelControllerRepo_Constructor|VespaLevelControllerRepo Constructor]] -- Creates the Java-side memory-mapped level controller that <code>vespa-logctl</code> modifies
* [[Implementation:Vespa_engine_Vespa_VespaLogHandler_Publish|VespaLogHandler.publish]] -- Reads the level control bytes on every log call

== Related Pages ==

* [[implements::Principle:Vespa_engine_Vespa_Runtime_Level_Control]]
* [[requires_env::Environment:Vespa_engine_Vespa_CMake_Cpp23_Build_Environment]]
* [[requires_env::Environment:Vespa_engine_Vespa_POSIX_Mmap_Log_Control]]
* [[uses_heuristic::Heuristic:Vespa_engine_Vespa_Log_Level_Inheritance_Polling]]

[[Category:Implementations]]

[[Category:Implementations]]

Implementation:Vespa engine Vespa VespaLogHandler Publish

2026-09-27T10:53:18Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Vespa_engine_Vespa_VespaLogHandler_Publish}}
{{PageInfo|type=Implementation|title=Vespa_engine_Vespa_VespaLogHandler_Publish}}
== VespaLogHandler.publish ==

[[domain::Logging]] [[domain::Observability]]

=== API Signature ===

<syntaxhighlight lang="java">
public synchronized void publish(LogRecord record)
</syntaxhighlight>

=== Source Location ===

* '''File''': [https://github.com/vespa-engine/vespa/blob/master/vespalog/src/main/java/com/yahoo/log/VespaLogHandler.java vespalog/src/main/java/com/yahoo/log/VespaLogHandler.java]
* '''Lines''': L64-90
* '''Class''': <code>class VespaLogHandler extends StreamHandler</code>
* '''Package''': <code>com.yahoo.log</code>

=== Description ===

The <code>publish</code> method is the '''hot path''' of Vespa's logging framework. It is called for every log record produced by any JUL logger in the process. The method applies level reduction, level control, reject filtering, and then opens the log target, writes the formatted record, flushes, and closes the file target. The method is <code>synchronized</code> to prevent interleaved output from concurrent threads.

=== Parameters ===

{| class="wikitable"
! Parameter !! Type !! Description
|-
| <code>record</code> || <code>LogRecord</code> || The JUL log record to publish. Contains the level, logger name, message, thread ID, timestamp, optional thrown exception, and optional parameters.
|}

=== Return Value ===

<code>void</code> -- The record is either written to the log target or silently dropped (if filtered out by level control or reject filter).

=== Full Method Source ===

<syntaxhighlight lang="java">
public synchronized void publish(LogRecord record) {
String loggerName = record.getLoggerName();

Level level = possiblyReduceLogLevel(loggerName, record.getLevel());

LevelController ctrl = getLevelControl(loggerName);
if (!ctrl.shouldLog(level)) { return; }

if (logRejectFilter.shouldReject(record.getMessage())) { return; }

try {
setOutputStream(logTarget.open());
} catch (RuntimeException e) {
LogRecord r = new LogRecord(Level.SEVERE, "Unable to open file target");
r.setThrown(e);
emergencyLog(r);
setOutputStream(System.err);
}

super.publish(record);
flush();
closeFileTarget();
}
</syntaxhighlight>

=== Step-by-Step Execution Flow ===

==== Step 1: Extract Logger Name ====

<syntaxhighlight lang="java">
String loggerName = record.getLoggerName();
</syntaxhighlight>

The logger name is the JUL logger name (e.g., <code>"com.yahoo.search.handler.SearchHandler"</code>). It is used for both level reduction and level control lookups.

==== Step 2: Apply Level Reduction ====

<syntaxhighlight lang="java">
Level level = possiblyReduceLogLevel(loggerName, record.getLevel());
</syntaxhighlight>

For certain noisy third-party loggers, the effective level is '''reduced'''. For example, Jetty INFO messages are treated as DEBUG. The <code>possiblyReduceLogLevel()</code> method checks if the logger name matches any prefix in the level reduction map. If it matches, the level is lowered; otherwise, the original level is returned unchanged.

This reduced level is used for the <code>shouldLog()</code> check but does '''not''' modify the <code>LogRecord</code> itself. The original level is preserved in the record for formatting purposes.

==== Step 3: Check Level Control ====

<syntaxhighlight lang="java">
LevelController ctrl = getLevelControl(loggerName);
if (!ctrl.shouldLog(level)) { return; }
</syntaxhighlight>

The level controller for the logger's component is retrieved from the <code>LevelControllerRepo</code>. The <code>shouldLog()</code> method reads a single byte from the memory-mapped control file to determine if the (possibly reduced) level is enabled.

If the level is disabled, the method returns '''immediately''' without performing any formatting, I/O, or synchronization beyond the method-level lock. This is the '''fast path''' for disabled levels.

==== Step 4: Apply Reject Filter ====

<syntaxhighlight lang="java">
if (logRejectFilter.shouldReject(record.getMessage())) { return; }
</syntaxhighlight>

Even if the level is enabled, the reject filter can drop messages that match known-useless patterns. This is a '''content-based filter''' that examines the actual message text. If the message is rejected, the method returns without writing anything.

==== Step 5: Open Log Target ====

<syntaxhighlight lang="java">
try {
setOutputStream(logTarget.open());
} catch (RuntimeException e) {
LogRecord r = new LogRecord(Level.SEVERE, "Unable to open file target");
r.setThrown(e);
emergencyLog(r);
setOutputStream(System.err);
}
</syntaxhighlight>

The log target is opened '''on every publish call'''. This is the key mechanism that enables '''external log rotation''':

* For '''file targets''': <code>open()</code> opens the file at the configured path. If an external tool has renamed the file since the last call, the new <code>open()</code> creates a fresh file at the original path.
* For '''file descriptor targets''' (e.g., <code>fd:2</code>): <code>open()</code> returns the same file descriptor each time.

If the open fails (e.g., disk full, permission denied), the handler:
# Creates a SEVERE log record describing the failure
# Logs it via <code>emergencyLog()</code> (which writes to stderr)
# Falls back to using <code>System.err</code> as the output stream

This ensures the original log record is still written (to stderr) even when the primary target is unavailable.

==== Step 6: Write the Record ====

<syntaxhighlight lang="java">
super.publish(record);
</syntaxhighlight>

Delegates to <code>StreamHandler.publish()</code>, which:
# Calls the <code>VespaFormatter.format(record)</code> method to produce the tab-delimited log line
# Writes the formatted string to the output stream set in Step 5

==== Step 7: Flush ====

<syntaxhighlight lang="java">
flush();
</syntaxhighlight>

Immediately flushes the output stream to ensure the record is committed to the underlying file or file descriptor. This guarantees that:
* Log monitoring tools see the record immediately
* A process crash loses at most the record currently being written

==== Step 8: Close File Target ====

<syntaxhighlight lang="java">
closeFileTarget();
</syntaxhighlight>

For file-based targets, the file is closed after each write. This:
* Releases the file descriptor
* Ensures the file can be rotated by external tools
* Prevents accumulation of open file handles

For file descriptor targets (<code>fd:2</code>, etc.), this is a no-op since the handler should not close shared file descriptors.

=== Synchronization Details ===

The method is declared <code>synchronized</code>, which means:

* '''Thread safety''': Only one thread can execute <code>publish()</code> at a time, preventing interleaved output.
* '''Atomicity''': The open-write-flush-close cycle is atomic with respect to other log calls.
* '''Bottleneck risk''': Under extreme logging load, threads will contend on the monitor. However, logging should not be on the critical path of request processing.

=== Error Recovery ===

The error recovery strategy is designed for '''robustness over correctness''':

* If the log target fails, output goes to stderr rather than being lost.
* The next <code>publish()</code> call will attempt to reopen the original target. If the underlying issue is resolved (e.g., disk space freed), normal operation resumes automatically.
* The emergency log record documents the failure for post-mortem analysis.

=== Performance Characteristics ===

{| class="wikitable"
! Scenario !! Operations !! Cost
|-
| Level disabled || Memory read + return || Nanoseconds (fast path)
|-
| Message rejected || Memory read + string match + return || Microseconds
|-
| Normal write (fd target) || Format + write + flush || Tens of microseconds
|-
| Normal write (file target) || Open + format + write + flush + close || Hundreds of microseconds
|}

The '''fast path''' (disabled level) is the most common case in production, where only a small fraction of log calls actually produce output.

=== Usage Context ===

This method is '''never called directly''' by application code. It is invoked by the JUL framework when any logger produces a log record:

<syntaxhighlight lang="java">
// Application code:
Logger logger = Logger.getLogger("com.yahoo.search.handler");
logger.info("Query completed in 42ms");

// JUL framework internally calls:
// vespaLogHandler.publish(logRecord);
</syntaxhighlight>

=== Implements Principle ===

[[Principle:Vespa_engine_Vespa_Log_Rotation_and_Special_Handling|Log Rotation and Special Handling]]

=== Related Implementations ===

* [[Implementation:Vespa_engine_Vespa_VespaLogHandler_Constructor|VespaLogHandler Constructor]] -- Constructs the handler and its dependencies
* [[Implementation:Vespa_engine_Vespa_VespaFormatter_Format|VespaFormatter.format]] -- Formats the log record into the tab-delimited output
* [[Implementation:Vespa_engine_Vespa_Vespa_Logctl|vespa-logctl]] -- Modifies the level control bytes that <code>shouldLog()</code> reads
* [[Implementation:Vespa_engine_Vespa_VespaLevelControllerRepo_Constructor|VespaLevelControllerRepo Constructor]] -- Creates the level controller repo used by <code>getLevelControl()</code>

== Related Pages ==

* [[implements::Principle:Vespa_engine_Vespa_Log_Rotation_and_Special_Handling]]
* [[uses_heuristic::Heuristic:Vespa_engine_Vespa_Log_Level_Inheritance_Polling]]

[[Category:Implementations]]

[[Category:Implementations]]

Implementation:Vespa engine Vespa VespaLogHandler Constructor

2026-09-27T10:53:17Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Vespa_engine_Vespa_VespaLogHandler_Constructor}}
{{PageInfo|type=Implementation|title=Vespa_engine_Vespa_VespaLogHandler_Constructor}}
== VespaLogHandler Constructor ==

[[domain::Logging]] [[domain::Observability]]

=== API Signature ===

<syntaxhighlight lang="java">
VespaLogHandler(LogTarget logTarget, LevelControllerRepo levelControllerRepo,
String serviceName, String applicationPrefix)
</syntaxhighlight>

=== Source Location ===

* '''File''': [https://github.com/vespa-engine/vespa/blob/master/vespalog/src/main/java/com/yahoo/log/VespaLogHandler.java vespalog/src/main/java/com/yahoo/log/VespaLogHandler.java]
* '''Lines''': L51-59
* '''Class''': <code>class VespaLogHandler extends StreamHandler</code>
* '''Package''': <code>com.yahoo.log</code>

=== Description ===

The <code>VespaLogHandler</code> constructor assembles the core logging handler that replaces the default JUL handlers. It wires together the log target (output destination), level controller repository (per-component level checking), service metadata, and the reject filter. After construction, the <code>initialize()</code> method sets up the <code>VespaFormatter</code> and configures the handler for use.

=== Key Fields ===

{| class="wikitable"
! Field !! Type !! Purpose
|-
| <code>logTarget</code> || <code>LogTarget</code> || Output destination (file, stderr, etc.) that provides an <code>OutputStream</code> on each <code>open()</code> call
|-
| <code>serviceName</code> || <code>String</code> || The Vespa service identity (e.g., <code>"searchnode"</code>, <code>"configserver"</code>) included in every log line
|-
| <code>appPrefix</code> || <code>String</code> || Application prefix prepended to component names in the control file and log output
|-
| <code>repo</code> || <code>LevelControllerRepo</code> || Repository that provides per-component <code>LevelController</code> instances for <code>shouldLog()</code> checks
|-
| <code>logRejectFilter</code> || <code>RejectFilter</code> || Content-based filter that drops known-useless log messages
|}

=== Parameters ===

{| class="wikitable"
! Parameter !! Type !! Description
|-
| <code>logTarget</code> || <code>LogTarget</code> || The log output target. Created from the <code>VESPA_LOG_TARGET</code> configuration value. Supports file descriptors (<code>fd:2</code>), file paths (<code>file:/path</code>), and stdout.
|-
| <code>levelControllerRepo</code> || <code>LevelControllerRepo</code> || The level controller repository, either a <code>VespaLevelControllerRepo</code> (memory-mapped) or <code>DefaultLevelControllerRepo</code> (static levels).
|-
| <code>serviceName</code> || <code>String</code> || The Vespa service name (from <code>VESPA_SERVICE_NAME</code>). Used in the <code>VespaFormatter</code> to populate the service field of each log line.
|-
| <code>applicationPrefix</code> || <code>String</code> || The application prefix (typically the program name). Used as the component prefix in log output and control file entries.
|}

=== Constructor Source ===

<syntaxhighlight lang="java">
VespaLogHandler(LogTarget logTarget, LevelControllerRepo levelControllerRepo,
String serviceName, String applicationPrefix) {
this.logTarget = logTarget;
this.serviceName = serviceName;
this.appPrefix = applicationPrefix;
this.repo = levelControllerRepo;
this.logRejectFilter = RejectFilter.createDefaultRejectFilter();
initialize();
}
</syntaxhighlight>

=== Initialization Sequence ===

==== Step 1: Store Dependencies ====

<syntaxhighlight lang="java">
this.logTarget = logTarget;
this.serviceName = serviceName;
this.appPrefix = applicationPrefix;
this.repo = levelControllerRepo;
</syntaxhighlight>

All four constructor parameters are stored as instance fields. These are used during the <code>publish()</code> call path.

==== Step 2: Create the Reject Filter ====

<syntaxhighlight lang="java">
this.logRejectFilter = RejectFilter.createDefaultRejectFilter();
</syntaxhighlight>

The <code>RejectFilter</code> is a content-based filter that examines log message text and drops messages matching known-useless patterns. The default filter is created via a factory method that includes patterns for common noisy messages. This filter is applied '''after''' level checking, as an additional layer of noise reduction.

==== Step 3: Initialize the Handler ====

<syntaxhighlight lang="java">
initialize();
</syntaxhighlight>

The <code>initialize()</code> method (not shown in the constructor) performs the following setup:

# Creates a <code>VespaFormatter</code> with the service name and application prefix.
# Sets the formatter on this handler via <code>setFormatter()</code>.
# Sets the handler level to <code>ALL</code> so that level filtering is handled by the <code>LevelController</code> rather than the JUL framework.

=== Level Reduction Map ===

The handler also maintains a '''level reduction map''' for noisy third-party loggers. This is a static mapping that reduces the effective log level for specific logger name prefixes:

<syntaxhighlight lang="java">
// Conceptual level reduction:
// "org.eclipse.jetty" -> reduce INFO to DEBUG
// "org.apache.aries.spifly" -> reduce INFO to DEBUG
</syntaxhighlight>

The <code>possiblyReduceLogLevel(String loggerName, Level level)</code> method checks if the logger name matches any prefix in the reduction map. If it does, the level is reduced (e.g., INFO becomes DEBUG), effectively silencing these loggers under default configuration.

=== The getLevelControl Method ===

When <code>publish()</code> needs to check if a log record should be output, it calls:

<syntaxhighlight lang="java">
LevelController ctrl = getLevelControl(loggerName);
</syntaxhighlight>

This method:
# Looks up the logger name in the <code>LevelControllerRepo</code>.
# If a per-component entry exists in the control file, returns its <code>LevelController</code>.
# If no entry exists, registers the component in the control file and returns a new controller initialized with default levels.

=== Usage Context ===

The constructor is called from <code>LogSetup.initInternal()</code>:

<syntaxhighlight lang="java">
// Inside LogSetup.initInternal():
LogTarget target = LogTarget.createLogTarget(logTargetString);
LevelControllerRepo repo = new VespaLevelControllerRepo(logControlFile, logLevel, programName);
VespaLogHandler handler = new VespaLogHandler(target, repo, serviceName, programName);

// Install on root logger
Logger rootLogger = Logger.getLogger("");
for (Handler h : rootLogger.getHandlers()) {
rootLogger.removeHandler(h);
}
rootLogger.addHandler(handler);
rootLogger.setLevel(Level.ALL);
</syntaxhighlight>

=== Implements Principle ===

[[Principle:Vespa_engine_Vespa_Logger_Handler_Installation|Logger Handler Installation]]

=== Related Implementations ===

* [[Implementation:Vespa_engine_Vespa_LogSetup_InitVespaLogging|LogSetup.initVespaLogging]] -- Resolves configuration and triggers handler construction
* [[Implementation:Vespa_engine_Vespa_VespaLevelControllerRepo_Constructor|VespaLevelControllerRepo Constructor]] -- Creates the level controller repo passed to this constructor
* [[Implementation:Vespa_engine_Vespa_VespaLogHandler_Publish|VespaLogHandler.publish]] -- The method called on each log record after the handler is installed
* [[Implementation:Vespa_engine_Vespa_VespaFormatter_Format|VespaFormatter.format]] -- The formatter used to produce tab-delimited output

== Related Pages ==

* [[implements::Principle:Vespa_engine_Vespa_Logger_Handler_Installation]]
* [[requires_env::Environment:Vespa_engine_Vespa_POSIX_Mmap_Log_Control]]

[[Category:Implementations]]

[[Category:Implementations]]

Implementation:Vespa engine Vespa VespaLevelControllerRepo Constructor

2026-09-27T10:53:17Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Vespa_engine_Vespa_VespaLevelControllerRepo_Constructor}}
{{PageInfo|type=Implementation|title=Vespa_engine_Vespa_VespaLevelControllerRepo_Constructor}}
== VespaLevelControllerRepo Constructor ==

[[domain::Logging]] [[domain::Observability]]

=== API Signature ===

<syntaxhighlight lang="java">
VespaLevelControllerRepo(String logCtlFn, String logLevel, String applicationPrefix)
</syntaxhighlight>

=== Source Location ===

* '''File''': [https://github.com/vespa-engine/vespa/blob/master/vespalog/src/main/java/com/yahoo/log/VespaLevelControllerRepo.java vespalog/src/main/java/com/yahoo/log/VespaLevelControllerRepo.java]
* '''Lines''': L58-63
* '''Class''': <code>class VespaLevelControllerRepo implements LevelControllerRepo</code>
* '''Package''': <code>com.yahoo.log</code>

=== Description ===

The <code>VespaLevelControllerRepo</code> constructor initializes the '''memory-mapped level control subsystem'''. It stores the control file path and application prefix, creates a default level controller from the level string, and then opens (or creates) the control file via <code>openCtlFile()</code>.

This class implements <code>LevelControllerRepo</code>, which provides the interface for looking up per-component level controllers. The repository is the bridge between the memory-mapped control file on disk and the level-checking logic used by the <code>VespaLogHandler</code>.

=== Key Fields ===

{| class="wikitable"
! Field !! Type !! Purpose
|-
| <code>ctlFile</code> || <code>RandomAccessFile</code> || Handle to the log control file opened in read-write mode
|-
| <code>mapBuf</code> || <code>MappedByteBuffer</code> || Memory-mapped view of the control file contents
|-
| <code>levelControllerRepo</code> || <code>MappedLevelControllerRepo</code> || Repository backed by the mapped buffer for per-component lookups
|-
| <code>logControlFilename</code> || <code>String</code> || Absolute path to the log control file
|-
| <code>appPrefix</code> || <code>String</code> || Application prefix prepended to component names in the control file
|-
| <code>defaultLevelCtrl</code> || <code>DefaultLevelController</code> || Fallback level controller used when no per-component entry exists
|}

=== Constants ===

{| class="wikitable"
! Constant !! Value !! Purpose
|-
| <code>maxPrefix</code> || <code>64</code> || Maximum length of the application prefix in the control file
|-
| <code>CFHEADER</code> || <code>"Vespa log control file version 1\n"</code> || Header string written to and validated in the control file
|-
| <code>numLevels</code> || <code>8</code> || Number of log levels supported (fatal, error, warning, config, info, event, debug, spam)
|}

=== Parameters ===

{| class="wikitable"
! Parameter !! Type !! Description
|-
| <code>logCtlFn</code> || <code>String</code> || Absolute path to the log control file. Derived from <code>VESPA_LOG_CONTROL_DIR</code> and <code>VESPA_SERVICE_NAME</code>, or set explicitly via <code>VESPA_LOG_CONTROL_FILE</code>.
|-
| <code>logLevel</code> || <code>String</code> || Default log level string (e.g., <code>"all -debug -spam"</code>). Used by the <code>DefaultLevelController</code> for components without explicit entries.
|-
| <code>applicationPrefix</code> || <code>String</code> || The application prefix (e.g., the program name) written to the control file header and used to scope component entries.
|}

=== Constructor Source ===

<syntaxhighlight lang="java">
VespaLevelControllerRepo(String logCtlFn, String logLevel, String applicationPrefix) {
this.logControlFilename = logCtlFn;
this.appPrefix = applicationPrefix;
defaultLevelCtrl = new DefaultLevelController(logLevel);
openCtlFile();
}
</syntaxhighlight>

=== Initialization Sequence ===

==== Step 1: Store Configuration ====

<syntaxhighlight lang="java">
this.logControlFilename = logCtlFn;
this.appPrefix = applicationPrefix;
</syntaxhighlight>

The control file path and application prefix are stored for use by <code>openCtlFile()</code> and subsequent component registration.

==== Step 2: Create Default Level Controller ====

<syntaxhighlight lang="java">
defaultLevelCtrl = new DefaultLevelController(logLevel);
</syntaxhighlight>

The <code>DefaultLevelController</code> parses the level string (e.g., <code>"all -debug -spam"</code>) and creates a level controller that can answer <code>shouldLog(level)</code> queries. This serves as the '''fallback''' for any component that does not have an explicit entry in the control file.

==== Step 3: Open the Control File ====

<syntaxhighlight lang="java">
openCtlFile();
</syntaxhighlight>

The <code>openCtlFile()</code> method performs the heavy lifting:

# Opens (or creates) the file at <code>logControlFilename</code> using <code>RandomAccessFile</code> in <code>"rw"</code> mode.
# If the file is newly created, writes the <code>CFHEADER</code> and the application prefix.
# If the file exists, validates the header string.
# Maps the file into memory via <code>FileChannel.map(MapMode.READ_WRITE, ...)</code>.
# Creates a <code>MappedLevelControllerRepo</code> from the <code>MappedByteBuffer</code>.

=== LevelControllerRepo Interface ===

The class implements the <code>LevelControllerRepo</code> interface, which provides:

<syntaxhighlight lang="java">
public interface LevelControllerRepo {
LevelController getLevelController(String component);
void close();
}
</syntaxhighlight>

When <code>getLevelController(component)</code> is called:
# It first checks the <code>MappedLevelControllerRepo</code> for an existing entry.
# If no entry exists, it creates a new entry in the memory-mapped file for that component.
# If the control file is not available, it returns the <code>defaultLevelCtrl</code>.

=== Error Handling ===

* If the control file cannot be opened or created, the repository falls back to using only the <code>defaultLevelCtrl</code>. Runtime level control is disabled in this case.
* If the file header does not match <code>CFHEADER</code>, the file is treated as corrupt and a warning is logged.

=== Usage Context ===

The constructor is called from within <code>LogSetup.initInternal()</code> after the control file path and log level have been resolved:

<syntaxhighlight lang="java">
// Inside LogSetup.initInternal():
LevelControllerRepo repo;
if (logControlFile != null) {
repo = new VespaLevelControllerRepo(logControlFile, logLevel, programName);
} else {
repo = new DefaultLevelControllerRepo(logLevel);
}
</syntaxhighlight>

=== Implements Principle ===

[[Principle:Vespa_engine_Vespa_Control_File_Initialization|Control File Initialization]]

=== Related Implementations ===

* [[Implementation:Vespa_engine_Vespa_LogSetup_InitVespaLogging|LogSetup.initVespaLogging]] -- Resolves the control file path and calls this constructor
* [[Implementation:Vespa_engine_Vespa_Vespa_Logctl|vespa-logctl]] -- The CLI tool that reads and modifies the same control file at runtime

== Related Pages ==

* [[implements::Principle:Vespa_engine_Vespa_Control_File_Initialization]]
* [[requires_env::Environment:Vespa_engine_Vespa_POSIX_Mmap_Log_Control]]
* [[uses_heuristic::Heuristic:Vespa_engine_Vespa_Log_Level_Inheritance_Polling]]

[[Category:Implementations]]

[[Category:Implementations]]

Implementation:Vespa engine Vespa VespaFormatter Format

2026-09-27T10:53:16Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Vespa_engine_Vespa_VespaFormatter_Format}}
{{PageInfo|type=Implementation|title=Vespa_engine_Vespa_VespaFormatter_Format}}
== VespaFormatter.format ==

[[domain::Logging]] [[domain::Observability]]

=== API Signature ===

<syntaxhighlight lang="java">
public String format(LogRecord r)
</syntaxhighlight>

=== Source Location ===

* '''File''': [https://github.com/vespa-engine/vespa/blob/master/vespalog/src/main/java/com/yahoo/log/VespaFormatter.java vespalog/src/main/java/com/yahoo/log/VespaFormatter.java]
* '''Lines''': L94-135
* '''Class''': <code>class VespaFormatter extends SimpleFormatter</code>
* '''Package''': <code>com.yahoo.log</code>

=== Description ===

The <code>format</code> method converts a JUL <code>LogRecord</code> into Vespa's '''tab-delimited log line format'''. It produces a single line containing the timestamp, hostname, process/thread IDs, service name, component path, log level, and escaped message. This method is called by the <code>VespaLogHandler</code> for every log record that passes level control and reject filtering.

=== Key Fields ===

{| class="wikitable"
! Field !! Type !! Purpose
|-
| <code>hostname</code> || <code>String</code> || The hostname of the machine, resolved once at formatter construction time
|-
| <code>processID</code> || <code>String</code> || The process ID (PID) of the current JVM, resolved once at construction time
|-
| <code>serviceName</code> || <code>String</code> || The Vespa service name (e.g., <code>"searchnode"</code>) from <code>VESPA_SERVICE_NAME</code>
|-
| <code>componentPrefix</code> || <code>String</code> || The application prefix (e.g., <code>"container"</code>) prepended to the logger name in the component field
|}

=== Parameters ===

{| class="wikitable"
! Parameter !! Type !! Description
|-
| <code>r</code> || <code>LogRecord</code> || The JUL log record to format. Contains the log level, logger name, message, thread ID, timestamp, optional thrown exception, and optional parameters.
|}

=== Return Value ===

<code>String</code> -- A single tab-delimited log line ending with <code>\n</code>. The format is:

<syntaxhighlight lang="text">
<time>\t<hostname>\t<pid/tid>\t<service>\t<component>\t<level>\t<message>\n
</syntaxhighlight>

=== Full Method Source ===

<syntaxhighlight lang="java">
public String format(LogRecord r) {
StringBuilder sbuf = new StringBuilder(300);

String levelName = LogLevel.getVespaLogLevel(r.getLevel())
.toString().toLowerCase();

String component = r.getLoggerName();

sbuf.append(VespaFormat.formatTime(r.getInstant()));
sbuf.append("\t");
sbuf.append(hostname).append("\t")
.append(processID).append("/")
.append(r.getThreadID()).append("\t")
.append(serviceName).append("\t");

if (component == null && componentPrefix == null) {
sbuf.append("-");
} else if (component == null) {
sbuf.append(componentPrefix);
} else if (componentPrefix == null) {
sbuf.append(".").append(component);
} else {
sbuf.append(componentPrefix).append(".").append(component);
}

sbuf.append("\t").append(levelName).append("\t");

if (r.getLevel() == LogLevel.EVENT) {
Event event = (Event) r.getParameters()[0];
sbuf.append(VespaFormat.escape(event.toString()));
} else {
sbuf.append(VespaFormat.escape(formatMessage(r)));
}

appendException(r.getThrown(), sbuf);
sbuf.append("\n");

return sbuf.toString();
}
</syntaxhighlight>

=== Field-by-Field Breakdown ===

==== 1. Timestamp ====

<syntaxhighlight lang="java">
sbuf.append(VespaFormat.formatTime(r.getInstant()));
</syntaxhighlight>

Formats the log record's <code>Instant</code> as <code>seconds.microseconds</code> in Unix epoch format (e.g., <code>1696000000.123456</code>). The <code>VespaFormat.formatTime()</code> utility method handles the conversion.

==== 2. Hostname ====

<syntaxhighlight lang="java">
sbuf.append(hostname);
</syntaxhighlight>

The hostname is resolved '''once''' at formatter construction time and stored as a field. It does not change during the lifetime of the process.

==== 3. PID/TID ====

<syntaxhighlight lang="java">
sbuf.append(processID).append("/").append(r.getThreadID());
</syntaxhighlight>

The process ID is resolved once at construction. The thread ID is extracted from the <code>LogRecord</code> and changes per log call. The format is <code>pid/tid</code> (e.g., <code>12345/67</code>).

==== 4. Service Name ====

<syntaxhighlight lang="java">
sbuf.append(serviceName);
</syntaxhighlight>

The service name is set during formatter construction from the <code>VESPA_SERVICE_NAME</code> value (e.g., <code>"searchnode"</code>, <code>"configserver"</code>).

==== 5. Component ====

<syntaxhighlight lang="java">
if (component == null && componentPrefix == null) {
sbuf.append("-");
} else if (component == null) {
sbuf.append(componentPrefix);
} else if (componentPrefix == null) {
sbuf.append(".").append(component);
} else {
sbuf.append(componentPrefix).append(".").append(component);
}
</syntaxhighlight>

The component field is built from the application prefix and the JUL logger name:

{| class="wikitable"
! componentPrefix !! component (logger name) !! Output
|-
| <code>null</code> || <code>null</code> || <code>-</code>
|-
| <code>"container"</code> || <code>null</code> || <code>container</code>
|-
| <code>null</code> || <code>"com.yahoo.search"</code> || <code>.com.yahoo.search</code>
|-
| <code>"container"</code> || <code>"com.yahoo.search"</code> || <code>container.com.yahoo.search</code>
|}

==== 6. Level ====

<syntaxhighlight lang="java">
String levelName = LogLevel.getVespaLogLevel(r.getLevel())
.toString().toLowerCase();
sbuf.append(levelName);
</syntaxhighlight>

The JUL level is mapped to Vespa's level names via <code>LogLevel.getVespaLogLevel()</code> and converted to lowercase (e.g., <code>"info"</code>, <code>"warning"</code>, <code>"error"</code>).

==== 7. Message ====

<syntaxhighlight lang="java">
if (r.getLevel() == LogLevel.EVENT) {
Event event = (Event) r.getParameters()[0];
sbuf.append(VespaFormat.escape(event.toString()));
} else {
sbuf.append(VespaFormat.escape(formatMessage(r)));
}
</syntaxhighlight>

Two code paths exist:

* '''EVENT level''': The first parameter of the log record is cast to an <code>Event</code> object and serialized via its <code>toString()</code> method. Events represent structured occurrences (service start/stop, state changes).
* '''All other levels''': The standard JUL <code>formatMessage(r)</code> is used, which handles message format substitution if parameters are present.

In both cases, the output is passed through <code>VespaFormat.escape()</code> to escape tabs, newlines, and backslashes.

==== 8. Exception (Optional) ====

<syntaxhighlight lang="java">
appendException(r.getThrown(), sbuf);
</syntaxhighlight>

If the log record has a thrown exception, the full stack trace is appended to the message. Stack trace newlines are escaped so the entire record remains on a single line.

==== 9. Newline ====

<syntaxhighlight lang="java">
sbuf.append("\n");
</syntaxhighlight>

The log line is terminated with a single newline character.

=== Example Output ===

<syntaxhighlight lang="text">
1696000000.123456 node-01.example.com 12345/67 searchnode container.com.yahoo.search.handler info Query completed in 42ms
</syntaxhighlight>

=== Performance Notes ===

* The <code>StringBuilder</code> is initialized with a capacity of '''300''' characters, which is a reasonable estimate for most log lines and avoids reallocation in the common case.
* The hostname and process ID are resolved once and cached, avoiding per-record system calls.
* The <code>VespaFormat.escape()</code> method only allocates a new string if the input contains characters that need escaping.

=== Implements Principle ===

[[Principle:Vespa_engine_Vespa_Log_Message_Formatting|Log Message Formatting]]

=== Related Implementations ===

* [[Implementation:Vespa_engine_Vespa_VespaLogHandler_Publish|VespaLogHandler.publish]] -- Calls this format method for each log record that passes filtering
* [[Implementation:Vespa_engine_Vespa_VespaLogHandler_Constructor|VespaLogHandler Constructor]] -- Creates the formatter during handler initialization

== Related Pages ==

* [[implements::Principle:Vespa_engine_Vespa_Log_Message_Formatting]]

[[Category:Implementations]]

[[Category:Implementations]]

Implementation:Vespa engine Vespa Publish Artifacts Sh

2026-09-27T10:53:15Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Vespa_engine_Vespa_Publish_Artifacts_Sh}}
{{PageInfo|type=Implementation|title=Vespa_engine_Vespa_Publish_Artifacts_Sh}}
{{DISPLAYTITLE:Artifact Publishing Implementation}}
[[domain::CI_CD]] [[domain::Build_Systems]]

== Overview ==

This page documents the implementation of the Vespa artifact signing and publishing script: ''.buildkite/publish-artifacts.sh''. This script creates tar archives of the RPM and Maven repositories, signs each artifact using Sigstore cosign with Buildkite OIDC identity, and uploads everything to the configured artifact destination.

'''Type:''' External Tool Doc

== Code Reference ==

<syntaxhighlight lang="bash">
#!/usr/bin/env bash
# .buildkite/publish-artifacts.sh (L1-31)

set -o errexit
set -o nounset
set -o pipefail

if [[ -n "${DEBUG:-}" ]]; then
set -o xtrace
fi

echo "--- Publishing build artifacts"
cd "$WORKDIR/artifacts/$ARCH"

echo "Creating archives..."
tar -cf rpm-repo.tar rpms &
tar -cf maven-repo.tar maven-repo
cp -a rpms/vespa-config-model-fat-*.rpm .
wait

echo "Signing artifacts..."
for FILE in *.tar *.rpm; do
cosign sign-blob -y --oidc-provider=buildkite-agent \
--output-signature "$FILE.sig" \
--output-certificate "$FILE.pem" "$FILE"
done

ARTIFACT_DESTINATION="${VESPA_ENGINE_ARTIFACTS_BUCKET}/${VESPA_ENGINE_ARTIFACTS_PREFIX}/${VESPA_VERSION}/artifacts/${ARCH}"
echo "Uploading artifacts to ${ARTIFACT_DESTINATION} ..."
buildkite-agent artifact upload "*.tar;*.tar.sig;*.tar.pem;*.rpm;*.rpm.sig;*.rpm.pem" \
"$ARTIFACT_DESTINATION"
</syntaxhighlight>

== I/O Contract ==

=== Inputs (Environment Variables) ===

{| class="wikitable"
! Variable !! Required !! Description !! Example
|-
| <code>WORKDIR</code> || Yes || Working directory containing build artifacts || <code>/tmp/vespa-build</code>
|-
| <code>ARCH</code> || Yes || CPU architecture identifier || <code>x86_64</code> or <code>aarch64</code>
|-
| <code>VESPA_ENGINE_ARTIFACTS_BUCKET</code> || Yes || Cloud storage bucket for uploads || <code>s3://vespa-artifacts</code>
|-
| <code>VESPA_ENGINE_ARTIFACTS_PREFIX</code> || Yes || Path prefix within the bucket || <code>builds</code>
|-
| <code>VESPA_VERSION</code> || Yes || Version string for the artifact path || <code>8.432.17</code>
|-
| <code>DEBUG</code> || No || If set to a non-empty value, enables bash xtrace || <code>1</code>
|}

=== Inputs (Prerequisite Files) ===

{| class="wikitable"
! File/Directory !! Produced By !! Description
|-
| <code>$WORKDIR/artifacts/$ARCH/rpms/</code> || build-rpms.sh || YUM repository with RPM packages and metadata
|-
| <code>$WORKDIR/artifacts/$ARCH/maven-repo/</code> || java.sh || Maven local repository with compiled JARs
|}

=== Inputs (System Dependencies) ===

{| class="wikitable"
! Tool !! Purpose !! Authentication
|-
| <code>cosign</code> || Sigstore keyless signing || Buildkite OIDC token (automatic)
|-
| <code>buildkite-agent</code> || Artifact upload to Buildkite || Agent token (pre-configured)
|-
| <code>tar</code> || Archive creation || N/A
|}

=== Outputs (Files Created Locally) ===

{| class="wikitable"
! Output !! Type !! Description
|-
| <code>rpm-repo.tar</code> || Tar archive || Archive of the complete YUM repository
|-
| <code>maven-repo.tar</code> || Tar archive || Archive of the Maven local repository
|-
| <code>vespa-config-model-fat-*.rpm</code> || RPM file || Extracted fat config model RPM
|-
| <code>*.sig</code> files || Detached signatures || Cosign signatures for each artifact
|-
| <code>*.pem</code> files || Certificates || Sigstore Fulcio certificates for each artifact
|}

=== Outputs (Uploaded Artifacts) ===

All files matching <code>*.tar</code>, <code>*.tar.sig</code>, <code>*.tar.pem</code>, <code>*.rpm</code>, <code>*.rpm.sig</code>, and <code>*.rpm.pem</code> are uploaded to:

<syntaxhighlight lang="text">
${VESPA_ENGINE_ARTIFACTS_BUCKET}/${VESPA_ENGINE_ARTIFACTS_PREFIX}/${VESPA_VERSION}/artifacts/${ARCH}/
</syntaxhighlight>

== Key Implementation Details ==

=== Parallel Archive Creation ===

<syntaxhighlight lang="bash">
tar -cf rpm-repo.tar rpms &
tar -cf maven-repo.tar maven-repo
cp -a rpms/vespa-config-model-fat-*.rpm .
wait
</syntaxhighlight>

The RPM repository archive is created in a background process (<code>&</code>), while the Maven repository archive runs in the foreground. The <code>cp -a</code> command extracts the fat config model RPM for separate distribution. The <code>wait</code> command synchronizes with the background process before proceeding.

This parallel approach reduces total archiving time. Both tar operations are I/O-bound, so they can share disk bandwidth. The archives are uncompressed (<code>-cf</code> without a compression flag) because the downstream upload and any further packaging will handle compression.

=== Signing Loop ===

<syntaxhighlight lang="bash">
for FILE in *.tar *.rpm; do
cosign sign-blob -y --oidc-provider=buildkite-agent \
--output-signature "$FILE.sig" \
--output-certificate "$FILE.pem" "$FILE"
done
</syntaxhighlight>

The loop iterates over all tar archives and RPM files in the working directory. For each file, cosign performs keyless signing:

* '''<code>-y</code>''': Automatically accepts the Sigstore terms of service (non-interactive mode for CI).
* '''<code>--oidc-provider=buildkite-agent</code>''': Uses the Buildkite agent's built-in OIDC provider to obtain an identity token. The token contains claims identifying the Buildkite organization, pipeline, and build.
* '''<code>--output-signature "$FILE.sig"</code>''': Writes the detached signature to a <code>.sig</code> file alongside the artifact.
* '''<code>--output-certificate "$FILE.pem"</code>''': Writes the short-lived Fulcio certificate to a <code>.pem</code> file.

Each signing operation involves network calls to:
# The Buildkite OIDC endpoint (for identity token)
# Sigstore Fulcio (for certificate issuance)
# Sigstore Rekor (for transparency log recording)

=== Artifact Upload ===

<syntaxhighlight lang="bash">
ARTIFACT_DESTINATION="${VESPA_ENGINE_ARTIFACTS_BUCKET}/${VESPA_ENGINE_ARTIFACTS_PREFIX}/${VESPA_VERSION}/artifacts/${ARCH}"
buildkite-agent artifact upload "*.tar;*.tar.sig;*.tar.pem;*.rpm;*.rpm.sig;*.rpm.pem" "$ARTIFACT_DESTINATION"
</syntaxhighlight>

The <code>buildkite-agent artifact upload</code> command uploads matching files to the specified destination. Key aspects:

* The glob patterns are semicolon-separated, matching multiple file types in a single command.
* The destination path is hierarchically structured: bucket / prefix / version / artifacts / architecture.
* The Buildkite agent handles authentication to the underlying storage backend (S3, GCS, etc.) using pre-configured credentials.

=== Working Directory Management ===

<syntaxhighlight lang="bash">
cd "$WORKDIR/artifacts/$ARCH"
</syntaxhighlight>

The script changes to the architecture-specific artifact directory at the outset. All subsequent operations (archiving, signing, uploading) use relative paths within this directory. This simplifies the tar and glob commands and ensures the archive internal paths are clean (e.g., <code>rpms/vespa-8.432.17-1.x86_64.rpm</code> rather than <code>/tmp/vespa-build/artifacts/x86_64/rpms/...</code>).

== Error Handling ==

The script uses strict error handling (<code>set -o errexit</code>, <code>set -o nounset</code>, <code>set -o pipefail</code>). If any command fails -- archiving, signing, or uploading -- the script terminates immediately. This is important because:

* A failed signing operation should not be followed by an upload of unsigned artifacts.
* A failed upload should be clearly reported rather than silently skipped.
* The <code>wait</code> command propagates the exit code of the background tar process.

== Execution Context ==

<syntaxhighlight lang="text">
Buildkite Pipeline
--> .buildkite/build-rpms.sh (produces RPMs)
--> .buildkite/java.sh (produces Maven repo)
--> .buildkite/publish-artifacts.sh
--> cd $WORKDIR/artifacts/$ARCH
--> tar -cf rpm-repo.tar rpms &
--> tar -cf maven-repo.tar maven-repo
--> cp vespa-config-model-fat RPM
--> wait (synchronize background tar)
--> cosign sign-blob (for each *.tar and *.rpm)
--> buildkite-agent artifact upload
</syntaxhighlight>

== Source File Locations ==

* [https://github.com/vespa-engine/vespa/blob/master/.buildkite/publish-artifacts.sh <code>.buildkite/publish-artifacts.sh</code>] (Lines 1-31)

== See Also ==

* [[Principle:Vespa_engine_Vespa_Artifact_Signing_and_Publishing|Artifact Signing and Publishing Principle]] -- The design rationale for keyless signing and artifact distribution.
* [[Implementation:Vespa_engine_Vespa_Build_Rpms_Sh|RPM Build Implementation]] -- The preceding stage that produces RPM packages.
* [[Implementation:Vespa_engine_Vespa_Build_Container_Sh|Container Build Implementation]] -- The parallel stage that produces container images.
* [https://docs.sigstore.dev/cosign/overview/ Sigstore cosign documentation]

== Related Pages ==

* [[implements::Principle:Vespa_engine_Vespa_Artifact_Signing_and_Publishing]]
* [[requires_env::Environment:Vespa_engine_Vespa_Java_17_Build_Runtime]]
* [[requires_env::Environment:Vespa_engine_Vespa_Cosign_Sigstore_Signing]]

[[Category:Implementations]]

[[Category:Implementations]]

Implementation:Vespa engine Vespa Prepare Sh

2026-09-27T10:53:15Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Vespa_engine_Vespa_Prepare_Sh}}
{{PageInfo|type=Implementation|title=Vespa_engine_Vespa_Prepare_Sh}}
{{DISPLAYTITLE:Prepare.sh Implementation}}
[[domain::CI_CD]] [[domain::Build_Systems]]

== Overview ==

This page documents the implementation of the Vespa version preparation scripts: ''prepare.sh'' and ''replace-vespa-version-in-poms.sh''. These scripts form the first stage of the Vespa CI/CD build pipeline and are responsible for injecting a release version string into all Maven POM files and creating the artifact directory structure.

'''Type:''' External Tool Doc

== Code Reference ==

=== prepare.sh ===

<syntaxhighlight lang="bash">
#!/usr/bin/env bash
# .buildkite/prepare.sh (L1-21)

set -o errexit
set -o nounset
set -o pipefail

if [[ -n "${DEBUG:-}" ]]; then
set -o xtrace
fi

echo "--- Preparing build environment"
echo "Updating Vespa version in POMs to $VESPA_VERSION..."
"$SOURCE_DIR/.buildkite/replace-vespa-version-in-poms.sh" "$VESPA_VERSION" "$SOURCE_DIR"

echo "Creating artifact directories..."
mkdir -p "$WORKDIR/artifacts/$ARCH/rpms"
mkdir -p "$WORKDIR/artifacts/$ARCH/maven-repo"
</syntaxhighlight>

=== replace-vespa-version-in-poms.sh ===

<syntaxhighlight lang="bash">
#!/usr/bin/env bash
# .buildkite/replace-vespa-version-in-poms.sh (L1-46)

set -o errexit
set -o nounset
set -o pipefail

if [[ -n "${DEBUG:-}" ]]; then
set -o xtrace
fi

if [[ $# -ne 2 ]]; then
echo "Usage: $(basename "$0") <Vespa version> <path>"
exit 1
fi

readonly VESPA_VERSION=$1
readonly DIR=$2

# Fail if DIR does not exist or is not a directory
if [[ ! -d "$DIR" ]]; then
echo "Directory $DIR does not exist or is not a directory."
exit 1
fi

if [[ -z $(find -L "$DIR" -name "pom.xml") ]]; then
echo "No pom.xml files found in $DIR"
exit 0
fi

echo "Updating version strings in POM files..."
if [[ "$(uname)" == "Darwin" ]]; then
SED_INPLACE=(sed -i '')
else
SED_INPLACE=(sed -i)
fi

find -L "$DIR" -name "pom.xml" -exec "${SED_INPLACE[@]}" \
-e "s,<version>.*SNAPSHOT.*</version>,<version>$VESPA_VERSION</version>," \
-e "s,<vespaversion>.*project.version.*</vespaversion>,<vespaversion>$VESPA_VERSION</vespaversion>," \
-e "s,<test-framework.version>.*project.version.*</test-framework.version>,<test-framework.version>$VESPA_VERSION</test-framework.version>," \
{} \;
</syntaxhighlight>

== I/O Contract ==

=== Inputs (Environment Variables) ===

{| class="wikitable"
! Variable !! Required !! Description !! Example
|-
| <code>VESPA_VERSION</code> || Yes || Target version string to inject into POM files || <code>8.432.17</code>
|-
| <code>SOURCE_DIR</code> || Yes || Absolute path to the Vespa source checkout root || <code>/vespa</code>
|-
| <code>WORKDIR</code> || Yes || Working directory for build artifacts || <code>/tmp/vespa-build</code>
|-
| <code>ARCH</code> || Yes || CPU architecture identifier || <code>x86_64</code> or <code>aarch64</code>
|-
| <code>DEBUG</code> || No || If set to a non-empty value, enables bash xtrace for debugging || <code>1</code>
|}

=== Inputs (Arguments to replace-vespa-version-in-poms.sh) ===

{| class="wikitable"
! Position !! Description !! Example
|-
| <code>$1</code> || Vespa version string || <code>8.432.17</code>
|-
| <code>$2</code> || Path to directory containing POM files || <code>/vespa</code>
|}

=== Outputs (Files) ===

{| class="wikitable"
! Output !! Type !! Description
|-
| Modified <code>pom.xml</code> files || In-place file modification || All POM files under <code>$SOURCE_DIR</code> have SNAPSHOT versions replaced
|-
| <code>$WORKDIR/artifacts/$ARCH/rpms/</code> || Directory || Empty directory for RPM artifacts
|-
| <code>$WORKDIR/artifacts/$ARCH/maven-repo/</code> || Directory || Empty directory for Maven repository artifacts
|}

== Key Implementation Details ==

=== sed Substitution Patterns ===

The <code>find ... -exec sed</code> command applies three substitution expressions to each POM file:

# '''Module version replacement''': Matches any <code><version></code> tag containing the string <code>SNAPSHOT</code> and replaces the entire content with the target version. The regex uses <code>.*SNAPSHOT.*</code> to match version strings like <code>8.999.1-SNAPSHOT</code> or <code>8-SNAPSHOT</code>.
# '''Vespa dependency version replacement''': Matches <code><vespaversion></code> tags that contain Maven property expressions like <code>${project.version}</code> and replaces them with the literal version string.
# '''Test framework version replacement''': Same as above, but for the <code><test-framework.version></code> tag used by Vespa's test modules.

All three patterns use commas as the sed delimiter (<code>s,pattern,replacement,</code>) to avoid conflicts with forward slashes in XML tag syntax.

=== Platform Detection ===

The script detects macOS vs. Linux to handle the <code>sed -i</code> syntax difference:

<syntaxhighlight lang="bash">
if [[ "$(uname)" == "Darwin" ]]; then
SED_INPLACE=(sed -i '') # macOS BSD sed requires empty string argument
else
SED_INPLACE=(sed -i) # GNU sed on Linux
fi
</syntaxhighlight>

This allows the script to be used both in CI (Linux) and during local development on macOS.

=== Symbolic Link Following ===

The <code>find -L</code> flag follows symbolic links during directory traversal. This is important because the Vespa source tree may contain symlinked modules or directories.

=== Error Handling ===

Both scripts use strict Bash error handling:

* <code>set -o errexit</code>: Exit immediately if any command fails.
* <code>set -o nounset</code>: Treat unset variables as errors.
* <code>set -o pipefail</code>: Return the exit code of the first failed command in a pipeline.

The POM replacement script also validates its arguments, checking that exactly two arguments are provided and that the directory exists.

== Execution Context ==

These scripts are invoked by the Buildkite pipeline as the first step of the build process. The typical invocation chain is:

<syntaxhighlight lang="text">
Buildkite Pipeline
--> .buildkite/prepare.sh
--> .buildkite/replace-vespa-version-in-poms.sh $VESPA_VERSION $SOURCE_DIR
--> mkdir -p $WORKDIR/artifacts/$ARCH/rpms
--> mkdir -p $WORKDIR/artifacts/$ARCH/maven-repo
</syntaxhighlight>

== Source File Locations ==

* [https://github.com/vespa-engine/vespa/blob/master/.buildkite/prepare.sh <code>.buildkite/prepare.sh</code>] (Lines 1-21)
* [https://github.com/vespa-engine/vespa/blob/master/.buildkite/replace-vespa-version-in-poms.sh <code>.buildkite/replace-vespa-version-in-poms.sh</code>] (Lines 1-46)

== See Also ==

* [[Principle:Vespa_engine_Vespa_Version_Preparation|Version Preparation Principle]] -- The design rationale behind version preparation in CI/CD pipelines.
* [[Implementation:Vespa_engine_Vespa_Bootstrap_And_Java_Sh|Bootstrap and Java Build Implementation]] -- The next pipeline stage that consumes the version-prepared POM files.

== Related Pages ==

* [[implements::Principle:Vespa_engine_Vespa_Version_Preparation]]
* [[requires_env::Environment:Vespa_engine_Vespa_Java_17_Build_Runtime]]

[[Category:Implementations]]

[[Category:Implementations]]

Implementation:Vespa engine Vespa LogSetup InitVespaLogging

2026-09-27T10:53:14Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Vespa_engine_Vespa_LogSetup_InitVespaLogging}}
{{PageInfo|type=Implementation|title=Vespa_engine_Vespa_LogSetup_InitVespaLogging}}
== LogSetup.initVespaLogging ==

[[domain::Logging]] [[domain::Observability]]

=== API Signature ===

<syntaxhighlight lang="java">
public static void initVespaLogging(String programName)
</syntaxhighlight>

=== Source Location ===

* '''File''': [https://github.com/vespa-engine/vespa/blob/master/vespalog/src/main/java/com/yahoo/log/LogSetup.java vespalog/src/main/java/com/yahoo/log/LogSetup.java]
* '''Lines''': L81-129
* '''Class''': <code>public class LogSetup</code>
* '''Package''': <code>com.yahoo.log</code>

=== Description ===

<code>initVespaLogging</code> is the '''primary entry point''' for initializing Vespa's logging framework in Java processes. It resolves log configuration from system properties and environment variables, sets up the log target, creates the level controller, and installs the custom <code>VespaLogHandler</code> on the root JUL logger.

This method must be called '''exactly once''' at process startup before any logging occurs. It is a static method that sets global state.

=== Key Fields ===

{| class="wikitable"
! Field !! Type !! Purpose
|-
| <code>taskRunner</code> || <code>Timer</code> || Schedules periodic tasks (e.g., control file re-check)
|-
| <code>logHandler</code> || <code>VespaLogHandler</code> || The installed JUL handler for Vespa-format logging
|-
| <code>zooKeeperFilter</code> || <code>ZooKeeperFilter</code> || Filters ZooKeeper client log messages to a separate target
|-
| <code>isInitialized</code> || <code>boolean</code> || Guard flag preventing double initialization
|}

=== Parameters ===

{| class="wikitable"
! Parameter !! Type !! Description
|-
| <code>programName</code> || <code>String</code> || The name of the program (e.g., <code>"configserver"</code>, <code>"container"</code>). Must be non-null and non-empty.
|}

=== Return Value ===

<code>void</code> -- This method has no return value. It modifies global logging state as a side effect.

=== Exceptions ===

{| class="wikitable"
! Exception !! Condition
|-
| <code>RuntimeException</code> || If <code>programName</code> is null or empty
|-
| <code>RuntimeException</code> || If the log target file cannot be opened (wraps <code>FileNotFoundException</code>)
|}

=== Full Method Source ===

<syntaxhighlight lang="java">
public static void initVespaLogging(String programName) {
if (isInitialized) {
System.err.println("WARNING: initVespaLogging called twice");
}
isInitialized = true;

String logLevel = System.getProperty("vespa.log.level");
String logTarget = System.getProperty("vespa.log.target");
String logService = System.getProperty("vespa.service.name");
String logControlDir = System.getProperty("vespa.log.control.dir");
String logControlFile = System.getProperty("vespa.log.control.file");

if (programName == null || programName.equals("")) {
throw new RuntimeException("invalid programName: " + programName);
}

if (logTarget == null) logTarget = System.getenv("VESPA_LOG_TARGET");
if (logService == null) logService = System.getenv("VESPA_SERVICE_NAME");
if (logControlDir == null) logControlDir = System.getenv("VESPA_LOG_CONTROL_DIR");
if (logControlFile == null) logControlFile = System.getenv("VESPA_LOG_CONTROL_FILE");
if (logLevel == null) logLevel = System.getenv("VESPA_LOG_LEVEL");

if (logTarget == null) logTarget = "fd:2";
if (logLevel == null) logLevel = "all -debug -spam";

if (logControlFile == null && logControlDir != null && logService != null
&& !logService.equals("") && !logService.equals("-")) {
logControlFile = logControlDir + "/" + logService + ".logcontrol";
}

if (logService == null) logService = System.getProperty("config.id");
if (logService == null) logService = "-";

System.setProperty("vespa.service.name", logService);
System.setProperty("vespa.program.name", programName);

try {
initInternal(logTarget, logService, logControlFile, programName, logLevel);
} catch (FileNotFoundException e) {
throw new RuntimeException("Unable to initialize logging", e);
}
}
</syntaxhighlight>

=== Configuration Resolution Logic ===

The method resolves each configuration value through a '''three-tier precedence chain''':

==== Step 1: Read System Properties ====

<syntaxhighlight lang="java">
String logLevel = System.getProperty("vespa.log.level");
String logTarget = System.getProperty("vespa.log.target");
String logService = System.getProperty("vespa.service.name");
String logControlDir = System.getProperty("vespa.log.control.dir");
String logControlFile = System.getProperty("vespa.log.control.file");
</syntaxhighlight>

System properties have the highest precedence. They are typically set via JVM flags like <code>-Dvespa.log.target=file:/var/log/vespa.log</code>.

==== Step 2: Fall Back to Environment Variables ====

<syntaxhighlight lang="java">
if (logTarget == null) logTarget = System.getenv("VESPA_LOG_TARGET");
if (logService == null) logService = System.getenv("VESPA_SERVICE_NAME");
if (logControlDir == null) logControlDir = System.getenv("VESPA_LOG_CONTROL_DIR");
if (logControlFile == null) logControlFile = System.getenv("VESPA_LOG_CONTROL_FILE");
if (logLevel == null) logLevel = System.getenv("VESPA_LOG_LEVEL");
</syntaxhighlight>

If a system property was not set, the corresponding environment variable is checked. These are typically set by the Vespa process launcher (<code>vespa-start-services</code>).

==== Step 3: Apply Defaults ====

<syntaxhighlight lang="java">
if (logTarget == null) logTarget = "fd:2";
if (logLevel == null) logLevel = "all -debug -spam";
</syntaxhighlight>

If neither system property nor environment variable is set, hardcoded defaults are used:
* Log target defaults to '''stderr''' (<code>fd:2</code>)
* Log level defaults to '''all except debug and spam''' (<code>all -debug -spam</code>)

==== Step 4: Derive Control File Path ====

<syntaxhighlight lang="java">
if (logControlFile == null && logControlDir != null && logService != null
&& !logService.equals("") && !logService.equals("-")) {
logControlFile = logControlDir + "/" + logService + ".logcontrol";
}
</syntaxhighlight>

If no explicit control file was specified but both a control directory and a valid service name exist, the control file path is derived as <code><dir>/<service>.logcontrol</code>.

==== Step 5: Final Service Name Fallback ====

<syntaxhighlight lang="java">
if (logService == null) logService = System.getProperty("config.id");
if (logService == null) logService = "-";
</syntaxhighlight>

The service name has an additional fallback to <code>config.id</code> (the Vespa config identity), and then to the literal <code>"-"</code>.

=== Environment Variables ===

{| class="wikitable"
! Variable !! System Property !! Default !! Purpose
|-
| <code>VESPA_LOG_TARGET</code> || <code>vespa.log.target</code> || <code>fd:2</code> || Log output destination
|-
| <code>VESPA_LOG_LEVEL</code> || <code>vespa.log.level</code> || <code>all -debug -spam</code> || Default log levels
|-
| <code>VESPA_SERVICE_NAME</code> || <code>vespa.service.name</code> || <code>-</code> || Service identity
|-
| <code>VESPA_LOG_CONTROL_DIR</code> || <code>vespa.log.control.dir</code> || ''(none)'' || Control file directory
|-
| <code>VESPA_LOG_CONTROL_FILE</code> || <code>vespa.log.control.file</code> || ''(derived)'' || Explicit control file path
|}

=== Usage Example ===

<syntaxhighlight lang="java">
public class MyVespaService {
public static void main(String[] args) {
// Must be called before any logging
LogSetup.initVespaLogging("my-vespa-service");

// Now logging works with Vespa format
Logger logger = Logger.getLogger(MyVespaService.class.getName());
logger.info("Service started successfully");
}
}
</syntaxhighlight>

=== Behavior Notes ===

* '''Double initialization warning''': If called twice, a warning is printed to stderr but initialization proceeds. The <code>isInitialized</code> flag is set to <code>true</code> immediately, not after successful completion.
* '''System property side effects''': The method sets <code>vespa.service.name</code> and <code>vespa.program.name</code> as system properties, making them available to downstream components like the <code>VespaFormatter</code>.
* '''Delegation to initInternal''': The actual handler installation, level controller creation, and JUL configuration happen inside <code>initInternal()</code>, which is called at the end.

=== Implements Principle ===

[[Principle:Vespa_engine_Vespa_Log_Target_and_Level_Configuration|Log Target and Level Configuration]]

=== Related Implementations ===

* [[Implementation:Vespa_engine_Vespa_VespaLevelControllerRepo_Constructor|VespaLevelControllerRepo Constructor]] -- Creates the level controller using the resolved control file path
* [[Implementation:Vespa_engine_Vespa_VespaLogHandler_Constructor|VespaLogHandler Constructor]] -- Installs the handler using the resolved log target and level controller

== Related Pages ==

* [[implements::Principle:Vespa_engine_Vespa_Log_Target_and_Level_Configuration]]
* [[requires_env::Environment:Vespa_engine_Vespa_Java_17_Build_Runtime]]

[[Category:Implementations]]

[[Category:Implementations]]

Implementation:Vespa engine Vespa Cpp Sh

2026-09-27T10:53:13Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Vespa_engine_Vespa_Cpp_Sh}}
{{PageInfo|type=Implementation|title=Vespa_engine_Vespa_Cpp_Sh}}
{{DISPLAYTITLE:C++ Compilation Implementation}}
[[domain::CI_CD]] [[domain::Build_Systems]]

== Overview ==

This page documents the implementation of the Vespa C++ compilation script: ''.buildkite/cpp.sh''. This script activates the GCC toolset, sets up the dependency PATH, and runs <code>make</code> with parallel threads to compile all C++ components of Vespa.

'''Type:''' External Tool Doc

== Code Reference ==

<syntaxhighlight lang="bash">
#!/usr/bin/env bash
# .buildkite/cpp.sh (L1-29)

set -o errexit
set -o nounset
set -o pipefail

if [[ -n "${DEBUG:-}" ]]; then
set -o xtrace
fi

mydir=${0%/*}
shlim=${mydir}/show-limits.sh
if [ -x "${shlim}" ]; then
"${shlim}" || echo "failed: ${shlim}"
fi

echo "--- Building C++ components"
# shellcheck disable=1091
source /etc/profile.d/enable-gcc-toolset.sh

PATH=/opt/vespa-deps/bin:$PATH

cd "$SOURCE_DIR"
echo "Running make with $NUM_CPP_THREADS threads..."
make -j "$NUM_CPP_THREADS"
</syntaxhighlight>

== I/O Contract ==

=== Inputs (Environment Variables) ===

{| class="wikitable"
! Variable !! Required !! Description !! Example
|-
| <code>NUM_CPP_THREADS</code> || Yes || Number of parallel compilation threads for <code>make -j</code> || <code>16</code>
|-
| <code>SOURCE_DIR</code> || Yes || Root directory of the Vespa source checkout || <code>/vespa</code>
|-
| <code>DEBUG</code> || No || If set to a non-empty value, enables bash xtrace for debugging || <code>1</code>
|}

=== Inputs (System Dependencies) ===

{| class="wikitable"
! Dependency !! Path !! Purpose
|-
| GCC Toolset || <code>/etc/profile.d/enable-gcc-toolset.sh</code> || Activates GCC 12+ with C++20 support
|-
| Vespa Dependencies || <code>/opt/vespa-deps/bin</code> || Pre-built third-party libraries (protobuf, abseil, gRPC, etc.)
|-
| Generated Makefiles || Current working directory || Output from the CMake configuration stage
|-
| show-limits.sh || <code>.buildkite/show-limits.sh</code> || Optional resource limit reporter
|}

=== Inputs (Prerequisite Build Artifacts) ===

{| class="wikitable"
! Artifact !! Produced By !! Purpose
|-
| Makefiles and CMakeCache.txt || CMake configuration stage || Build rules for all C++ targets
|-
| Java JAR files || Java bootstrap stage || JNI headers and test dependencies
|}

=== Outputs (Compiled Artifacts) ===

{| class="wikitable"
! Output !! Type !! Description
|-
| <code>*.so</code> files || Shared libraries || Vespa's native libraries (search core, document storage, etc.)
|-
| Executable binaries || Executables || Server processes and CLI utilities
|-
| <code>*.a</code> files || Static libraries || Libraries statically linked into other targets
|-
| Test binaries || Executables || Unit test programs for subsequent test stages
|}

== Key Implementation Details ==

=== Resource Limit Reporting ===

Before starting compilation, the script optionally runs <code>show-limits.sh</code>:

<syntaxhighlight lang="bash">
mydir=${0%/*}
shlim=${mydir}/show-limits.sh
if [ -x "${shlim}" ]; then
"${shlim}" || echo "failed: ${shlim}"
fi
</syntaxhighlight>

The <code>${0%/*}</code> pattern extracts the directory containing the script itself. If <code>show-limits.sh</code> exists and is executable, it runs and logs system resource limits (ulimits, memory, file descriptors). If it fails, the error is logged but the build continues -- this is purely diagnostic.

=== GCC Toolset Activation ===

<syntaxhighlight lang="bash">
source /etc/profile.d/enable-gcc-toolset.sh
</syntaxhighlight>

This script is provided by the build container and activates a modern GCC version (12+) that supports C++20. Without this, the system default compiler (often GCC 8 on CentOS/AlmaLinux 8) would be used, which lacks full C++20 support.

=== Dependency PATH Setup ===

<syntaxhighlight lang="bash">
PATH=/opt/vespa-deps/bin:$PATH
</syntaxhighlight>

Pre-built Vespa dependencies are installed under <code>/opt/vespa-deps/</code>. Adding this to the PATH ensures that tools like <code>protoc</code> (Protocol Buffer compiler) and other code generators are found during compilation.

=== Parallel Make Invocation ===

<syntaxhighlight lang="bash">
cd "$SOURCE_DIR"
make -j "$NUM_CPP_THREADS"
</syntaxhighlight>

The script changes to <code>$SOURCE_DIR</code> and runs <code>make</code> with the <code>-j</code> flag for parallel execution. Key aspects:

* The Makefiles in the build directory were generated by the preceding CMake configuration stage.
* <code>make -j "$NUM_CPP_THREADS"</code> launches up to <code>$NUM_CPP_THREADS</code> concurrent compilation jobs.
* Make's dependency tracking ensures that targets are built in the correct order -- a shared library is not linked until all its object files are compiled.
* The <code>set -o errexit</code> flag causes the script to terminate immediately if <code>make</code> returns a non-zero exit code (indicating a compilation or linking error).

=== Working Directory ===

The script changes to <code>$SOURCE_DIR</code> before running make. This is the directory where CMake was configured (the build directory), which contains the generated Makefiles. The build directory may be the same as the source directory (in-source build) or a separate directory (out-of-source build), depending on pipeline configuration.

== Execution Context ==

The compilation script is invoked after CMake configuration completes:

<syntaxhighlight lang="text">
Buildkite Pipeline
--> .buildkite/bootstrap.sh (Java bootstrap)
--> .buildkite/bootstrap-cmake.sh (CMake configuration)
--> .buildkite/cpp.sh
--> source enable-gcc-toolset.sh
--> PATH=/opt/vespa-deps/bin:$PATH
--> cd $SOURCE_DIR
--> make -j $NUM_CPP_THREADS
</syntaxhighlight>

The compilation step is typically the longest stage in the pipeline, taking 20-60 minutes depending on the number of available CPU cores.

== Source File Locations ==

* [https://github.com/vespa-engine/vespa/blob/master/.buildkite/cpp.sh <code>.buildkite/cpp.sh</code>] (Lines 1-29)

== See Also ==

* [[Principle:Vespa_engine_Vespa_CPP_Compilation|C++ Compilation Principle]] -- The design rationale for parallel C++ compilation.
* [[Implementation:Vespa_engine_Vespa_Bootstrap_Cmake_Sh|CMake Configuration Implementation]] -- The preceding stage that generates Makefiles.
* [[Implementation:Vespa_engine_Vespa_Build_Rpms_Sh|RPM Package Creation Implementation]] -- The next stage that packages compiled binaries.

== Related Pages ==

* [[implements::Principle:Vespa_engine_Vespa_CPP_Compilation]]
* [[requires_env::Environment:Vespa_engine_Vespa_CMake_Cpp23_Build_Environment]]
* [[uses_heuristic::Heuristic:Vespa_engine_Vespa_Maven_Parallel_Build_Optimization]]

[[Category:Implementations]]

[[Category:Implementations]]

Implementation:Vespa engine Vespa Build Rpms Sh

2026-09-27T10:53:13Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Vespa_engine_Vespa_Build_Rpms_Sh}}
{{PageInfo|type=Implementation|title=Vespa_engine_Vespa_Build_Rpms_Sh}}
{{DISPLAYTITLE:RPM Build Implementation}}
[[domain::CI_CD]] [[domain::Build_Systems]]

== Overview ==

This page documents the implementation of the Vespa RPM package creation script: ''.buildkite/build-rpms.sh''. This script generates a source RPM, rebuilds it into binary RPMs with zstd compression, and creates a YUM repository from the results.

'''Type:''' External Tool Doc

== Code Reference ==

<syntaxhighlight lang="bash">
#!/usr/bin/env bash
# .buildkite/build-rpms.sh (L1-30)

set -o errexit
set -o nounset
set -o pipefail

if [[ -n "${DEBUG:-}" ]]; then
set -o xtrace
fi

echo "--- Building RPM packages"
ulimit -c 0

echo "Creating source RPM..."
make -f .copr/Makefile srpm outdir="$WORKDIR"

echo "Building binary RPMs..."
rpmbuild --rebuild \
--define="_topdir $WORKDIR/vespa-rpmbuild" \
--define "_debugsource_template %{nil}" \
--define "_binary_payload w10T4.zstdio" \
--define "installdir $WORKDIR/vespa-install" "$WORKDIR"/vespa-"$VESPA_VERSION"-*.src.rpm

echo "Moving RPMs and creating repository..."
mv "$WORKDIR"/vespa-rpmbuild/RPMS/*/*.rpm "$WORKDIR/artifacts/$ARCH/rpms"
createrepo "$WORKDIR/artifacts/$ARCH/rpms"
</syntaxhighlight>

== I/O Contract ==

=== Inputs (Environment Variables) ===

{| class="wikitable"
! Variable !! Required !! Description !! Example
|-
| <code>WORKDIR</code> || Yes || Working directory for all build artifacts || <code>/tmp/vespa-build</code>
|-
| <code>VESPA_VERSION</code> || Yes || Version string for the RPM package name || <code>8.432.17</code>
|-
| <code>ARCH</code> || Yes || CPU architecture identifier || <code>x86_64</code> or <code>aarch64</code>
|-
| <code>DEBUG</code> || No || If set to a non-empty value, enables bash xtrace || <code>1</code>
|}

=== Inputs (Prerequisite Files) ===

{| class="wikitable"
! File/Directory !! Produced By !! Description
|-
| <code>.copr/Makefile</code> || Source repository || Makefile with <code>srpm</code> target for SRPM generation
|-
| <code>$WORKDIR/vespa-install/</code> || <code>make install</code> (C++ build) || Pre-built binaries and libraries
|-
| <code>$WORKDIR/artifacts/$ARCH/rpms/</code> || prepare.sh || Pre-created empty directory for RPM output
|}

=== Outputs (Files) ===

{| class="wikitable"
! Output !! Type !! Description
|-
| <code>$WORKDIR/vespa-$VESPA_VERSION-*.src.rpm</code> || Source RPM || Contains spec file and source tarball
|-
| <code>$WORKDIR/artifacts/$ARCH/rpms/*.rpm</code> || Binary RPMs || Installable RPM packages
|-
| <code>$WORKDIR/artifacts/$ARCH/rpms/repodata/</code> || YUM metadata || Repository metadata for <code>yum</code>/<code>dnf</code>
|}

== Key Implementation Details ==

=== Core Dump Suppression ===

<syntaxhighlight lang="bash">
ulimit -c 0
</syntaxhighlight>

The script sets the core dump size limit to zero at the outset. This prevents any process that crashes during the RPM build from writing a core dump file, which could consume gigabytes of disk space and potentially fill the build disk.

=== Source RPM Generation ===

<syntaxhighlight lang="bash">
make -f .copr/Makefile srpm outdir="$WORKDIR"
</syntaxhighlight>

The <code>.copr/Makefile</code> follows the Copr build service convention. The <code>srpm</code> target:

# Generates a source tarball from the current source tree.
# Combines the tarball with the RPM spec file (<code>vespa.spec</code>).
# Produces an SRPM file named <code>vespa-$VESPA_VERSION-*.src.rpm</code> in <code>$WORKDIR</code>.

The <code>outdir</code> variable is passed to the Makefile to control where the SRPM is written.

=== Binary RPM Rebuild ===

<syntaxhighlight lang="bash">
rpmbuild --rebuild \
--define="_topdir $WORKDIR/vespa-rpmbuild" \
--define "_debugsource_template %{nil}" \
--define "_binary_payload w10T4.zstdio" \
--define "installdir $WORKDIR/vespa-install" \
"$WORKDIR"/vespa-"$VESPA_VERSION"-*.src.rpm
</syntaxhighlight>

The <code>rpmbuild --rebuild</code> command processes the SRPM through the full RPM build lifecycle. The <code>--define</code> flags override default RPM macros:

* '''<code>_topdir</code>''': Redirects the RPM build tree (BUILD, RPMS, SRPMS, SOURCES, SPECS directories) to an isolated working directory. This avoids conflicts with any system-level RPM build configuration.
* '''<code>_debugsource_template %{nil}</code>''': Sets the debug source template to nil, suppressing the creation of debugsource RPMs. This reduces build time and disk usage.
* '''<code>_binary_payload w10T4.zstdio</code>''': Configures the RPM payload compression:
** <code>w</code>: Write mode
** <code>10</code>: Compression level 10 (high compression)
** <code>T4</code>: Use 4 threads for compression
** <code>zstdio</code>: Use the Zstandard algorithm
* '''<code>installdir</code>''': Points to the directory where <code>make install</code> placed the compiled binaries. The spec file uses this to avoid recompilation during the <code>%install</code> phase.

The glob pattern <code>vespa-"$VESPA_VERSION"-*.src.rpm</code> matches the SRPM file regardless of the release suffix.

=== RPM Collection and Repository Creation ===

<syntaxhighlight lang="bash">
mv "$WORKDIR"/vespa-rpmbuild/RPMS/*/*.rpm "$WORKDIR/artifacts/$ARCH/rpms"
createrepo "$WORKDIR/artifacts/$ARCH/rpms"
</syntaxhighlight>

After <code>rpmbuild</code> completes, the binary RPMs are scattered across architecture-specific subdirectories under <code>RPMS/</code> (e.g., <code>RPMS/x86_64/</code>, <code>RPMS/noarch/</code>). The <code>mv</code> command with the glob <code>*/*.rpm</code> collects all RPMs into the flat artifact directory.

The <code>createrepo</code> command then generates YUM repository metadata, creating a <code>repodata/</code> directory containing:

* <code>repomd.xml</code>: Repository metadata index
* <code>primary.xml.gz</code>: Package names, versions, and dependencies
* <code>filelists.xml.gz</code>: File lists for each package
* <code>other.xml.gz</code>: Changelog and supplementary data

This enables downstream consumers (the container image build and artifact publishing) to use the directory as a YUM repository.

== Execution Context ==

<syntaxhighlight lang="text">
Buildkite Pipeline
--> .buildkite/prepare.sh (creates artifact directories)
--> .buildkite/bootstrap.sh + java.sh (Java build)
--> .buildkite/bootstrap-cmake.sh + cpp.sh (C++ build + make install)
--> .buildkite/build-rpms.sh
--> ulimit -c 0
--> make -f .copr/Makefile srpm
--> rpmbuild --rebuild ...
--> mv RPMs to artifact directory
--> createrepo
</syntaxhighlight>

== Source File Locations ==

* [https://github.com/vespa-engine/vespa/blob/master/.buildkite/build-rpms.sh <code>.buildkite/build-rpms.sh</code>] (Lines 1-30)

== See Also ==

* [[Principle:Vespa_engine_Vespa_RPM_Package_Creation|RPM Package Creation Principle]] -- The design rationale for RPM packaging in the Vespa build.
* [[Implementation:Vespa_engine_Vespa_Cpp_Sh|C++ Compilation Implementation]] -- The preceding stage that produces compiled binaries.
* [[Implementation:Vespa_engine_Vespa_Build_Container_Sh|Container Image Building Implementation]] -- The next stage that consumes RPMs.
* [[Implementation:Vespa_engine_Vespa_Publish_Artifacts_Sh|Artifact Publishing Implementation]] -- The stage that signs and uploads RPMs.

== Related Pages ==

* [[implements::Principle:Vespa_engine_Vespa_RPM_Package_Creation]]
* [[requires_env::Environment:Vespa_engine_Vespa_CMake_Cpp23_Build_Environment]]
* [[uses_heuristic::Heuristic:Vespa_engine_Vespa_Maven_Parallel_Build_Optimization]]
* [[uses_heuristic::Heuristic:Vespa_engine_Vespa_RPM_Zstd_Compression_Settings]]

[[Category:Implementations]]

[[Category:Implementations]]

Implementation:Vespa engine Vespa Build Container Sh

2026-09-27T10:53:12Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Vespa_engine_Vespa_Build_Container_Sh}}
{{PageInfo|type=Implementation|title=Vespa_engine_Vespa_Build_Container_Sh}}
{{DISPLAYTITLE:Container Build Implementation}}
[[domain::CI_CD]] [[domain::Build_Systems]]

== Overview ==

This page documents the implementation of the Vespa container image building script: ''.buildkite/build-container.sh''. This script builds two Docker images -- a Vespa preview image and a system-test image -- for the target architecture and OS combination.

'''Type:''' External Tool Doc

== Code Reference ==

<syntaxhighlight lang="bash">
#!/usr/bin/env bash
# .buildkite/build-container.sh (L1-91)

set -o errexit
set -o nounset
set -o pipefail

if [[ -n "${DEBUG:-}" ]]; then
set -o xtrace
fi

if ! docker ps &> /dev/null; then
echo "No working docker command found."
exit 1
fi

case "${VESPA_BUILDOS_LABEL}" in
alma8)
VESPA_BASE_IMAGE="el8"
SYSTEM_TEST_BASE_IMAGE="almalinux:8"
;;
alma9)
VESPA_BASE_IMAGE="el9"
SYSTEM_TEST_BASE_IMAGE="almalinux:9"
;;
*)
echo "Unknown build os: ${VESPA_BUILDOS_LABEL}" 1>&2
exit 1
;;
esac

# --- Clone docker-image repository ---
if [[ ! -d "${WORKDIR}/docker-image" ]]; then
git clone --quiet --depth 1 https://github.com/vespa-engine/docker-image "$WORKDIR/docker-image"
fi

# --- Prepare RPMs for container build ---
rm -rf "${WORKDIR}/docker-image/rpms"
cp -a "${WORKDIR}/artifacts/$ARCH/rpms" "${WORKDIR}/docker-image/"

cd "${WORKDIR}/docker-image"
SOURCE_GITREF=$(git rev-parse HEAD)

# --- Build Vespa preview container ---
GHCR_PREVIEW_TAG=ghcr.io/vespa-engine/vespa-preview-${ARCH}:${VESPA_VERSION}${VESPA_CONTAINER_IMAGE_VERSION_TAG_SUFFIX}
docker build --progress plain \
--build-arg SOURCE_GITREF="$SOURCE_GITREF" \
--build-arg VESPA_VERSION="$VESPA_VERSION" \
--build-arg VESPA_BASE_IMAGE="$VESPA_BASE_IMAGE" \
--tag vespaengine/vespa \
--tag "${GHCR_PREVIEW_TAG}" \
--file Dockerfile .

# --- Clone system-test repository ---
declare -r GITREF="${GITREF_SYSTEM_TEST:-HEAD}"

cd "$WORKDIR"
if [[ ! -d $WORKDIR/system-test ]]; then
git clone --quiet --filter="blob:none" https://github.com/vespa-engine/system-test
fi

cd system-test
git checkout "$GITREF"
mkdir -p docker/vespa-systemtests
git archive HEAD --format tar | tar x -C docker/vespa-systemtests
cd docker
rm -rf maven-repo
cp -a "$HOME/.m2/repository" maven-repo
rm -rf rpms
mv "$WORKDIR/docker-image/rpms" rpms

# --- Build system-test container ---
DOCKER_SYSTEMTEST_TAG=docker.io/vespaengine/vespa-systemtest-preview-${ARCH}:${VESPA_VERSION}${VESPA_CONTAINER_IMAGE_VERSION_TAG_SUFFIX}
docker build --progress=plain \
--build-arg BASE_IMAGE="$SYSTEM_TEST_BASE_IMAGE" \
--build-arg VESPA_BASE_IMAGE="${GHCR_PREVIEW_TAG}" \
--target systemtest \
--tag "$DOCKER_SYSTEMTEST_TAG" \
--file Dockerfile .
</syntaxhighlight>

== I/O Contract ==

=== Inputs (Environment Variables) ===

{| class="wikitable"
! Variable !! Required !! Description !! Example
|-
| <code>VESPA_BUILDOS_LABEL</code> || Yes || Build OS identifier determining base images || <code>alma8</code> or <code>alma9</code>
|-
| <code>VESPA_VERSION</code> || Yes || Version string for image tags || <code>8.432.17</code>
|-
| <code>ARCH</code> || Yes || CPU architecture identifier || <code>x86_64</code> or <code>aarch64</code>
|-
| <code>WORKDIR</code> || Yes || Working directory containing build artifacts || <code>/tmp/vespa-build</code>
|-
| <code>VESPA_CONTAINER_IMAGE_VERSION_TAG_SUFFIX</code> || Yes || Optional suffix appended to image version tags || (empty string or custom)
|-
| <code>GITREF_SYSTEM_TEST</code> || No || Git ref for system-test checkout (defaults to HEAD) || <code>abc123</code> or <code>HEAD</code>
|-
| <code>DEBUG</code> || No || If set to a non-empty value, enables bash xtrace || <code>1</code>
|}

=== Inputs (Prerequisite Files) ===

{| class="wikitable"
! File/Directory !! Produced By !! Description
|-
| <code>$WORKDIR/artifacts/$ARCH/rpms/</code> || build-rpms.sh || YUM repository with Vespa RPM packages
|-
| <code>$HOME/.m2/repository/</code> || java.sh || Maven local repository with compiled JARs
|}

=== Inputs (External Repositories) ===

{| class="wikitable"
! Repository !! URL !! Purpose
|-
| docker-image || <code>https://github.com/vespa-engine/docker-image</code> || Contains Dockerfile for the Vespa production image
|-
| system-test || <code>https://github.com/vespa-engine/system-test</code> || Contains test framework and system-test Dockerfile
|}

=== Outputs (Docker Images) ===

{| class="wikitable"
! Image !! Tag !! Description
|-
| Vespa Preview || <code>ghcr.io/vespa-engine/vespa-preview-${ARCH}:${VESPA_VERSION}${SUFFIX}</code> || Production Vespa image
|-
| Vespa Preview (local) || <code>vespaengine/vespa</code> || Local tag for the production image
|-
| System Test Preview || <code>docker.io/vespaengine/vespa-systemtest-preview-${ARCH}:${VESPA_VERSION}${SUFFIX}</code> || System test image with test frameworks
|}

== Key Implementation Details ==

=== Docker Availability Check ===

<syntaxhighlight lang="bash">
if ! docker ps &> /dev/null; then
echo "No working docker command found."
exit 1
fi
</syntaxhighlight>

The script immediately verifies that the Docker daemon is accessible by running <code>docker ps</code> and redirecting all output to <code>/dev/null</code>. This provides an early, clear failure message if Docker is not available, rather than a confusing error later during the build.

=== Base Image Selection ===

<syntaxhighlight lang="bash">
case "${VESPA_BUILDOS_LABEL}" in
alma8)
VESPA_BASE_IMAGE="el8"
SYSTEM_TEST_BASE_IMAGE="almalinux:8"
;;
alma9)
VESPA_BASE_IMAGE="el9"
SYSTEM_TEST_BASE_IMAGE="almalinux:9"
;;
*)
echo "Unknown build os: ${VESPA_BUILDOS_LABEL}" 1>&2
exit 1
;;
esac
</syntaxhighlight>

The <code>case</code> statement maps the build OS label to two different base image references:
* <code>VESPA_BASE_IMAGE</code> uses a short label (<code>el8</code>/<code>el9</code>) that is resolved inside the Dockerfile to the appropriate internal base image.
* <code>SYSTEM_TEST_BASE_IMAGE</code> uses a full Docker Hub reference (<code>almalinux:8</code>/<code>almalinux:9</code>) for the system test base.

=== Docker-Image Repository Cloning ===

<syntaxhighlight lang="bash">
if [[ ! -d "${WORKDIR}/docker-image" ]]; then
git clone --quiet --depth 1 https://github.com/vespa-engine/docker-image "$WORKDIR/docker-image"
fi
rm -rf "${WORKDIR}/docker-image/rpms"
cp -a "${WORKDIR}/artifacts/$ARCH/rpms" "${WORKDIR}/docker-image/"
</syntaxhighlight>

The docker-image repository is cloned with <code>--depth 1</code> (shallow clone) for minimal download. The built RPMs are then copied into the clone to serve as the Docker build context. The <code>cp -a</code> flag preserves file attributes and timestamps.

=== Vespa Preview Image Build ===

The Docker build uses three build arguments:
* <code>SOURCE_GITREF</code>: The git commit hash of the docker-image repo, used for image metadata.
* <code>VESPA_VERSION</code>: Baked into the image for runtime version reporting.
* <code>VESPA_BASE_IMAGE</code>: Selects the OS variant within the Dockerfile.

Two tags are applied: a local tag (<code>vespaengine/vespa</code>) used as the base for the system-test image, and a GHCR preview tag for registry storage.

=== System-Test Image Build ===

The system-test build is more involved:

# The system-test repository is cloned with <code>--filter="blob:none"</code> (blobless clone) for efficiency.
# A specific git ref is checked out (defaulting to HEAD).
# <code>git archive HEAD | tar x</code> exports the test framework without <code>.git</code> metadata.
# The Maven repository and RPMs are copied into the Docker build context.
# The image is built with <code>--target systemtest</code>, using a multi-stage Dockerfile.

The <code>--target systemtest</code> flag selects the systemtest stage in the multi-stage Dockerfile, which extends the base Vespa image with test dependencies.

=== RPM Movement Between Images ===

After the Vespa preview image is built, the RPMs are moved (not copied) from the docker-image context into the system-test context:

<syntaxhighlight lang="bash">
rm -rf rpms
mv "$WORKDIR/docker-image/rpms" rpms
</syntaxhighlight>

Using <code>mv</code> instead of <code>cp</code> avoids doubling the disk usage for the RPM repository.

== Execution Context ==

<syntaxhighlight lang="text">
Buildkite Pipeline
--> .buildkite/build-rpms.sh (produces RPMs)
--> .buildkite/build-container.sh
--> Verify Docker availability
--> Map VESPA_BUILDOS_LABEL to base images
--> Clone vespa-engine/docker-image (shallow)
--> Copy RPMs into docker-image context
--> docker build (Vespa preview image)
--> Clone vespa-engine/system-test (blobless)
--> Prepare test context (git archive, copy Maven repo)
--> docker build --target systemtest (system-test image)
</syntaxhighlight>

== Source File Locations ==

* [https://github.com/vespa-engine/vespa/blob/master/.buildkite/build-container.sh <code>.buildkite/build-container.sh</code>] (Lines 1-91)

== See Also ==

* [[Principle:Vespa_engine_Vespa_Container_Image_Building|Container Image Building Principle]] -- The design rationale for Vespa container images.
* [[Implementation:Vespa_engine_Vespa_Build_Rpms_Sh|RPM Build Implementation]] -- The preceding stage that produces the RPMs installed in the image.
* [[Implementation:Vespa_engine_Vespa_Publish_Artifacts_Sh|Artifact Publishing Implementation]] -- The stage that signs and uploads build artifacts.

== Related Pages ==

* [[implements::Principle:Vespa_engine_Vespa_Container_Image_Building]]
* [[requires_env::Environment:Vespa_engine_Vespa_Docker_OCI_Container_Runtime]]

[[Category:Implementations]]

[[Category:Implementations]]

Implementation:Vespa engine Vespa Bootstrap Cmake Sh

2026-09-27T10:53:12Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Vespa_engine_Vespa_Bootstrap_Cmake_Sh}}
{{PageInfo|type=Implementation|title=Vespa_engine_Vespa_Bootstrap_Cmake_Sh}}
{{DISPLAYTITLE:CMake Configuration Implementation}}
[[domain::CI_CD]] [[domain::Build_Systems]]

== Overview ==

This page documents the implementation of the Vespa CMake configuration script: ''.buildkite/bootstrap-cmake.sh''. This script sets up the build environment, resolves sanitizer and ccache options, and invokes CMake to generate Makefiles for the C++ build.

'''Type:''' External Tool Doc

== Code Reference ==

<syntaxhighlight lang="bash">
#!/usr/bin/env bash
# .buildkite/bootstrap-cmake.sh (L1-35)

set -o errexit
set -o nounset
set -o pipefail

if [[ -n "${DEBUG:-}" ]]; then
set -o xtrace
fi

echo "--- Configuring CMake build"
# shellcheck disable=1091
source /etc/profile.d/enable-gcc-toolset.sh

PATH=/opt/vespa-deps/bin:$PATH

VESPA_CMAKE_SANITIZERS_OPTION=""
VESPA_CMAKE_CCACHE_OPTION=""
if [[ $VESPA_USE_SANITIZER != null ]]; then
echo "Enabling sanitizer: $VESPA_USE_SANITIZER"
VESPA_CMAKE_SANITIZERS_OPTION="-DVESPA_USE_SANITIZER=$VESPA_USE_SANITIZER"
VESPA_CMAKE_CCACHE_OPTION="-DVESPA_USE_CCACHE=false"
VALGRIND_UNIT_TESTS=false
fi
if [[ $BUILDKITE_PULL_REQUEST != "false" ]]; then
VALGRIND_UNIT_TESTS=false
fi

echo "Running CMake configuration..."
cmake -DVESPA_UNPRIVILEGED=no -DVALGRIND_UNIT_TESTS="$VALGRIND_UNIT_TESTS" \
"$VESPA_CMAKE_SANITIZERS_OPTION" "$VESPA_CMAKE_CCACHE_OPTION" "$SOURCE_DIR"
</syntaxhighlight>

== I/O Contract ==

=== Inputs (Environment Variables) ===

{| class="wikitable"
! Variable !! Required !! Description !! Example
|-
| <code>VESPA_USE_SANITIZER</code> || Yes || Sanitizer type to enable, or <code>null</code> for none || <code>address</code>, <code>thread</code>, or <code>null</code>
|-
| <code>BUILDKITE_PULL_REQUEST</code> || Yes || PR number or <code>"false"</code> if this is not a PR build || <code>35801</code> or <code>false</code>
|-
| <code>VALGRIND_UNIT_TESTS</code> || Yes || Initial setting for Valgrind test enablement || <code>true</code> or <code>false</code>
|-
| <code>SOURCE_DIR</code> || Yes || Absolute path to the Vespa source checkout || <code>/vespa</code>
|-
| <code>DEBUG</code> || No || If set to a non-empty value, enables bash xtrace || <code>1</code>
|}

=== Inputs (System Dependencies) ===

{| class="wikitable"
! Dependency !! Path !! Purpose
|-
| GCC Toolset || <code>/etc/profile.d/enable-gcc-toolset.sh</code> || Activates the GCC 12+ compiler suite
|-
| Vespa Dependencies || <code>/opt/vespa-deps/bin</code> || Pre-built libraries (protobuf, abseil, gRPC, etc.)
|-
| CMake || System PATH (after deps setup) || Build system generator
|}

=== Outputs (Files) ===

{| class="wikitable"
! Output !! Type !! Description
|-
| <code>Makefile</code> || Generated file || Top-level Makefile for the C++ build
|-
| <code>CMakeCache.txt</code> || Generated file || Cache of all resolved CMake variables
|-
| Subdirectory Makefiles || Generated files || Per-module Makefiles for each CMakeLists.txt
|-
| Generated headers || Generated files || Platform-specific config headers (e.g., <code>config.h</code>)
|}

== Key Implementation Details ==

=== Sanitizer Option Resolution ===

The script determines sanitizer and ccache options through conditional logic:

<syntaxhighlight lang="bash">
VESPA_CMAKE_SANITIZERS_OPTION=""
VESPA_CMAKE_CCACHE_OPTION=""
if [[ $VESPA_USE_SANITIZER != null ]]; then
VESPA_CMAKE_SANITIZERS_OPTION="-DVESPA_USE_SANITIZER=$VESPA_USE_SANITIZER"
VESPA_CMAKE_CCACHE_OPTION="-DVESPA_USE_CCACHE=false"
VALGRIND_UNIT_TESTS=false
fi
</syntaxhighlight>

When a sanitizer is active:
* The corresponding CMake variable is set (e.g., <code>-DVESPA_USE_SANITIZER=address</code>).
* Ccache is explicitly disabled to prevent cache poisoning with sanitizer-instrumented object files.
* Valgrind is disabled because sanitizers already provide memory error detection.

=== Pull Request Optimization ===

For pull request builds, Valgrind unit tests are unconditionally disabled:

<syntaxhighlight lang="bash">
if [[ $BUILDKITE_PULL_REQUEST != "false" ]]; then
VALGRIND_UNIT_TESTS=false
fi
</syntaxhighlight>

This reduces PR build times significantly since Valgrind adds 10-50x overhead to test execution. Full Valgrind testing is reserved for post-merge builds on the main branch.

=== CMake Variable Passing ===

The variables <code>$VESPA_CMAKE_SANITIZERS_OPTION</code> and <code>$VESPA_CMAKE_CCACHE_OPTION</code> are passed as unquoted arguments to CMake. When they are empty strings, Bash word splitting causes them to be omitted entirely, which is the desired behavior -- CMake receives no sanitizer or ccache flags when they are not configured.

=== GCC Toolset and Dependency Path ===

The script sets up the compilation environment before invoking CMake:

<syntaxhighlight lang="bash">
source /etc/profile.d/enable-gcc-toolset.sh
PATH=/opt/vespa-deps/bin:$PATH
</syntaxhighlight>

This ensures that:
* CMake detects the correct C++ compiler (GCC 12+ with C++20 support).
* <code>find_package()</code> calls in CMakeLists.txt files can locate pre-built Vespa dependency libraries under <code>/opt/vespa-deps/</code>.

=== VESPA_UNPRIVILEGED Flag ===

The <code>-DVESPA_UNPRIVILEGED=no</code> flag tells CMake that the build targets a privileged (root) installation. This affects installation paths, file permissions, and systemd service configurations in the generated build system.

== Execution Context ==

This script is invoked from the Buildkite pipeline after the Java bootstrap has completed. It runs in the build directory (not the source directory), creating an out-of-source build:

<syntaxhighlight lang="text">
Buildkite Pipeline
--> .buildkite/bootstrap.sh (Java bootstrap)
--> cd $BUILD_DIR
--> .buildkite/bootstrap-cmake.sh
--> source enable-gcc-toolset.sh
--> cmake ... $SOURCE_DIR
--> .buildkite/cpp.sh (uses generated Makefiles)
</syntaxhighlight>

== Source File Locations ==

* [https://github.com/vespa-engine/vespa/blob/master/.buildkite/bootstrap-cmake.sh <code>.buildkite/bootstrap-cmake.sh</code>] (Lines 1-35)

== See Also ==

* [[Principle:Vespa_engine_Vespa_CMake_Configuration|CMake Configuration Principle]] -- The design rationale for CMake configuration in the Vespa build.
* [[Implementation:Vespa_engine_Vespa_Cpp_Sh|C++ Compilation Implementation]] -- The next stage that runs <code>make</code> on the generated Makefiles.
* [[Implementation:Vespa_engine_Vespa_Bootstrap_And_Java_Sh|Bootstrap and Java Build Implementation]] -- The preceding stage that produces JAR dependencies for CMake.

== Related Pages ==

* [[implements::Principle:Vespa_engine_Vespa_CMake_Configuration]]
* [[requires_env::Environment:Vespa_engine_Vespa_CMake_Cpp23_Build_Environment]]

[[Category:Implementations]]

[[Category:Implementations]]

Implementation:Vespa engine Vespa Bootstrap And Java Sh

2026-09-27T10:53:11Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Vespa_engine_Vespa_Bootstrap_And_Java_Sh}}
{{PageInfo|type=Implementation|title=Vespa_engine_Vespa_Bootstrap_And_Java_Sh}}
{{DISPLAYTITLE:Bootstrap and Java Build Implementation}}
[[domain::CI_CD]] [[domain::Build_Systems]]

== Overview ==

This page documents the implementation of the Vespa Java bootstrap and Maven build scripts: ''.buildkite/bootstrap.sh'', ''.buildkite/java.sh'', and the root-level ''bootstrap.sh''. Together these scripts set up the Maven wrapper, build parent POMs and plugins, compile all Java modules, and collect JAR files needed by C++ tests.

'''Type:''' External Tool Doc

== Code Reference ==

=== .buildkite/bootstrap.sh ===

<syntaxhighlight lang="bash">
#!/usr/bin/env bash
# .buildkite/bootstrap.sh (L1-24)

set -o errexit
set -o nounset
set -o pipefail

if [[ -n "${DEBUG:-}" ]]; then
set -o xtrace
fi

echo "--- Running Vespa bootstrap"
cd "$SOURCE_DIR"
./bootstrap.sh full

echo "Setting up test JAR directory..."
mkdir -p "$VESPA_CPP_TEST_JARS"

echo "Collecting JAR files for C++ tests..."
# shellcheck disable=2038
find . -type d -name target -exec find {} -mindepth 1 -maxdepth 1 -name "*.jar" \; \
| xargs -I '{}' cp '{}' "$VESPA_CPP_TEST_JARS"
</syntaxhighlight>

=== .buildkite/java.sh ===

<syntaxhighlight lang="bash">
#!/usr/bin/env bash
# .buildkite/java.sh (L1-31)

set -o errexit
set -o nounset
set -o pipefail

if [[ -n "${DEBUG:-}" ]]; then
set -o xtrace
fi

mydir=${0%/*}
shlim=${mydir}/show-limits.sh
if [ -x "${shlim}" ]; then
"${shlim}" || echo "failed: ${shlim}"
fi

echo "--- Building Java components"
# shellcheck disable=1091
source /etc/profile.d/enable-gcc-toolset.sh

PATH=/opt/vespa-deps/bin:$PATH

cd "$SOURCE_DIR"

echo "Running Maven build with target: ${VESPA_MAVEN_TARGET} [threads: ${NUM_MVN_THREADS}]"
read -ra MVN_EXTRA_OPTS <<< "$VESPA_MAVEN_EXTRA_OPTS"
./mvnw -T "$NUM_MVN_THREADS" "${MVN_EXTRA_OPTS[@]}" "$VESPA_MAVEN_TARGET"
</syntaxhighlight>

=== bootstrap.sh (Root-Level) ===

<syntaxhighlight lang="bash">
#!/usr/bin/env bash
# bootstrap.sh (L1-133) -- key sections shown

# Mode selection: full | java | default | wrapper
MODE=$1 # or "default" if no argument

# Maven wrapper setup
MAVEN_CMD=$(get_env_var_with_optional_default VESPA_MAVEN_COMMAND "$(pwd)/mvnw")
mvn -B wrapper:wrapper -Dmaven=3.9.12 -N ${MAVEN_EXTRA_OPTS}

# Proxy script allowing plain "mvn" to use the wrapper
wbdir=maven-wrapper/bin
mkdir -p ${wbdir}
printf '#!/bin/sh\nexec %s/mvnw "$@"\n' "$(pwd)" > ${wbdir}/mvn
chmod +x ${wbdir}/mvn

# Core build function
mvn_install() {
${MAVEN_CMD} --batch-mode --no-snapshot-updates \
-Dmaven.wagon.http.retryHandler.count=5 \
clean "${MAVEN_TARGET}" ${MAVEN_EXTRA_OPTS} "$@"
}

# Build order:
# 1. Parent POMs (dependency-versions, container-dependency-versions, parent)
# 2. Root POM (non-recursive)
# 3. Maven plugins
# 4. Mode-specific modules (full mode: jrt, linguistics, messagebus)

cd dependency-versions && mvn_install
cd container-dependency-versions && mvn_install
cd parent && mvn_install
mvn_install -N
mvn_install -f maven-plugins/pom.xml

# Full mode: build C++ test dependencies
mvn_install -am -T1C -Dmaven.test.skip=true \
-Dmaven.javadoc.skip=true -Dmaven.source.skip=true \
-pl jrt,linguistics,messagebus
</syntaxhighlight>

== I/O Contract ==

=== Inputs (Environment Variables) ===

{| class="wikitable"
! Variable !! Required !! Script !! Description !! Example
|-
| <code>SOURCE_DIR</code> || Yes || bootstrap.sh, java.sh || Root directory of the Vespa source checkout || <code>/vespa</code>
|-
| <code>VESPA_CPP_TEST_JARS</code> || Yes || bootstrap.sh || Destination directory for collected JAR files || <code>/tmp/vespa-build/test-jars</code>
|-
| <code>NUM_MVN_THREADS</code> || Yes || java.sh || Number of parallel Maven threads || <code>4</code>
|-
| <code>VESPA_MAVEN_TARGET</code> || Yes || java.sh, bootstrap.sh || Maven lifecycle target || <code>install</code>
|-
| <code>VESPA_MAVEN_EXTRA_OPTS</code> || Yes || java.sh, bootstrap.sh || Additional Maven options || <code>-Dmaven.test.skip=true</code>
|-
| <code>VESPA_MAVEN_COMMAND</code> || No || bootstrap.sh || Override for Maven command path || <code>./mvnw</code>
|-
| <code>MAVEN_OPTS</code> || No || java.sh || JVM arguments for Maven process || <code>-Xms256m -Xmx2g</code>
|-
| <code>DEBUG</code> || No || All || Enables bash xtrace when non-empty || <code>1</code>
|}

=== Outputs (Files and Artifacts) ===

{| class="wikitable"
! Output !! Produced By !! Description
|-
| <code>./mvnw</code> || bootstrap.sh (root) || Maven wrapper script (Maven 3.9.12)
|-
| <code>maven-wrapper/bin/mvn</code> || bootstrap.sh (root) || Proxy script redirecting <code>mvn</code> to the wrapper
|-
| <code>~/.m2/repository/</code> || bootstrap.sh (root), java.sh || Local Maven repository containing all compiled JARs
|-
| <code>$VESPA_CPP_TEST_JARS/*.jar</code> || .buildkite/bootstrap.sh || Flat directory of JAR files needed by C++ tests
|-
| <code>dist/vtag.map</code> || bootstrap.sh (root) || Version tag map generated by <code>getversionmap.sh</code>
|}

== Key Implementation Details ==

=== Maven Wrapper Setup ===

The root ''bootstrap.sh'' installs the Maven wrapper at a pinned version (3.9.12):

<syntaxhighlight lang="bash">
mvn -B wrapper:wrapper -Dmaven=3.9.12 -N ${MAVEN_EXTRA_OPTS}
</syntaxhighlight>

The <code>-N</code> (non-recursive) flag ensures only the root module is processed. After installation, a proxy script is created at <code>maven-wrapper/bin/mvn</code> so that any script invoking plain <code>mvn</code> transparently uses the wrapper instead.

=== Build Order in bootstrap.sh ===

The root bootstrap script enforces a specific build order due to Maven's plugin resolution limitation:

# '''dependency-versions''' -- Defines version constraints for third-party dependencies.
# '''container-dependency-versions''' -- Defines version constraints for container-related dependencies.
# '''parent''' -- The parent POM that all modules inherit from.
# '''Root POM''' (non-recursive) -- Installs the root aggregator POM.
# '''maven-plugins''' -- Custom Maven plugins used by other modules.
# '''Mode-specific modules''' -- In <code>full</code> mode, builds <code>jrt</code>, <code>linguistics</code>, and <code>messagebus</code> with <code>-am</code> (also-make-dependencies) and <code>-T1C</code> (one thread per core).

=== JAR Collection for C++ Tests ===

The ''.buildkite/bootstrap.sh'' script uses a nested <code>find</code> command to locate all JAR files:

<syntaxhighlight lang="bash">
find . -type d -name target -exec find {} -mindepth 1 -maxdepth 1 -name "*.jar" \; \
| xargs -I '{}' cp '{}' "$VESPA_CPP_TEST_JARS"
</syntaxhighlight>

This two-level find first locates all Maven <code>target/</code> directories, then within each one finds JAR files at the top level (not in subdirectories). The JARs are copied into a flat directory for easy classpath construction by C++ test binaries.

=== GCC Toolset and PATH Setup ===

The ''.buildkite/java.sh'' script activates the GCC toolset and adds Vespa dependency binaries to the PATH before invoking Maven:

<syntaxhighlight lang="bash">
source /etc/profile.d/enable-gcc-toolset.sh
PATH=/opt/vespa-deps/bin:$PATH
</syntaxhighlight>

This is necessary because some Java modules contain JNI (Java Native Interface) code that requires native compilation during the Maven build.

=== Resource Limit Reporting ===

Before starting the build, ''java.sh'' optionally executes <code>show-limits.sh</code> to log system resource limits (e.g., open file descriptors, stack size). This diagnostic output helps troubleshoot build failures caused by resource exhaustion.

== Execution Context ==

The typical invocation sequence in the Buildkite pipeline is:

<syntaxhighlight lang="text">
Buildkite Pipeline
--> .buildkite/bootstrap.sh
--> cd $SOURCE_DIR && ./bootstrap.sh full
--> mvn wrapper:wrapper (Maven 3.9.12)
--> mvn_install dependency-versions
--> mvn_install container-dependency-versions
--> mvn_install parent
--> mvn_install -N (root POM)
--> mvn_install maven-plugins
--> mvn_install jrt,linguistics,messagebus
--> mkdir -p $VESPA_CPP_TEST_JARS
--> find + xargs cp (collect JARs)
--> .buildkite/java.sh
--> source enable-gcc-toolset.sh
--> ./mvnw -T $NUM_MVN_THREADS $VESPA_MAVEN_EXTRA_OPTS $VESPA_MAVEN_TARGET
</syntaxhighlight>

== Source File Locations ==

* [https://github.com/vespa-engine/vespa/blob/master/.buildkite/bootstrap.sh <code>.buildkite/bootstrap.sh</code>] (Lines 1-24)
* [https://github.com/vespa-engine/vespa/blob/master/.buildkite/java.sh <code>.buildkite/java.sh</code>] (Lines 1-31)
* [https://github.com/vespa-engine/vespa/blob/master/bootstrap.sh <code>bootstrap.sh</code>] (Lines 1-133)

== See Also ==

* [[Principle:Vespa_engine_Vespa_Java_Bootstrap_and_Maven_Build|Java Bootstrap and Maven Build Principle]] -- The design rationale for the two-phase Java build.
* [[Implementation:Vespa_engine_Vespa_Prepare_Sh|Prepare.sh Implementation]] -- The preceding pipeline stage.
* [[Implementation:Vespa_engine_Vespa_Bootstrap_Cmake_Sh|CMake Configuration Implementation]] -- The next stage that depends on bootstrap output.

== Related Pages ==

* [[implements::Principle:Vespa_engine_Vespa_Java_Bootstrap_and_Maven_Build]]
* [[requires_env::Environment:Vespa_engine_Vespa_Java_17_Build_Runtime]]
* [[uses_heuristic::Heuristic:Vespa_engine_Vespa_Maven_Parallel_Build_Optimization]]

[[Category:Implementations]]

[[Category:Implementations]]

Implementation:Turboderp org Exllamav2 WebSocket Actions

2026-09-27T10:53:10Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Turboderp_org_Exllamav2_WebSocket_Actions}}
{| class="wikitable" style="float:right; margin-left:1em; width:300px;"
|-
! Knowledge Sources
|
* [https://github.com/turboderp-org/exllamav2 Turboderp_org_Exllamav2]
|-
! Domains
| [[domain::Server]], [[domain::WebSocket]], [[domain::Text_Generation]]
|-
! Last Updated
| [[last_updated::2026-02-15 00:00 GMT]]
|}

== Overview ==

The '''WebSocket_Actions''' module defines the request handler functions for the ExLlamaV2 WebSocket server, including token estimation, text trimming, streaming inference, and interrupt control.

=== Description ===

This module contains the action handler functions that are dispatched by '''ExLlamaV2WebSocketServer'''. The '''dispatch()''' function routes incoming JSON requests based on the '''action''' field to the appropriate handler. Each handler receives the parsed request dict, the WebSocket connection, the server instance, and a pre-initialized response dict.

The available actions are:

* '''echo''' - Returns the response with only the echoed request/response IDs. Used as a ping/health check.

* '''estimate_token''' - Encodes the provided '''text''' using the server's tokenizer and returns the token count as '''num_tokens'''. Useful for clients to estimate prompt length before sending an inference request.

* '''lefttrim_token''' - Encodes the input '''text''', trims from the left to keep only '''trimmed_length''' tokens from the right, then decodes back to text. Returns '''trimmed_text'''. This is used for context window management.

* '''infer''' - The main generation handler (async). Acquires the '''model_lock''' to ensure exclusive model access. Configures sampler settings from request parameters (top_k, top_p, top_a, min_p, typical, temperature, skew, repetition/frequency/presence penalties). Handles prompt tokenization, context overflow trimming, custom BOS tokens, stop conditions, and token healing. Generates tokens in a streaming loop, sending '''response_type: "chunk"''' messages for each generated piece of text. Supports '''stream_full''' mode where each chunk message includes the full response so far. Generation terminates on EOS, max tokens reached, or the '''stop_signal''' being set. The final response has '''response_type: "full"''' with the complete text and '''stop_reason''' ("eos", "num_tokens", or "interrupted").

* '''stop''' - Sets the server's '''stop_signal''' event to interrupt any active inference. The next iteration of the infer loop will detect the signal and terminate.

=== Usage ===

These functions are not called directly by users. They are invoked by '''ExLlamaV2WebSocketServer.main()''' via the '''dispatch()''' function when a JSON message arrives on a WebSocket connection. Clients interact with these actions by sending appropriately formatted JSON messages.

== Code Reference ==

=== Source Location ===
* '''Repository:''' [https://github.com/turboderp-org/exllamav2 Turboderp_org_Exllamav2]
* '''File:''' [https://github.com/turboderp-org/exllamav2/blob/main/exllamav2/server/websocket_actions.py exllamav2/server/websocket_actions.py]
* '''Lines:''' 1-259

=== Signature ===
<syntaxhighlight lang="python">
async def dispatch(request: dict, ws, server) -> None: ...

def echo(request: dict, ws, server, response: dict) -> None: ...

def estimate_token(request: dict, ws, server, response: dict) -> None: ...

def lefttrim_token(request: dict, ws, server, response: dict) -> None: ...

async def infer(request: dict, ws, server, response: dict) -> None: ...

def stop(request: dict, ws, server, response: dict) -> None: ...
</syntaxhighlight>

=== Import ===
<syntaxhighlight lang="python">
from exllamav2.server import websocket_actions
</syntaxhighlight>

== I/O Contract ==

=== dispatch() ===

{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| request || <code>dict</code> || Parsed JSON request with an "action" field
|-
| ws || <code>WebSocketServerProtocol</code> || WebSocket connection for sending responses
|-
| server || <code>ExLlamaV2WebSocketServer</code> || Server instance providing model, tokenizer, generator, and locks
|}

=== infer() Request Fields ===

{| class="wikitable"
|-
! Field !! Type !! Required !! Description
|-
| action || <code>str</code> || Yes || Must be "infer"
|-
| text || <code>str</code> || Yes || Input prompt text
|-
| max_new_tokens || <code>int</code> || Yes || Maximum number of tokens to generate
|-
| stream || <code>bool</code> || Yes || Whether to stream chunk responses
|-
| stream_full || <code>bool</code> || No || If True, each chunk includes full response so far
|-
| top_k || <code>int</code> || No || Top-K sampling (default: 100, 0 to disable)
|-
| top_p || <code>float</code> || No || Top-P / nucleus sampling (default: 0.8, 0 to disable)
|-
| top_a || <code>float</code> || No || Top-A sampling threshold (default: 0)
|-
| min_p || <code>float</code> || No || Min-P sampling threshold (default: 0)
|-
| typical || <code>float</code> || No || Typical sampling threshold (default: 0)
|-
| temperature || <code>float</code> || No || Sampling temperature (default: 0.9)
|-
| skew || <code>float</code> || No || Skew factor (default: 0.0)
|-
| rep_pen || <code>float</code> || No || Repetition penalty (default: 1.05)
|-
| freq_pen || <code>float</code> || No || Frequency penalty (default: 0.0)
|-
| pres_pen || <code>float</code> || No || Presence penalty (default: 0.0)
|-
| customBos || <code>str</code> || No || Custom BOS token prepended to prompt
|-
| stop_conditions || <code>list[str|int]</code> || No || Additional stop strings/token IDs
|-
| token_healing || <code>bool</code> || No || Enable token healing (default: False)
|-
| tag || <code>str</code> || No || Echoed in response for client-side correlation
|}

=== infer() Response Format ===

{| class="wikitable"
|-
! Field !! Type !! Description
|-
| action || <code>str</code> || "infer"
|-
| response_type || <code>str</code> || "chunk" for streaming, "full" for final
|-
| chunk || <code>str</code> || Next text chunk (streaming only)
|-
| response || <code>str</code> || Full generated text (final response, or partial when stream_full=True)
|-
| util_text || <code>str</code> || Input context after overflow trimming (final response only)
|-
| stop_reason || <code>str</code> || "eos", "num_tokens", or "interrupted" (final response only)
|-
| tag || <code>str</code> || Echoed tag (if provided in request)
|-
| request_id || <code>str</code> || Echoed request ID (if provided)
|-
| response_id || <code>str</code> || Echoed response ID (if provided)
|}

== Usage Examples ==

<syntaxhighlight lang="python">
# Client-side Python example using the websockets library
import asyncio
import json
import websockets

async def chat():
async with websockets.connect("ws://localhost:7862") as ws:
# Send an inference request
request = {
"action": "infer",
"text": "Explain quantum computing in simple terms:",
"max_new_tokens": 200,
"stream": True,
"temperature": 0.7,
"top_p": 0.9,
"top_k": 50,
"rep_pen": 1.05,
"stop_conditions": ["\n\n"],
"token_healing": True,
}
await ws.send(json.dumps(request))

# Receive streaming chunks
while True:
msg = json.loads(await ws.recv())
if msg["response_type"] == "chunk":
print(msg.get("chunk", ""), end="", flush=True)
elif msg["response_type"] == "full":
print(f"\n[Stop reason: {msg['stop_reason']}]")
break

asyncio.run(chat())

# Estimate token count
# {"action": "estimate_token", "text": "Hello world"}
# Response: {"action": "estimate_token", "num_tokens": 2}

# Left-trim to fit context
# {"action": "lefttrim_token", "text": "...", "trimmed_length": 2048}
# Response: {"action": "lefttrim_token", "trimmed_text": "..."}

# Interrupt active generation
# {"action": "stop"}
</syntaxhighlight>

== Related Pages ==

* [[Implementation:Turboderp_org_Exllamav2_ExLlamaV2WebSocketServer]] - The WebSocket server that dispatches to these action handlers
* [[Implementation:Turboderp_org_Exllamav2_ExLlamaV2DynamicGeneratorAsync]] - Alternative async generation interface for more advanced use cases
* [[Implementation:Turboderp_org_Exllamav2_ExLlamaV2TokenizerBase]] - Base tokenizer class used for encoding/decoding in these actions

[[Category:Implementations]]

Implementation:Turboderp org Exllamav2 ThreadPool

2026-09-27T10:53:10Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Turboderp_org_Exllamav2_ThreadPool}}
{| class="wikitable" style="float:right; margin-left:1em; width:300px;"
|-
! Knowledge Sources
|
* [https://github.com/turboderp-org/exllamav2 Turboderp_org_Exllamav2]
|-
! Domains
| [[domain::Concurrency]], [[domain::C_Extension]]
|-
! Last Updated
| [[last_updated::2026-02-15 00:00 GMT]]
|}

== Overview ==

Header-only C++ library providing a '''ThreadPool''' class for asynchronous task execution and a '''Barrier''' class for thread synchronization, used throughout ExLlamaV2's C++ extension layer.

=== Description ===

'''threadpool.h''' defines two concurrency primitives:

'''ThreadPool''' implements a classic thread pool pattern with:
* A configurable number of worker threads created at construction time via '''ThreadPool(size_t threads)'''.
* A task queue protected by a '''std::mutex''' and signaled via a '''std::condition_variable'''.
* A templated '''enqueue()''' method that accepts any callable with arguments and returns a '''std::future''' for the result, allowing callers to submit work and retrieve results asynchronously.
* Worker threads that loop indefinitely, waiting on the condition variable for new tasks. They exit cleanly when '''stop''' is set to true and the queue is drained.
* The destructor sets the stop flag, notifies all workers, and joins all threads to ensure clean shutdown.

'''Barrier''' implements a reusable synchronization barrier with:
* '''arrive_and_wait()''' -- Each thread increments a counter; when the counter reaches '''num_threads''', the generation is advanced and all waiting threads are released via '''cv.notify_all()'''. Threads that arrive early wait on a condition variable gated by the generation counter, preventing spurious wakeups.
* '''reset(int new_num_threads)''' -- Dynamically changes the thread count, resets the counter, advances the generation to unblock any currently waiting threads, and notifies all.

=== Usage ===

The '''ThreadPool''' is used by '''ExtTPContext''' (tensor parallelism context) to dispatch parallel operations across multiple GPU devices. The '''Barrier''' is used for cross-device synchronization points during tensor-parallel inference, ensuring all devices have completed a phase before proceeding.

== Code Reference ==

=== Source Location ===
* '''Repository:''' [https://github.com/turboderp-org/exllamav2 Turboderp_org_Exllamav2]
* '''File:''' [https://github.com/turboderp-org/exllamav2/blob/main/exllamav2/exllamav2_ext/cpp/threadpool.h exllamav2/exllamav2_ext/cpp/threadpool.h]
* '''Lines:''' 1-124

=== Signature ===
<syntaxhighlight lang="cpp">
class ThreadPool
{
public:
ThreadPool(size_t threads);
~ThreadPool();

template<class F, class... Args>
auto enqueue(F&& f, Args&&... args)
-> std::future<typename std::result_of<F(Args...)>::type>;
};

class Barrier
{
public:
Barrier(int num_threads);
void arrive_and_wait();
void reset(int new_num_threads);
};
</syntaxhighlight>

=== Import ===
<syntaxhighlight lang="cpp">
#include "threadpool.h"
</syntaxhighlight>

== I/O Contract ==

{| class="wikitable"
|-
! Class !! Method !! Input !! Output !! Description
|-
| '''ThreadPool''' || constructor || size_t threads || ThreadPool instance || Creates pool with specified number of worker threads
|-
| '''ThreadPool''' || enqueue(f, args...) || Callable + arguments || std::future<return_type> || Submits task, returns future for asynchronous result retrieval
|-
| '''ThreadPool''' || destructor || -- || -- || Sets stop flag, notifies all workers, joins all threads
|-
| '''Barrier''' || constructor || int num_threads || Barrier instance || Creates barrier for the specified number of participating threads
|-
| '''Barrier''' || arrive_and_wait() || -- || -- || Blocks until all threads have arrived; uses generation counter to prevent spurious wakeups
|-
| '''Barrier''' || reset(new_num_threads) || int new_num_threads || -- || Resets barrier for a new thread count, unblocks any waiting threads
|}

== Usage Examples ==
<syntaxhighlight lang="cpp">
#include "threadpool.h"

// Create a pool with 4 worker threads
ThreadPool pool(4);

// Submit tasks and collect futures
std::vector<std::future<int>> results;
for (int i = 0; i < 8; i++) {
results.push_back(pool.enqueue([i] {
// perform work on device i % 4
return i * i;
}));
}

// Collect results
for (auto& f : results) {
int result = f.get();
}

// Barrier usage for synchronizing 4 threads
Barrier barrier(4);
// Each thread calls:
barrier.arrive_and_wait(); // blocks until all 4 arrive
</syntaxhighlight>

== Related Pages ==
* [[Implementation:Turboderp_org_Exllamav2_Ext_TP_H]] -- Tensor parallelism context that uses ThreadPool and Barrier

[[Category:Implementations]]

Implementation:Turboderp org Exllamav2 Softmax AVX2

2026-09-27T10:53:10Z

Agent: Sync from local file

{{PageInfo|type=Implementation|title=Turboderp_org_Exllamav2_Softmax_AVX2}}
{| class="wikitable" style="float:right; margin-left:1em; width:300px;"
|-
! Knowledge Sources
|
* [https://github.com/turboderp-org/exllamav2 Turboderp_org_Exllamav2]
|-
! Domains
| [[domain::Sampling]], [[domain::SIMD]], [[domain::Performance_Optimization]]
|-
! Last Updated
| [[last_updated::2026-02-15 00:00 GMT]]
|}

== Overview ==

AVX2-optimized implementation of the softmax function that converts raw logits into a probability distribution using SIMD vectorized operations for high-throughput CPU-side sampling.

=== Description ===

'''softmax_cpu_avx2''' provides a performance-critical softmax implementation that leverages Intel AVX2 (256-bit SIMD) intrinsics to process 8 float values simultaneously. The function aligns the vocabulary size to a 32-element boundary for optimal vector processing.

The implementation handles three distinct code paths based on the '''exponent''' parameter:

* '''exponent == 2.0f (fast path):''' Uses a squared subtraction approach where logit differences from the maximum are squared, negated via XOR with a sign mask, and then multiplied by the inverse temperature before exponentiation. This avoids the expensive '''powf''' call entirely by leveraging SIMD multiply and XOR operations.
* '''exponent == 1.0f (standard path):''' The classic softmax with temperature. If temperature is exactly 1.0, the inverse-temperature multiply is skipped as an additional optimization. Uses '''exp256_ps''' (vectorized exp from '''avx_mathfun.h''') for SIMD exponentiation.
* '''exponent != 1.0f and != 2.0f (fallback path):''' Falls back to scalar '''powf''' and '''expf''' calls per element, as arbitrary exponents cannot be efficiently vectorized.

The normalization phase accumulates the exponential sum across 8 SIMD lanes, reduces it to a scalar, and then divides all probabilities by the sum using vectorized multiply with the reciprocal.

On non-x86 platforms (e.g., aarch64), a dummy fallback function is compiled that returns 0, ensuring the build does not fail.

=== Usage ===

This function is called as a drop-in replacement for the scalar '''softmax_cpu''' when the build detects AVX2 support ('''USE_AVX2''' preprocessor macro). It is used in the sampling pipeline to convert model logits into probabilities before top-K, top-P, and other filtering stages are applied.

== Code Reference ==

=== Source Location ===
* '''Repository:''' [https://github.com/turboderp-org/exllamav2 Turboderp_org_Exllamav2]
* '''File:''' [https://github.com/turboderp-org/exllamav2/blob/main/exllamav2/exllamav2_ext/cpp/sampling_avx2.cpp exllamav2/exllamav2_ext/cpp/sampling_avx2.cpp]
* '''Lines:''' 1-166

=== Signature ===
<syntaxhighlight lang="cpp">
AVX2_TARGET
int softmax_cpu_avx2(
const int vocab_size,
const float temperature,
const float* logits,
const bool* logits_filter,
const float exponent,
float* output
);
</syntaxhighlight>

=== Import ===
<syntaxhighlight lang="cpp">
#include "sampling_avx2.h"
</syntaxhighlight>

== I/O Contract ==

{| class="wikitable"
|-
! Parameter !! Type !! Direction !! Description
|-
| '''vocab_size''' || const int || in || Size of the vocabulary (number of logits)
|-
| '''temperature''' || const float || in || Softmax temperature; higher values produce more uniform distributions
|-
| '''logits''' || const float* || in || Raw logit values from the model, length = vocab_size
|-
| '''logits_filter''' || const bool* || in || Optional filter mask; NULL means all tokens allowed, true = allowed
|-
| '''exponent''' || const float || in || Exponent applied to logit differences (1.0 = standard, 2.0 = quadratic fast path)
|-
| '''output''' || float* || out || Probability distribution, must be aligned to 32 floats (vocab_size_aligned)
|}

{| class="wikitable"
|-
! Return !! Type !! Description
|-
| max logit index || int || Index of the token with the highest raw logit value
|}

== Usage Examples ==
<syntaxhighlight lang="cpp">
#include "sampling_avx2.h"

// Allocate aligned output buffer (32-element aligned)
int vocab_size = 32000;
int aligned_size = ((vocab_size + 31) / 32) * 32;
float* output = (float*)aligned_alloc(32, aligned_size * sizeof(float));

// Standard softmax with temperature=0.8
int max_idx = softmax_cpu_avx2(vocab_size, 0.8f, logits, nullptr, 1.0f, output);

// Quadratic softmax (exponent=2.0) with logit filtering
bool logit_filter[32000];
// ... set filter values ...
int max_idx2 = softmax_cpu_avx2(vocab_size, 1.0f, logits, logit_filter, 2.0f, output);
</syntaxhighlight>

== Related Pages ==
* [[Implementation:Turboderp_org_Exllamav2_Sampling_H]] -- Header declaring all sampling function signatures
* [[Implementation:Turboderp_org_Exllamav2_Ext_Norm]] -- GPU normalization operations

[[Category:Implementations]]