sd-backend-client 0.2.1__py3-none-any.whl

sd_backend_client/__init__.py

@@ -0,0 +1 @@
+"""IntraPaint standalone API package."""

sd_backend_client/api/__init__.py

@@ -0,0 +1 @@
+"""api provides modules handling remote REST APIs."""

sd_backend_client/api/a1111_webservice.py

@@ -0,0 +1,646 @@
+"""
+Accesses the A1111/stable-diffusion-webui through its REST API, providing access to image generation and editing
+through Stable Diffusion.
+"""
+import json
+import logging
+from copy import deepcopy
+from typing import Optional, Any, Callable, cast, TYPE_CHECKING
+from typing_extensions import TypedDict
+
+import requests  # type: ignore
+from PIL import Image  # type: ignore
+from requests import Response
+
+from sd_backend_client.api.shared_data.controlnet.controlnet_category_builder import ControlNetCategoryBuilder
+from sd_backend_client.api.shared_data.controlnet.controlnet_preprocessor import ControlNetPreprocessor, \
+    PreprocessorParams
+from sd_backend_client.api.shared_data.api_datatypes import DiffusionUpscalingParams, REDRAW_MODES, SEAM_FIX_MODES
+from sd_backend_client.api.shared_data.controlnet.controlnet_unit import ControlNetUnit
+from sd_backend_client.api.webservice import WebService, AuthError, DEFAULT_REQUEST_TIMEOUT
+from sd_backend_client.api.webui.controlnet_webui_constants import (ControlNetModelResponse, ControlNetModuleResponse,
+                                                      ControlTypeDef, ControlTypeResponse,
+                                                      FIRST_GENERIC_PARAMETER_KEY, SECOND_GENERIC_PARAMETER_KEY,
+                                                      PREPROCESSOR_RES_PARAM_KEY)
+from sd_backend_client.api.webui.controlnet_webui_utils import get_all_preprocessors
+from sd_backend_client.api.webui.diffusion_request_body import DiffusionRequestBody
+from sd_backend_client.api.webui.request_formats import UpscalingRequestBody
+from sd_backend_client.api.webui.response_formats import GenerationInfoData, ProgressResponseBody, \
+    InterrogateResponse, PromptStyleData, SamplerInfo, UpscalerInfo, ModelInfo, VaeInfo, LoraInfo
+from sd_backend_client.api.webui.script_info_types import ScriptResponseData, ScriptInfo
+from sd_backend_client.util.visual.image_utils import (image_to_base64, image_from_base64, image_from_bytes,
+                                                    mask_to_grayscale)
+
+if TYPE_CHECKING:
+    from sd_backend_client.api.webui.webui_generation_handle import WebUIDispatcher, WebUIGenerationHandle
+
+logger = logging.getLogger(__name__)
+
+
+class ImageResponse(TypedDict):
+    """Defines image generation response format."""
+    images: list[Image.Image]
+    info: Optional[GenerationInfoData]
+
+
+ULTIMATE_UPSCALE_SCRIPT = 'ultimate sd upscale'
+INTERROGATE_DEFAULT_MODEL = 'clip'
+DEFAULT_GENERATION_TIMEOUT = 600.0
+MAX_LOGIN_ATTEMPTS = 3
+SETTINGS_UPDATE_TIMEOUT = 90
+
+
+class A1111Webservice(WebService):
+    """
+    A1111Webservice provides access to the a1111/stable-diffusion-webui through the REST API.
+    """
+
+    # noinspection SpellCheckingInspection
+    class Endpoints:
+        """REST API endpoint constants."""
+        OPTIONS = '/sdapi/v1/options'
+        REFRESH_CKPT = '/sdapi/v1/refresh-checkpoints'
+        REFRESH_VAE = '/sdapi/v1/refresh-vae'
+        REFRESH_LORA = '/sdapi/v1/refresh-loras'
+        PROGRESS = '/sdapi/v1/progress'
+        IMG2IMG = '/sdapi/v1/img2img'
+        TXT2IMG = '/sdapi/v1/txt2img'
+        UPSCALE = '/sdapi/v1/extra-single-image'
+        INTERROGATE = '/sdapi/v1/interrogate'
+        INTERRUPT = '/sdapi/v1/interrupt'
+        STYLES = '/sdapi/v1/prompt-styles'
+        SCRIPTS = '/sdapi/v1/scripts'
+        SCRIPT_INFO = '/sdapi/v1/script-info'
+        SAMPLERS = '/sdapi/v1/samplers'
+        UPSCALERS = '/sdapi/v1/upscalers'
+        LATENT_UPSCALE_MODES = '/sdapi/v1/latent-upscale-modes'
+        HYPERNETWORKS = '/sdapi/v1/hypernetworks'
+        SD_MODELS = '/sdapi/v1/sd-models'
+        VAE_MODELS = '/sdapi/v1/sd-vae'
+        LORA_MODELS = '/sdapi/v1/loras'
+        CONTROLNET_VERSION = '/controlnet/version'
+        CONTROLNET_MODELS = '/controlnet/model_list'
+        CONTROLNET_MODULES = '/controlnet/module_list'
+        CONTROLNET_CONTROL_TYPES = '/controlnet/control_types'
+        CONTROLNET_SETTINGS = '/controlnet/settings'
+        CONTROLNET_PREVIEW = '/controlnet/detect'
+        LOGIN = '/login'
+        EXTRA_NW_DATA = '/sd_extra_networks/metadata'
+        EXTRA_NW_THUMB = '/sd_extra_networks/thumb'
+        EXTRA_NW_CARD = '/sd_extra_networks/card'
+
+    class ForgeEndpoints:
+        """REST API endpoint constants (Forge WebUI alternates)"""
+        SD_MODULES = '/sdapi/v1/sd-modules'
+
+    def __init__(self, url: str,
+                 credentials_provider: Optional[Callable[[], Optional[tuple[str, str]]]] = None,
+                 request_timeout: Optional[float] = DEFAULT_REQUEST_TIMEOUT,
+                 generation_timeout: Optional[float] = DEFAULT_GENERATION_TIMEOUT) -> None:
+        """Create the webservice client.
+
+        Parameters
+        ----------
+        url: str
+            Base URL of the A1111 / Forge WebUI server.
+        credentials_provider: optional callable
+            Invoked with no arguments when the server requires authentication. It should return a
+            (username, password) pair to attempt, or None to abort (raising AuthError). IntraPaint prompted for
+            these through a Qt login dialog; a standalone caller injects its own prompt or fixed credentials here.
+        request_timeout: float, optional, default=DEFAULT_REQUEST_TIMEOUT
+            Timeout in seconds for metadata, settings and other non-generation requests. None waits indefinitely.
+        generation_timeout: float, optional, default=DEFAULT_GENERATION_TIMEOUT
+            Timeout in seconds for requests that block until images are ready: txt2img, img2img, upscale and
+            ControlNet preprocessor previews. None waits indefinitely.
+        """
+        super().__init__(url, request_timeout)
+        self._generation_timeout = generation_timeout
+        self._preprocessor_cache: Optional[list[ControlNetPreprocessor]] = None
+        self._credentials_provider = credentials_provider
+        self._dispatcher: Optional['WebUIDispatcher'] = None
+
+    @property
+    def generation_timeout(self) -> Optional[float]:
+        """Timeout in seconds for requests that block until images are ready, or None to wait indefinitely."""
+        return self._generation_timeout
+
+    @property
+    def _generation_dispatcher(self) -> 'WebUIDispatcher':
+        """Lazily-created client-side dispatch queue backing the async ``submit_*`` methods."""
+        if self._dispatcher is None:
+            from sd_backend_client.api.webui.webui_generation_handle import WebUIDispatcher
+            self._dispatcher = WebUIDispatcher(self)
+        return self._dispatcher
+
+    def submit_txt2img(self, request_body: Optional[DiffusionRequestBody] = None
+                       ) -> 'WebUIGenerationHandle':
+        """Async counterpart to :meth:`txt2img`: enqueue the job and return a handle immediately.
+
+        The blocking POST is deferred to the client-side dispatcher (see ``webui_generation_handle``), so
+        the returned handle starts ``PENDING`` and is cleanly cancellable until it is actually dispatched.
+        Call ``handle.wait()`` for the blocking result, or poll ``handle.poll()`` for progress.
+        The request body is copied at submit time, so later changes to the caller's body do not affect the job and
+        the body can be reused for further submissions.
+        """
+        from sd_backend_client.api.webui.webui_generation_handle import create_task_id
+        snapshot = DiffusionRequestBody() if request_body is None else request_body.model_copy(deep=True)
+        task_id = snapshot.force_task_id or create_task_id('txt2img')
+        snapshot.force_task_id = task_id
+        return self._generation_dispatcher.submit(lambda: self.txt2img(snapshot), task_id)
+
+    def submit_img2img(self, image: Image.Image, mask: Optional[Image.Image] = None,
+                       request_body: Optional[DiffusionRequestBody] = None) -> 'WebUIGenerationHandle':
+        """Async counterpart to :meth:`img2img`: enqueue the job and return a handle immediately.
+
+        See :meth:`submit_txt2img` for the dispatch/cancel semantics. The image, mask and request body are copied at
+        submit time.
+        """
+        from sd_backend_client.api.webui.webui_generation_handle import create_task_id
+        snapshot = DiffusionRequestBody() if request_body is None else request_body.model_copy(deep=True)
+        image_copy = image.copy()
+        mask_copy = None if mask is None else mask.copy()
+        task_id = snapshot.force_task_id or create_task_id('img2img')
+        snapshot.force_task_id = task_id
+        return self._generation_dispatcher.submit(lambda: self.img2img(image_copy, mask_copy, snapshot), task_id)
+
+    # General utility:
+    def login_check(self):
+        """Calls the login check endpoint, returning a status 401 response if a login is required."""
+        return self.get('/login_check')
+
+    def set_config(self, config_updates: dict) -> None:
+        """
+        Updates the Stable Diffusion WebUI configuration.
+
+        Parameters
+        ----------
+        config_updates: dict
+            Maps settings that should change to their updated values. Use the get_settings method's response body
+            to check available options.
+        """
+        self.post(A1111Webservice.Endpoints.OPTIONS, config_updates, timeout=SETTINGS_UPDATE_TIMEOUT).json()
+
+    def refresh_checkpoints(self) -> requests.Response:
+        """Requests an updated list of available Stable Diffusion models.
+
+        Returns
+        -------
+        response
+            HTTP response with the list of updated Stable Diffusion models.
+        """
+        return self.post(A1111Webservice.Endpoints.REFRESH_CKPT, body={})
+
+    def refresh_vae(self) -> requests.Response:
+        """Requests an updated list of available Stable Diffusion VAE models.
+
+        VAE models handle the conversion between images and the latent image space. Different VAE models can be used
+        to adjust performance and final image quality.
+
+
+        Returns
+        -------
+        response
+            HTTP response with the list of updated Stable Diffusion VAE models.
+        """
+        return self.post(A1111Webservice.Endpoints.REFRESH_VAE, body={})
+
+    def refresh_loras(self) -> requests.Response:
+        """Requests an updated list of available Stable Diffusion LoRA models.
+
+        LoRA models augment existing Stable Diffusion models, usually to provide support for new concepts, characters,
+        or art styles.
+
+        Returns
+        -------
+        response
+            HTTP response with the list of updated Stable Diffusion LoRA models.
+        """
+        return self.post(A1111Webservice.Endpoints.REFRESH_LORA, body={})
+
+    def progress_check(self) -> ProgressResponseBody:
+        """Checks the progress of an ongoing image operation."""
+        return ProgressResponseBody.model_validate(
+            self.get(A1111Webservice.Endpoints.PROGRESS).json())
+
+    # Image manipulation:
+    def img2img(self, image: Image.Image, mask: Optional[Image.Image] = None,
+                request_body: Optional[DiffusionRequestBody] = None) -> ImageResponse:
+        """Sends a request to alter an image section using selected parameters.
+
+        Parameters
+        ----------
+        image: Image.Image
+            Source image to transform. If request_body is not None, and it already has an image, this parameter is
+            ignored.
+        mask: Optional[Image.Image] = None
+            Optional inpainting mask.  This will also be ignored if request_body is not None, and it already has a mask.
+        request_body : Optional[DiffusionRequestBody] = None
+            Optional initial request body to use. If None, a default DiffusionRequestBody is used.
+            The caller's body is not modified.
+        Returns
+        -------
+        ImageResponse
+            All generated images, plus accompanying image generation data if available.
+        """
+        if request_body is None:
+            request_body = DiffusionRequestBody()
+            request_body.init_images = [image]
+            request_body.mask=mask
+        else:
+            request_body = request_body.model_copy()
+            if not request_body.init_images:
+                request_body.init_images = [image]
+            else:
+                request_body.init_images = list(request_body.init_images)
+            if request_body.mask is None and mask is not None:
+                request_body.mask = mask
+        res = self.post(A1111Webservice.Endpoints.IMG2IMG, request_body.to_dict(), timeout=self._generation_timeout)
+        return self._handle_image_response(res)
+
+    def txt2img(self, request_body: Optional[DiffusionRequestBody] = None) -> ImageResponse:
+        """Sends a request to generate new images using selected parameter.
+
+        Parameters
+        ----------
+        request_body : Optional[DiffusionRequestBody] = None
+            Optional initial request body to use. If None, a new one will be constructed from default parameters.
+        Returns
+        -------
+        ImageResponse
+            All generated images, plus accompanying image generation data if available.
+        """
+        if request_body is None:
+            request_body = DiffusionRequestBody()
+        res = self.post(A1111Webservice.Endpoints.TXT2IMG, request_body.to_dict(), timeout=self._generation_timeout)
+        return self._handle_image_response(res)
+
+    def controlnet_preprocessor_preview(self, image: Image.Image, mask: Optional[Image.Image],
+                                        preprocessor: ControlNetPreprocessor | PreprocessorParams) -> Image.Image:
+        """Gets a preview image for a ControlNet preprocessor.
+
+        `preprocessor` may be a bare `ControlNetPreprocessor`, in which case the server applies its own
+        parameter defaults, or a `PreprocessorParams` to override threshold_a/threshold_b/processor_res.
+        """
+        input_images: list[str] = [image_to_base64(image, True)]
+        if mask is not None:
+            input_images.append(image_to_base64(mask_to_grayscale(mask), True))
+        typedef = preprocessor.typedef if isinstance(preprocessor, PreprocessorParams) else preprocessor
+        body: dict[str, int | float | str | list[str]] = {
+            'controlnet_module': typedef.name,
+            'controlnet_input_images': input_images
+        }
+        if isinstance(preprocessor, PreprocessorParams):
+            detect_param_keys = {
+                FIRST_GENERIC_PARAMETER_KEY: 'controlnet_threshold_a',
+                SECOND_GENERIC_PARAMETER_KEY: 'controlnet_threshold_b',
+                PREPROCESSOR_RES_PARAM_KEY: 'controlnet_processor_res',
+            }
+            for param_key, detect_key in detect_param_keys.items():
+                if param_key in preprocessor.parameter_values:
+                    body[detect_key] = preprocessor.parameter_values[param_key]
+        res = self.post(A1111Webservice.Endpoints.CONTROLNET_PREVIEW, body, timeout=self._generation_timeout)
+        return self._handle_image_response(res)['images'][0]
+
+    def _validate_tile_controlnet(self, tile_control_unit: Optional[ControlNetUnit]) -> Optional[ControlNetUnit]:
+        """Return the tile ControlNet unit only if it's fully specified and installed on the server, else None."""
+        if tile_control_unit is None:
+            return None
+        if (tile_control_unit.model is None
+                or tile_control_unit.preprocessor is None
+                or float(tile_control_unit.control_strength) == 0.0
+                or float(tile_control_unit.control_start) >= float(tile_control_unit.control_end)):
+            return None
+        models = self.get_controlnet_models().model_list
+        preprocessors = [preprocessor.name for preprocessor in self.get_controlnet_preprocessors()]
+        if (tile_control_unit.model.full_model_name not in models
+                or tile_control_unit.preprocessor.typedef.name not in preprocessors):
+            return None
+        return tile_control_unit
+
+    def upscale(self,
+                image: Image.Image,
+                width: int,
+                height: int,
+                sd_upscale_params: Optional[DiffusionUpscalingParams] = None) -> ImageResponse:
+        """Sends a request to upscale an image.
+
+        Parameters
+        ----------
+        image : Image.Image
+            Source image to upscale.
+        width : int
+            New image width in pixels requested.
+        height : int
+            New image height in pixels requested.
+        sd_upscale_params : Optional[DiffusionUpscalingParams]
+            Parameters for stable diffusion upscaling using the "Ultimate SD Upscale" workflow. If None, only basic
+            upscaling will be used.
+        Returns
+        -------
+        ImageResponse
+            The generated image, plus accompanying image generation data if available.
+        """
+        upscale_options = [upscaler.name for upscaler in self.get_upscalers()]
+        # Default to the first real upscaler rather than upscale_options[0], which is the no-op 'None' upscaler that
+        # would leave the image unchanged.
+        upscaler: str = next((name for name in upscale_options if name.lower() != 'none'), upscale_options[0])
+        if sd_upscale_params is not None and sd_upscale_params.upscaling_mode in upscale_options:
+            upscaler = sd_upscale_params.upscaling_mode
+
+        if sd_upscale_params is not None and sd_upscale_params.use_stable_diffusion_upscaling:
+            # Populate the core diffusion pass (prompt, seed, cfg, sampler, checkpoint, ...) from diffusion_params,
+            # then override the upscale-specific bits, which take precedence:
+            request_body = DiffusionRequestBody(**sd_upscale_params.diffusion_params.model_dump())
+            request_body.init_images = [image]
+            request_body.denoising_strength = sd_upscale_params.denoising_strength
+            request_body.steps = sd_upscale_params.step_count
+            request_body.width = width
+            request_body.height = height
+            request_body.batch_size = 1
+            request_body.n_iter = 1
+
+            # Attach the optional tile ControlNet via controlnet_units; DiffusionRequestBody.to_dict() serializes these
+            # into alwayson_scripts['controlnet']. (Setting alwayson_scripts directly here would be wiped by to_dict.)
+            tile_control_unit = self._validate_tile_controlnet(sd_upscale_params.tile_controlnet)
+            request_body.controlnet_units = [tile_control_unit] if tile_control_unit is not None else []
+
+            if sd_upscale_params.use_ultimate_upscale_script:
+                request_body.script_name = ULTIMATE_UPSCALE_SCRIPT
+                # Positional args for the "ultimate sd upscale" script (order confirmed via /sdapi/v1/script-info):
+                request_body.script_args = [
+                    None,  # [0] not used
+                    sd_upscale_params.tile_width,        # [1] tile width
+                    sd_upscale_params.tile_height,       # [2] tile height
+                    sd_upscale_params.mask_blur,         # [3] mask_blur
+                    sd_upscale_params.tile_padding,      # [4] tile padding
+                    sd_upscale_params.seam_fix_width,    # [5] seams_fix_width
+                    sd_upscale_params.seam_fix_denoise,  # [6] seams_fix_denoise
+                    sd_upscale_params.seam_fix_padding,  # [7] seams_fix_padding
+                    upscale_options.index(upscaler),     # [8] upscaler_index (into /sdapi/v1/upscalers)
+                    sd_upscale_params.save_upscaled_image,   # [9] save_upscaled_image
+                    REDRAW_MODES.index(sd_upscale_params.redraw_mode),  # [10] redraw mode (0=Linear,1=Chess,2=None)
+                    sd_upscale_params.save_seams_fix_image,   # [11] save_seams_fix_image
+                    sd_upscale_params.seam_fix_mask_blur,     # [12] seams_fix_mask_blur
+                    SEAM_FIX_MODES.index(sd_upscale_params.seam_fix_mode),  # [13] seams_fix_type
+                    1,       # [14] target_size_type (1 = use custom width/height below)
+                    width,   # [15] custom_width
+                    height,  # [16] custom_height
+                    None     # [17] custom_scale (ignored when target_size_type=1)
+                ]
+            return self.img2img(image, None, request_body)
+        # otherwise, normal upscaling without controlNet:
+        body: UpscalingRequestBody = {
+            'resize_mode': 1,
+            'upscaling_resize_w': width,
+            'upscaling_resize_h': height,
+            'upscaler_1': upscaler,
+            'image': image_to_base64(image, include_prefix=True)
+        }
+        res = self.post(A1111Webservice.Endpoints.UPSCALE, body, timeout=self._generation_timeout)
+        return self._handle_image_response(res)
+
+    def interrogate(self, image: Image.Image, interrogate_model: Optional[str] = None) -> str:
+        """Requests text describing an image.
+
+        Parameters
+        ----------
+        image : PIL Image
+            The image to describe.
+        interrogate_model : Optional[str]
+            Specific image interrogation model to use. Must be supported by the backend. Defaults to
+            INTERROGATE_DEFAULT_MODEL.
+        Returns
+        -------
+        str
+            A brief description of the image.
+        """
+        if interrogate_model is None:
+            interrogate_model = INTERROGATE_DEFAULT_MODEL
+        body = {
+            'model': interrogate_model,
+            'image': image_to_base64(image, include_prefix=True)
+        }
+        res = self.post(A1111Webservice.Endpoints.INTERROGATE, body, timeout=60).json()
+        if isinstance(res, dict):
+            res = InterrogateResponse.model_validate(res)
+            return res.caption
+        assert isinstance(res, str)
+        return res
+
+    def interrupt(self) -> dict:
+        """
+        Attempts to interrupt an ongoing image operation, returning a dict from the response body indicating the
+        result.
+        """
+        res = self.post(A1111Webservice.Endpoints.INTERRUPT, body={})
+        return res.json()
+
+    @staticmethod
+    def _handle_image_response(res: Response) -> ImageResponse:
+        if res.status_code != 200:
+            raise RuntimeError(res.json())
+        res_body = res.json()
+        images = []
+        info_data: Optional[GenerationInfoData] = None
+        if 'images' in res_body:
+            for image in res_body['images']:
+                images.append(image_from_base64(image))
+            info = res_body.get('info')  # absent on some endpoints (e.g. /controlnet/detect)
+            if isinstance(info, str):
+                try:
+                    info_data = GenerationInfoData.model_validate(json.loads(info))
+                except json.JSONDecodeError:
+                    logger.error(f'Image response info not valid JSON, got {info}')
+                    info_data = None
+            elif info is not None:
+                info_data = GenerationInfoData.model_validate(info)
+        elif 'image' in res_body:  # basic upscaling result
+            images = [image_from_base64(res_body['image'])]
+            info_data = None
+        image_response: ImageResponse = {
+            'images': images,
+            'info': info_data
+        }
+        return image_response
+
+    # Load misc. service info:
+    def get_config(self) -> dict[str, Any]:
+        """Returns a dict containing the current Stable Diffusion WebUI configuration."""
+        return self.get('/sdapi/v1/options').json()
+
+    def get_styles(self) -> list[PromptStyleData]:
+        """Returns a list of image generation style objects saved by the Stable Diffusion WebUI."""
+        res_body = self.get(A1111Webservice.Endpoints.STYLES).json()
+        all_styles: list[PromptStyleData] = []
+        for serialized_style in res_body:
+            all_styles.append(PromptStyleData.model_validate(serialized_style))
+        return all_styles
+
+    def get_scripts(self) -> ScriptResponseData:
+        """Returns available scripts installed to the Stable Diffusion WebUI.
+        Returns
+        -------
+        dict
+            Response will have 'txt2img' and 'img2img' keys, each holding a list of scripts available for that mode.
+        """
+        return ScriptResponseData.model_validate(self.get(A1111Webservice.Endpoints.SCRIPTS).json())
+
+    def get_script_info(self) -> list[ScriptInfo]:
+        """Returns information on expected script parameters
+        Returns
+        -------
+        list of dict
+            Objects defining all parameters required by each script.
+        """
+        return [ScriptInfo.model_validate(item) for item in self.get(A1111Webservice.Endpoints.SCRIPT_INFO).json()]
+
+    def _get_name_list(self, endpoint: str) -> list[str]:
+        res_body = self.get(endpoint).json()
+        return [obj['name'] for obj in res_body]
+
+    def get_samplers(self) -> list[SamplerInfo]:
+        """Returns the list of image sampler algorithms available for image generation."""
+        return [SamplerInfo.model_validate(item)
+                for item in self.get(A1111Webservice.Endpoints.SAMPLERS).json()]
+
+    def get_upscalers(self) -> list[UpscalerInfo]:
+        """Returns the list of image upscalers available."""
+        return [UpscalerInfo.model_validate(item)
+                for item in self.get(A1111Webservice.Endpoints.UPSCALERS).json()]
+
+    def get_latent_upscale_modes(self) -> list[str]:
+        """Returns the list of Stable Diffusion enhanced upscaling modes."""
+        return self._get_name_list(A1111Webservice.Endpoints.LATENT_UPSCALE_MODES)
+
+    def get_hypernetworks(self) -> list[str]:
+        """Returns the list of hypernetworks available.
+
+        Hypernetworks are a simpler form of model for augmenting full Stable Diffusion models. Each hypernetwork
+        introduces a single style or concept.
+        """
+        return self._get_name_list(A1111Webservice.Endpoints.HYPERNETWORKS)
+
+    def get_models(self) -> list[ModelInfo]:
+        """Returns the list of available Stable Diffusion models cached by the webui.
+
+        If available models may have changed, instead consider using the slower refresh_checkpoints method.
+        """
+        return [ModelInfo.model_validate(item)
+                for item in self.get(A1111Webservice.Endpoints.SD_MODELS).json()]
+
+    def get_vae(self) -> list[VaeInfo]:
+        """Returns the list of available Stable Diffusion VAE models cached by the webui.
+
+        If available models may have changed, instead consider using the slower refresh_vae method.
+        """
+        try:
+            vae_models = self.get(A1111Webservice.Endpoints.VAE_MODELS).json()
+        except RuntimeError:
+            vae_models = self.get(A1111Webservice.ForgeEndpoints.SD_MODULES).json()
+        return [VaeInfo.model_validate(item) for item in vae_models]
+
+    def get_controlnet_version(self) -> int:
+        """
+        Returns the installed version of the Stable Diffusion ControlNet extension, or raises if the exception is not
+        installed.
+        """
+        return self.get(A1111Webservice.Endpoints.CONTROLNET_VERSION).json()['version']
+
+    def get_controlnet_models(self) -> ControlNetModelResponse:
+        """Returns a dict defining the models available to the Stable Diffusion ControlNet extension."""
+        return ControlNetModelResponse.model_validate(
+                    self.get(A1111Webservice.Endpoints.CONTROLNET_MODELS).json())
+
+    def get_controlnet_modules(self) -> ControlNetModuleResponse:
+        """Returns a dict defining the modules available to the Stable Diffusion ControlNet extension."""
+        return ControlNetModuleResponse.model_validate(
+                    self.get(A1111Webservice.Endpoints.CONTROLNET_MODULES).json())
+
+    def get_controlnet_control_types(self) -> ControlTypeResponse:
+        """Returns a dict defining the control types available to the Stable Diffusion ControlNet extension."""
+        return cast(ControlTypeResponse, self.get(A1111Webservice.Endpoints.CONTROLNET_CONTROL_TYPES).json())
+
+    def get_controlnet_settings(self) -> dict[str, Any]:
+        """Returns the current settings applied to the Stable Diffusion ControlNet extension."""
+        return self.get(A1111Webservice.Endpoints.CONTROLNET_SETTINGS).json()
+
+    def get_controlnet_preprocessors(self, update_cache=False) -> list[ControlNetPreprocessor]:
+        """Queries the API for ControlNet preprocessor modules, and parameterizes and returns all options."""
+        if update_cache or self._preprocessor_cache is None:
+            modules = self.get_controlnet_modules()
+            module_names = modules.module_list
+            module_details = modules.module_details
+            self._preprocessor_cache = get_all_preprocessors(module_names, module_details)
+        assert self._preprocessor_cache is not None
+        return deepcopy(self._preprocessor_cache)
+
+    def get_controlnet_type_categories(self) -> dict[str, ControlTypeDef]:
+        """Gets the set of valid ControlNet preprocessor/model categories, taking into account available options and
+           API category definitions if possible."""
+        modules = self.get_controlnet_modules()
+        models = self.get_controlnet_models()
+        try:
+            control_type_defs = self.get_controlnet_control_types()
+        except (KeyError, RuntimeError):
+            control_type_defs = None
+        preprocessor_names = modules.module_list
+        model_names = models.model_list
+        control_type_builder = ControlNetCategoryBuilder(preprocessor_names, model_names, None, control_type_defs)
+        return control_type_builder.get_control_types()
+
+    def get_loras(self) -> list[LoraInfo]:
+        """Returns the list of available Stable Diffusion LoRA models cached by the webui.
+
+        If available models may have changed, instead consider using the slower refresh_loras method.
+        """
+        return [LoraInfo.model_validate(item)
+                for item in self.get(A1111Webservice.Endpoints.LORA_MODELS).json()]
+
+    def get_thumbnail(self, file_path: str) -> Optional[Image.Image]:
+        """Attempts to load one of the extra model thumbnails given a path parameter."""
+        try:
+            res = self.get(A1111Webservice.Endpoints.EXTRA_NW_THUMB,
+                           url_params={'filename': file_path})
+            if not res.ok:
+                return None
+            return image_from_bytes(res.content)
+        except (RuntimeError, IOError) as err:
+            logger.error(f'Failed to load thumbnail "{file_path}": {err}')
+            return None
+
+    def login(self, username: str, password: str) -> requests.Response:
+        """Attempt to log in with a username and password."""
+        body = {'username': username, 'password': password}
+        return self.post(A1111Webservice.Endpoints.LOGIN, body, 'x-www-form-urlencoded',
+                         throw_on_failure=False)
+
+    def _handle_auth_error(self):
+        """Asks the credentials provider for credentials, up to MAX_LOGIN_ATTEMPTS times.
+
+        Credentials are checked with an authenticated GET to an /sdapi/v1/ endpoint, which is what --api-auth
+        protects. They are installed on the session only once accepted. Raises AuthError if no provider is
+        configured, the provider returns None, or every attempt is rejected."""
+        if self._credentials_provider is None:
+            raise AuthError('Authentication required, but no credentials_provider was configured.')
+        for attempt in range(1, MAX_LOGIN_ATTEMPTS + 1):
+            credentials = self._credentials_provider()
+            if credentials is None:
+                logger.info('Login aborted')
+                raise AuthError('Login aborted: the credentials provider returned no credentials.')
+            previous_auth = self._session.auth
+            self.set_auth(credentials)
+            try:
+                response = self.get(A1111Webservice.Endpoints.PROGRESS,
+                                    url_params={'skip_current_image': 'true'},
+                                    fail_on_auth_error=True, throw_on_failure=False)
+            except BaseException:
+                self.set_auth(previous_auth)
+                raise
+            if response.status_code != 401:
+                if not response.ok:
+                    logger.warning(f'Credential check returned status {response.status_code}')
+                return
+            self.set_auth(previous_auth)
+            logger.warning(f'Login attempt {attempt} of {MAX_LOGIN_ATTEMPTS} was rejected (status 401).')
+        raise AuthError(f'Authentication failed after {MAX_LOGIN_ATTEMPTS} attempts: the server returned status 401.'
+                        ' Check the credentials and the server\'s --api-auth setting.')

sd_backend_client/api/comfyui/__init__.py

@@ -0,0 +1 @@
+"""Misc. data definitions and helper classes for ComfyUIWebservice."""