Core API Reference

This section documents the core modules that provide the fundamental functionality of Pipeworks.

Image Generation

Configuration

Configuration management for Pipe-Works Image Generator.

This module provides centralised configuration management using Pydantic Settings. All configuration is loaded from environment variables with the PIPEWORKS_ prefix, allowing easy customisation without code changes.

Environment Variable Loading

Configuration values are loaded in the following priority order:

1. Environment variables (PIPEWORKS_* prefix)

2. .env file in the project root

3. Default values defined in PipeworksConfig

Example .env file:

PIPEWORKS_DEVICE=cuda
PIPEWORKS_NUM_INFERENCE_STEPS=9
PIPEWORKS_OUTPUTS_DIR=outputs
PIPEWORKS_GALLERY_DIR=static/gallery

Global Configuration Instance

A global config instance is created automatically at module import time. This ensures a single source of truth for all configuration values across the application.

Usage Example

from pipeworks.core.config import config

# Access configuration values
print(config.device)           # "cuda"
print(config.outputs_dir)      # Path("outputs")
print(config.server_port)      # 7860

Directory Management

The configuration automatically creates required directories on initialisation:

• models_dir — Cached HuggingFace model files

• outputs_dir — Runtime output artifacts such as LoRA dataset runs

• gallery_dir — Web-accessible gallery images

• gallery_db — JSON metadata for the gallery

Z-Image-Turbo Constraints

Important constraints for Z-Image-Turbo model:

• guidance_scale MUST be 0.0 (enforced in pipeworks.core.model_manager)

• Recommended num_inference_steps: 9 (results in 8 DiT forwards)

• Optimal torch_dtype: bfloat16 (best quality/performance balance)

• Device: cuda preferred, falls back to cpu

Performance Optimisation Settings

The config provides several optimisation flags:

• enable_attention_slicing — Reduces VRAM usage at slight speed cost

• enable_model_cpu_offload — Enables CPU offloading for memory-constrained setups

• compile_model — Uses torch.compile for faster inference (slower first run)

• attention_backend — Can use Flash-Attention-2 for speedup

See also

-

-

class:PipeworksConfig : Full configuration class documentation

class pipeworks.core.config.GpuWorkerConfig(**data)

Bases: BaseModel

One configured GPU worker target for generation requests.

id: str

label: str

mode: Literal['local', 'remote']

base_url: str | None

bearer_token: str | None

timeout_seconds: float

enabled: bool

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pipeworks.core.config.PipeworksConfig(*, torch_dtype: Literal['bfloat16', 'float16', 'float32']='bfloat16', device: str = 'cuda', num_inference_steps: Annotated[int, ~annotated_types.Ge(ge=1), ~annotated_types.Le(le=50)] = 9, guidance_scale: float = 0.0, default_width: Annotated[int, ~annotated_types.Ge(ge=512), ~annotated_types.Le(le=2048)] = 1024, default_height: Annotated[int, ~annotated_types.Ge(ge=512), ~annotated_types.Le(le=2048)] = 1024, enable_attention_slicing: bool = False, enable_model_cpu_offload: bool = False, compile_model: bool = False, attention_backend: Literal['default', 'flash', '_flash_3']='default', models_dir: Path = PosixPath('models'), outputs_dir: Path = PosixPath('outputs'), static_dir: Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/pipeworks-image-generator/checkouts/latest/src/pipeworks/static'), data_dir: Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/pipeworks-image-generator/checkouts/latest/src/pipeworks/static/data'), gallery_dir: Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/pipeworks-image-generator/checkouts/latest/src/pipeworks/static/gallery'), gallery_db: Path | None = None, templates_dir: Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/pipeworks-image-generator/checkouts/latest/src/pipeworks/templates'), server_host: str = '0.0.0.0', server_port: Annotated[int, ~annotated_types.Ge(ge=1024), ~annotated_types.Le(le=65535)] = 7860, disable_http_cache: bool = False, gpu_workers: list[GpuWorkerConfig] = <factory>, default_gpu_worker_id: str | None = None, worker_api_bearer_tokens: list[str] = <factory>, remote_worker_max_batch_size: Annotated[int, ~annotated_types.Ge(ge=1), ~annotated_types.Le(le=1000)] = 64, remote_worker_max_decoded_bytes: Annotated[int, ~annotated_types.Ge(ge=1024), ~annotated_types.Le(le=1073741824)] = 83886080)

Bases: BaseSettings

Main configuration for the Pipe-Works Image Generator.

Uses Pydantic Settings to load values from environment variables prefixed with PIPEWORKS_, with fallback to the defaults defined here. All Path fields are resolved on initialisation and their directories are created automatically.

General Model Settings

torch_dtypeLiteral[“bfloat16”, “float16”, “float32”]

Torch dtype for model inference (bfloat16 recommended for quality/performance balance).

devicestr

Device for inference — cuda, mps, or cpu.

Generation Defaults

num_inference_stepsint

Default number of diffusion steps (9 recommended for Turbo).

guidance_scalefloat

Classifier-free guidance scale. MUST be 0.0 for Turbo models.

default_widthint

Default image width in pixels (512–2048, must be multiple of 64).

default_heightint

Default image height in pixels (512–2048, must be multiple of 64).

Performance Optimisation

enable_attention_slicingbool

Enable attention slicing for lower VRAM usage.

enable_model_cpu_offloadbool

Enable sequential CPU offloading for memory-constrained setups.

compile_modelbool

Compile model with torch.compile (slower first run, faster subsequent inference).

attention_backendLiteral[“default”, “flash”, “_flash_3”]

Attention backend selection. "flash" enables Flash-Attention-2.

Paths

models_dirPath

Directory to cache downloaded HuggingFace models.

outputs_dirPath

Directory for runtime output artifacts such as LoRA dataset runs.

static_dirPath

Root of the web-accessible static files directory.

data_dirPath

Directory containing models.json, prepend.json, main.json, and append.json.

gallery_dirPath

Directory for gallery image files.

gallery_dbPath

JSON metadata file for gallery entries.

templates_dirPath

Directory containing the HTML template(s).

Server Settings

server_hoststr

Bind address for the uvicorn ASGI server.

server_portint

Port for the uvicorn ASGI server (1024–65535).

disable_http_cachebool

Disable browser caching for HTML, API, and static responses.

Notes

• All directories are created automatically if they do not exist.

• Configuration is immutable after initialisation.

• To modify values, set environment variables and restart the application.

Examples

Using the global instance (recommended):

>>> from pipeworks.core.config import config
>>> config.device
'cuda'

Creating a custom instance for testing:

>>> cfg = PipeworksConfig(device="cpu", server_port=9000)
>>> cfg.server_port
9000

model_config: ClassVar[SettingsConfigDict] = {'arbitrary_types_allowed': True, 'case_sensitive': False, 'cli_avoid_json': False, 'cli_enforce_required': False, 'cli_exit_on_error': True, 'cli_flag_prefix_char': '-', 'cli_hide_none_type': False, 'cli_ignore_unknown_args': False, 'cli_implicit_flags': False, 'cli_kebab_case': False, 'cli_parse_args': None, 'cli_parse_none_str': None, 'cli_prefix': '', 'cli_prog_name': None, 'cli_shortcuts': None, 'cli_use_class_docs_for_groups': False, 'enable_decoding': True, 'env_file': '.env', 'env_file_encoding': 'utf-8', 'env_ignore_empty': False, 'env_nested_delimiter': None, 'env_nested_max_split': None, 'env_parse_enums': None, 'env_parse_none_str': None, 'env_prefix': 'PIPEWORKS_', 'env_prefix_target': 'variable', 'extra': 'ignore', 'json_file': None, 'json_file_encoding': None, 'nested_model_default_partial_update': False, 'protected_namespaces': ('model_validate', 'model_dump', 'settings_customise_sources'), 'secrets_dir': None, 'toml_file': None, 'validate_default': True, 'yaml_config_section': None, 'yaml_file': None, 'yaml_file_encoding': None}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

torch_dtype: Literal['bfloat16', 'float16', 'float32']

device: str

num_inference_steps: int

guidance_scale: float

default_width: int

default_height: int

enable_attention_slicing: bool

enable_model_cpu_offload: bool

compile_model: bool

attention_backend: Literal['default', 'flash', '_flash_3']

models_dir: Path

outputs_dir: Path

static_dir: Path

data_dir: Path

gallery_dir: Path

templates_dir: Path

server_host: str

server_port: int

disable_http_cache: bool

gpu_workers: list[GpuWorkerConfig]

default_gpu_worker_id: str | None

worker_api_bearer_tokens: list[str]

remote_worker_max_batch_size: int

remote_worker_max_decoded_bytes: int

get_enabled_gpu_workers()

Return all currently enabled GPU workers in configured order.

Return type:

list[GpuWorkerConfig]

resolve_default_gpu_worker_id()

Return selected default worker id with first-enabled fallback.

Return type:

str

worker_api_tokens()

Return bearer tokens accepted by internal worker API routes.

Return type:

set[str]

__init__(**kwargs)

Initialise configuration and create required directories.

After loading values from environment variables and defaults, this method ensures that all required directories exist on disk. Directory creation uses parents=True (creates parent directories) and exist_ok=True (no error if directory already exists), making it safe to call multiple times.

Parameters:

**kwargs – Configuration overrides. Typically supplied via environment variables or explicitly in test code.

gallery_db: Path | None

Prompt Builder

Character Conditions

Model Adapters

Tokenizer