Merge branch 'main' into docs/add-testing-guide

Author: ajcasagrande

.github/workflows/pre-commit.yml

@@ -24,8 +24,7 @@ jobs:
 
     - name: Install dependencies
       run: |
-        make setup-venv
-        make setup-mkinit
+        make first-time-setup PYTHON_VERSION=3.10
 
     - uses: pre-commit/action@v3.0.1
       env:

.pre-commit-config.yaml

@@ -1,6 +1,15 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 repos:
+  - repo: local
+    hooks:
+      - id: generate-cli-docs
+        name: generate-cli-docs
+        entry: make generate-cli-docs
+        language: python
+        types: [python]
+        pass_filenames: false
+        args: []
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0  # Use the latest stable version
     hooks:

ATTRIBUTIONS-Python.md

@@ -1199,7 +1199,7 @@ SOFTWARE.
   - `Issue tracker`: https://github.com/jawah/charset_normalizer/issues
 
 
-## cyclopts (3.24.0)
+## cyclopts (4.2.3)
 
 ### Licenses
 License: `Apache-2.0`

ATTRIBUTIONS-container.md

@@ -17,7 +17,7 @@ This document provides attribution information for third-party software componen
 - **Website**: https://ffmpeg.org/
 - **License**: LGPL v2.1+
 - **Usage**: Video and audio processing library (included in runtime container)
-- **Build Configuration**: Built without GPL components (`--disable-gpl --disable-nonfree`)
+- **Build Configuration**: Built without GPL components (`--disable-gpl --disable-nonfree --enable-libvpx`)
 
 **License Text:**
 
@@ -48,6 +48,65 @@ The FFmpeg source code used to build this container is available at:
 - Build configuration excludes GPL-licensed components
 - Apache 2.0 licensed code in this project remains separate from LGPL components
 
+### libvpx
+
+**Component Information:**
+- **Software**: libvpx (VP8/VP9 Codec SDK)
+- **Version**: 1.12.0 (from Debian Bookworm)
+- **Source**: Debian Bookworm
+- **Website**: https://www.webmproject.org/
+- **License**: BSD 3-Clause
+- **Usage**: VP9 video codec library (included in runtime container, used by FFmpeg)
+
+**License Text:**
+
+> Copyright (c) 2010, The WebM Project authors. All rights reserved.
+>
+> Redistribution and use in source and binary forms, with or without
+> modification, are permitted provided that the following conditions are
+> met:
+>
+>   * Redistributions of source code must retain the above copyright
+>     notice, this list of conditions and the following disclaimer.
+>
+>   * Redistributions in binary form must reproduce the above copyright
+>     notice, this list of conditions and the following disclaimer in
+>     the documentation and/or other materials provided with the
+>     distribution.
+>
+>   * Neither the name of Google, nor the WebM Project, nor the names
+>     of its contributors may be used to endorse or promote products
+>     derived from this software without specific prior written
+>     permission.
+>
+> THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+> "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+> LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+> A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+> HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+> SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+> LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+> DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+> THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+> (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+> OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+>
+> Full license text: https://chromium.googlesource.com/webm/libvpx/+/refs/heads/main/LICENSE
+
+**Source Code Availability:**
+
+The libvpx source code is available at:
+- Debian package: https://packages.debian.org/bookworm/libvpx-dev
+- Debian source package: `apt-get source libvpx` from Debian Bookworm repositories
+- Upstream WebM Project source: https://chromium.googlesource.com/webm/libvpx/
+
+**Compliance Notes:**
+
+- libvpx binary is copied from Debian Bookworm base image
+- No modifications were made to libvpx source code
+- libvpx is dynamically linked with FFmpeg
+- BSD license is compatible with Apache 2.0
+
 ### Bash
 
 **Component Information:**
@@ -97,6 +156,12 @@ LGPL is compatible with Apache 2.0 when:
 - No modifications were made to FFmpeg source code
 - Proper attribution is provided (as above)
 
+### libvpx (BSD 3-Clause)
+BSD 3-Clause is compatible with Apache 2.0:
+- BSD is a permissive license that allows redistribution with minimal restrictions
+- Attribution requirements are satisfied through this document
+- No conflict with Apache 2.0 terms
+
 ### Bash (GPL v3+)
 GPL is compatible with Apache 2.0 when:
 - Bash runs as a separate executable and is not linked with Apache 2.0 code

Dockerfile

@@ -82,17 +82,18 @@ FROM base AS env-builder
 
 WORKDIR /workspace
 
-# Build ffmpeg from source
+# Build ffmpeg from source with libvpx
 RUN apt-get update -y && \
     DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
         build-essential \
         nasm \
         pkg-config \
         wget \
         yasm \
+        libvpx-dev \
     && rm -rf /var/lib/apt/lists/*
 
-# Download and build ffmpeg
+# Download and build ffmpeg with libvpx (VP9 codec)
 RUN wget https://ffmpeg.org/releases/ffmpeg-7.1.tar.xz \
     && tar -xf ffmpeg-7.1.tar.xz \
     && cd ffmpeg-7.1 \
@@ -102,6 +103,7 @@ RUN wget https://ffmpeg.org/releases/ffmpeg-7.1.tar.xz \
         --disable-nonfree \
         --enable-shared \
         --disable-static \
+        --enable-libvpx \
         --disable-doc \
         --disable-htmlpages \
         --disable-manpages \
@@ -110,7 +112,9 @@ RUN wget https://ffmpeg.org/releases/ffmpeg-7.1.tar.xz \
     && make -j$(nproc) \
     && make install \
     && cd .. \
-    && rm -rf ffmpeg-7.1 ffmpeg-7.1.tar.xz
+    && rm -rf ffmpeg-7.1 ffmpeg-7.1.tar.xz \
+    && cp -P /usr/lib/*/libvpx.so* /opt/ffmpeg/lib/ 2>/dev/null || \
+       cp -P /usr/lib/libvpx.so* /opt/ffmpeg/lib/ 2>/dev/null || { echo "Error: libvpx.so not found"; exit 1; }
 
 # Create directories for the nvs user (UID 1000 in NVIDIA distroless)
 RUN mkdir -p /app /app/artifacts /app/.cache \
@@ -137,7 +141,7 @@ COPY LICENSE ATTRIBUTIONS*.md /legal/
 # Copy bash with executable permissions preserved using --chmod
 COPY --from=env-builder --chown=1000:1000 --chmod=755 /bin/bash /bin/bash
 
-# Copy ffmpeg binaries and libraries
+# Copy ffmpeg binaries and libraries (includes libvpx)
 COPY --from=env-builder --chown=1000:1000 /opt/ffmpeg /opt/ffmpeg
 ENV PATH="/opt/ffmpeg/bin:${PATH}" \
     LD_LIBRARY_PATH="/opt/ffmpeg/lib:${LD_LIBRARY_PATH}"
@@ -154,4 +158,4 @@ ENV VIRTUAL_ENV=/opt/aiperf/venv \
     PATH="/opt/aiperf/venv/bin:${PATH}"
 
 # Set bash as entrypoint
-ENTRYPOINT ["/bin/bash", "-c"]
+ENTRYPOINT ["/bin/bash", "-c"]

Makefile

@@ -17,10 +17,10 @@
 
 .PHONY: ruff lint ruff-fix lint-fix format fmt check-format check-fmt \
 		test coverage clean install install-app docker docker-run first-time-setup \
-		test-verbose init-files setup-venv setup-mkinit install-mock-server \
+		test-verbose init-files setup-venv install-mock-server \
 		integration-tests integration-tests-ci integration-tests-verbose integration-tests-ci-macos \
 		test-integration test-integration-ci test-integration-verbose test-integration-ci-macos \
-		test-stress stress-tests internal-help help
+		generate-cli-docs test-stress stress-tests internal-help help
 
 
 # Include user-defined environment variables
@@ -37,9 +37,9 @@ PYTHON_VERSION ?= 3.12
 # The command to activate the virtual environment
 activate_venv = . $(VENV_PATH)/bin/activate
 
-# Try and get the app name and version from uv
-APP_NAME := $(shell $(activate_venv) 2>/dev/null && uv version 2>/dev/null | cut -d ' ' -f 1)
-APP_VERSION := $(shell $(activate_venv) 2>/dev/null && uv version 2>/dev/null | cut -d ' ' -f 2)
+# Try and get the app name and version from pyproject.toml
+APP_NAME := $(shell grep '^name = ' pyproject.toml 2>/dev/null | sed 's/name = "\(.*\)"/\1/')
+APP_VERSION := $(shell grep '^version = ' pyproject.toml 2>/dev/null | sed 's/version = "\(.*\)"/\1/')
 
 # The folder where uv is installed
 UV_PATH ?= $(HOME)/.local/bin
@@ -108,13 +108,13 @@ check-format check-fmt: #? check the formatting of the project using ruff.
 	$(activate_venv) && ruff format . --check $(args)
 
 test: #? run the tests using pytest-xdist.
-	$(activate_venv) && pytest -n auto -m 'not integration and not performance' $(args)
+	$(activate_venv) && pytest tests/unit -n auto -m 'not integration and not performance' $(args)
 
 test-verbose: #? run the tests using pytest-xdist with DEBUG logging.
-	$(activate_venv) && pytest -n auto -v -s --log-cli-level=DEBUG -m 'not integration and not performance'
+	$(activate_venv) && pytest tests/unit -n auto -v -s --log-cli-level=DEBUG -m 'not integration and not performance'
 
 coverage: #? run the tests and generate an html coverage report.
-	$(activate_venv) && pytest -n auto --cov=src/aiperf --cov-branch --cov-report=html --cov-report=xml --cov-report=term -m 'not integration and not performance' $(args)
+	$(activate_venv) && pytest tests/unit -n auto --cov=src/aiperf --cov-branch --cov-report=html --cov-report=xml --cov-report=term -m 'not integration and not performance' $(args)
 
 install: install-app install-mock-server #? install the project and mock server in editable mode.
 
@@ -160,9 +160,6 @@ setup-venv: #? create the virtual environment.
 		printf "$(bold)$(green)Virtual environment already exists$(reset)\n"; \
 	fi
 
-setup-mkinit: #? install the mkinit and ruff packages for pre-commit.
-	$(activate_venv) && uv pip install mkinit ruff
-
 first-time-setup: #? convenience command to setup the environment for the first time
 	$(MAKE) setup-venv --no-print-directory
 
@@ -206,3 +203,6 @@ integration-tests-verbose test-integration-verbose: #? run integration tests wit
 	@printf "$(yellow)Note: Sequential mode shows real-time AIPerf output$(reset)\n"
 	$(activate_venv) && pytest tests/integration/ -m 'integration and not stress and not performance' -vv -s --tb=short --log-cli-level=INFO --capture=no $(args)
 	@printf "$(bold)$(green)AIPerf Mock Server integration tests passed!$(reset)\n"
+
+generate-cli-docs: #? generate the CLI documentation.
+	$(activate_venv) && tools/generate_cli_docs.py

README.md

@@ -61,6 +61,7 @@ Features
 | **[Request Rate with Max Concurrency](docs/tutorials/request-rate-concurrency.md)** | Dual control of request timing and concurrent connection ceiling (Poisson or constant modes) | Testing API rate/concurrency limits, avoiding thundering herd, realistic client simulation |
 | **[GPU Telemetry](docs/tutorials/gpu-telemetry.md)** | Real-time GPU metrics collection via DCGM (power, utilization, memory, temperature, etc) | Performance optimization, resource monitoring, multi-node telemetry |
 | **[Template Endpoint](docs/tutorials/template-endpoint.md)** | Benchmark custom APIs with flexible Jinja2 request templates | Custom API formats, rapid prototyping, non-standard endpoints |
+| **[SGLang Image Generation](docs/tutorials/sglang-image-generation.md)** | Benchmark image generation APIs using SGLang with FLUX.1-dev model | Image generation testing, text-to-image benchmarking, extracting generated images |
 
 ### Working with Benchmark Data
 - **[Profile Exports](docs/tutorials/working-with-profile-exports.md)** - Parse and analyze `profile_export.jsonl` with Pydantic models, custom metrics, and async processing