tinysd 0.0.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
tinysd/__init__.py ADDED
@@ -0,0 +1,31 @@
1
+ """TinySD: a small wrapper around diffusers for Stable Diffusion 1.x and SDXL.
2
+
3
+ Modules:
4
+ - :mod:`tinysd.prompt`: A1111 -> Compel prompt syntax conversion.
5
+ - :mod:`tinysd.schedulers`: A1111-named scheduler registry.
6
+ - :mod:`tinysd.pipeline`: Pipeline loading (VAE, LoRA, textual inversion).
7
+ - :mod:`tinysd.generation`: Low-level image generation.
8
+ - :mod:`tinysd.generator`: High-level :class:`SDImageGenerator`.
9
+ - :mod:`tinysd.schemas`: Output data containers.
10
+ """
11
+
12
+ from .generation import generate_image
13
+ from .generator import SDImageGenerator
14
+ from .pipeline import MODEL_ID_ALIASES, get_stable_diffusion_pipeline
15
+ from .prompt import convert_a1111_to_compel
16
+ from .schedulers import SCHEDULERS, set_scheduler
17
+ from .schemas import StableDiffusionOutput
18
+
19
+ __version__ = "0.1.0"
20
+
21
+ __all__ = [
22
+ "MODEL_ID_ALIASES",
23
+ "SCHEDULERS",
24
+ "SDImageGenerator",
25
+ "StableDiffusionOutput",
26
+ "convert_a1111_to_compel",
27
+ "generate_image",
28
+ "get_stable_diffusion_pipeline",
29
+ "set_scheduler",
30
+ "__version__",
31
+ ]
tinysd/generation.py ADDED
@@ -0,0 +1,126 @@
1
+ """Low-level image generation with Compel prompt weighting."""
2
+
3
+ from typing import Union, Optional
4
+
5
+ import PIL.Image
6
+ import torch
7
+ from compel import Compel, ReturnedEmbeddingsType
8
+ from diffusers import StableDiffusionPipeline, StableDiffusionXLPipeline
9
+
10
+ from .prompt import convert_a1111_to_compel
11
+ from .utils import _ensure_text_model_attr, _is_sdxl_pipeline
12
+
13
+
14
+ def generate_image(
15
+ positive_prompt: Union[str, list[str]],
16
+ negative_prompt: Union[str, list[str]],
17
+ stable_diffusion_pipeline: Union[StableDiffusionPipeline, StableDiffusionXLPipeline],
18
+ height: int = 512,
19
+ width: int = 512,
20
+ steps: int = 30,
21
+ guidance_scale: float = 7.5,
22
+ seed: Optional[int] = None,
23
+ clip_skip: int = 1,
24
+ convert_a1111_syntax: bool = True,
25
+ ) -> list[PIL.Image.Image]:
26
+ """Generate images from weighted prompts using a loaded pipeline.
27
+
28
+ Prompts are encoded with Compel (supporting long prompts and weighting), padded
29
+ to the same length, and passed to the pipeline as embeddings.
30
+
31
+ Args:
32
+ positive_prompt: Prompt or list of prompts (one image per prompt).
33
+ negative_prompt: Negative prompt or list of negative prompts.
34
+ stable_diffusion_pipeline: A pipeline from
35
+ :func:`tinysd.pipeline.get_stable_diffusion_pipeline`.
36
+ height: Image height in pixels.
37
+ width: Image width in pixels.
38
+ steps: Number of denoising steps.
39
+ guidance_scale: Classifier-free guidance scale.
40
+ seed: Random seed. For a batch, prompt ``i`` uses ``seed + i``.
41
+ ``None`` means non-deterministic.
42
+ clip_skip: For SD 1.x, values ``>= 2`` use the penultimate CLIP hidden
43
+ states. Ignored for SDXL, which always uses the penultimate layer.
44
+ convert_a1111_syntax: Convert A1111 prompt syntax to Compel syntax first.
45
+
46
+ Returns:
47
+ The list of generated PIL images.
48
+ """
49
+ if convert_a1111_syntax:
50
+ if isinstance(positive_prompt, list):
51
+ positive_prompt = [convert_a1111_to_compel(p) for p in positive_prompt]
52
+ else:
53
+ positive_prompt = convert_a1111_to_compel(positive_prompt)
54
+
55
+ if isinstance(negative_prompt, list):
56
+ negative_prompt = [convert_a1111_to_compel(p) for p in negative_prompt]
57
+ else:
58
+ negative_prompt = convert_a1111_to_compel(negative_prompt)
59
+
60
+ batch_size = len(positive_prompt) if isinstance(positive_prompt, list) else 1
61
+ if seed is None:
62
+ generator = None
63
+ elif batch_size > 1:
64
+ generator = [torch.Generator("cpu").manual_seed(int(seed) + i) for i in range(batch_size)]
65
+ else:
66
+ generator = torch.Generator("cpu").manual_seed(int(seed))
67
+
68
+ _ensure_text_model_attr(getattr(stable_diffusion_pipeline, "text_encoder", None))
69
+ _ensure_text_model_attr(getattr(stable_diffusion_pipeline, "text_encoder_2", None))
70
+ is_xl = _is_sdxl_pipeline(stable_diffusion_pipeline)
71
+
72
+ if is_xl:
73
+ compel = Compel(
74
+ tokenizer=[stable_diffusion_pipeline.tokenizer, stable_diffusion_pipeline.tokenizer_2],
75
+ text_encoder=[stable_diffusion_pipeline.text_encoder, stable_diffusion_pipeline.text_encoder_2],
76
+ returned_embeddings_type=ReturnedEmbeddingsType.PENULTIMATE_HIDDEN_STATES_NON_NORMALIZED,
77
+ requires_pooled=[False, True],
78
+ truncate_long_prompts=False,
79
+ )
80
+ positive_prompt_embeds, positive_pooled = compel(positive_prompt)
81
+ negative_prompt_embeds, negative_pooled = compel(negative_prompt)
82
+ [positive_prompt_embeds, negative_prompt_embeds] = compel.pad_conditioning_tensors_to_same_length(
83
+ [positive_prompt_embeds, negative_prompt_embeds]
84
+ )
85
+ sd_output = stable_diffusion_pipeline(
86
+ prompt_embeds=positive_prompt_embeds,
87
+ negative_prompt_embeds=negative_prompt_embeds,
88
+ pooled_prompt_embeds=positive_pooled,
89
+ negative_pooled_prompt_embeds=negative_pooled,
90
+ height=height,
91
+ width=width,
92
+ num_inference_steps=steps,
93
+ guidance_scale=guidance_scale,
94
+ generator=generator,
95
+ output_type="pil",
96
+ )
97
+ else:
98
+ emb_type = (
99
+ ReturnedEmbeddingsType.PENULTIMATE_HIDDEN_STATES_NORMALIZED
100
+ if clip_skip and clip_skip >= 2
101
+ else ReturnedEmbeddingsType.LAST_HIDDEN_STATES_NORMALIZED
102
+ )
103
+ compel = Compel(
104
+ tokenizer=stable_diffusion_pipeline.tokenizer,
105
+ text_encoder=stable_diffusion_pipeline.text_encoder,
106
+ returned_embeddings_type=emb_type,
107
+ truncate_long_prompts=False,
108
+ )
109
+ positive_prompt_embeds = compel(positive_prompt)
110
+ negative_prompt_embeds = compel(negative_prompt)
111
+ [positive_prompt_embeds, negative_prompt_embeds] = compel.pad_conditioning_tensors_to_same_length(
112
+ [positive_prompt_embeds, negative_prompt_embeds]
113
+ )
114
+
115
+ sd_output = stable_diffusion_pipeline(
116
+ prompt_embeds=positive_prompt_embeds,
117
+ negative_prompt_embeds=negative_prompt_embeds,
118
+ height=height,
119
+ width=width,
120
+ num_inference_steps=steps,
121
+ guidance_scale=guidance_scale,
122
+ generator=generator,
123
+ output_type="pil",
124
+ )
125
+
126
+ return sd_output.images
tinysd/generator.py ADDED
@@ -0,0 +1,128 @@
1
+ """High-level, stateful image generator."""
2
+
3
+ import os
4
+ from os import PathLike
5
+ from pathlib import Path
6
+ from typing import Union, Literal, Optional
7
+
8
+ from .generation import generate_image
9
+ from .pipeline import get_stable_diffusion_pipeline
10
+ from .schemas import StableDiffusionOutput
11
+
12
+
13
+ class SDImageGenerator:
14
+ """Load a pipeline once and generate images repeatedly with it.
15
+
16
+ Example:
17
+ >>> gen = SDImageGenerator("stabilityai/stable-diffusion-xl-base-1.0", None, None)
18
+ >>> out = gen.generate_images("a (cat:1.2) on a mat", "blurry", seed=42, nbimages=2)
19
+ >>> out.images[0].save("cat.png")
20
+ """
21
+
22
+ def __init__(
23
+ self,
24
+ base_model_id: Union[Literal["runwayml/stable-diffusion-v1-5", "stable-diffusion-v1-5/stable-diffusion-v1-5", "stabilityai/stable-diffusion-xl-base-1.0"], str],
25
+ lora_weight_path: Optional[Union[PathLike, str]],
26
+ vae_weight_path: Optional[Union[PathLike, str]],
27
+ text_encoder_id: Optional[str] = None,
28
+ tokenizer_id: Optional[str] = None,
29
+ cuda: bool = True,
30
+ text_inversion_embedding_path: Optional[Union[PathLike, str]] = None,
31
+ scheduler_name: str = "Euler",
32
+ ):
33
+ """Build the underlying pipeline.
34
+
35
+ Args:
36
+ base_model_id: Hugging Face model ID or local checkpoint path.
37
+ lora_weight_path: Optional LoRA weights path (file, directory or repo ID).
38
+ vae_weight_path: Optional custom VAE path (file, directory or repo ID).
39
+ text_encoder_id: Optional custom text encoder ID (requires ``tokenizer_id``).
40
+ tokenizer_id: Optional custom tokenizer ID (requires ``text_encoder_id``).
41
+ cuda: Use CUDA if available.
42
+ text_inversion_embedding_path: Optional textual inversion embedding path.
43
+ scheduler_name: A scheduler name from :data:`tinysd.schedulers.SCHEDULERS`.
44
+
45
+ See :func:`tinysd.pipeline.get_stable_diffusion_pipeline` for details.
46
+ """
47
+ self._base_model_id = base_model_id
48
+ if isinstance(lora_weight_path, Path):
49
+ self._lora_file_name = lora_weight_path.name
50
+ lora_weight_path = lora_weight_path.as_posix()
51
+ elif isinstance(lora_weight_path, str):
52
+ self._lora_file_name = os.path.basename(lora_weight_path)
53
+ else:
54
+ self._lora_file_name = None
55
+ if isinstance(vae_weight_path, str):
56
+ vae_weight_path = Path(vae_weight_path)
57
+ self._vae_file_name = vae_weight_path.name
58
+ elif isinstance(vae_weight_path, Path):
59
+ self._vae_file_name = vae_weight_path.name
60
+ else:
61
+ self._vae_file_name = None
62
+
63
+ self._pipe = get_stable_diffusion_pipeline(
64
+ self._base_model_id,
65
+ lora_weight_path,
66
+ vae_weight_path,
67
+ text_encoder_id=text_encoder_id,
68
+ tokenizer_id=tokenizer_id,
69
+ cuda=cuda,
70
+ text_inversion_embedding_path=text_inversion_embedding_path,
71
+ scheduler_name=scheduler_name,
72
+ )
73
+
74
+ def generate_images(
75
+ self,
76
+ positive_prompt: str,
77
+ negative_prompt: str,
78
+ height: int = 512,
79
+ width: int = 512,
80
+ steps: int = 30,
81
+ guidance_scale: float = 7.5,
82
+ seed: Optional[int] = None,
83
+ nbimages: int = 1,
84
+ clip_skip: int = 1,
85
+ ) -> StableDiffusionOutput:
86
+ """Generate ``nbimages`` images, one pipeline call per image.
87
+
88
+ Args:
89
+ positive_prompt: Prompt (A1111 or Compel syntax).
90
+ negative_prompt: Negative prompt (A1111 or Compel syntax).
91
+ height: Image height in pixels.
92
+ width: Image width in pixels.
93
+ steps: Number of denoising steps.
94
+ guidance_scale: Classifier-free guidance scale.
95
+ seed: Base seed; image ``i`` uses ``seed + i``. ``None`` is random.
96
+ nbimages: Number of images to generate.
97
+ clip_skip: CLIP skip (SD 1.x only); ``>= 2`` uses the penultimate layer.
98
+
99
+ Returns:
100
+ A :class:`StableDiffusionOutput` with the images and generation settings.
101
+ """
102
+ images = [
103
+ generate_image(
104
+ positive_prompt,
105
+ negative_prompt,
106
+ self._pipe,
107
+ height=height,
108
+ width=width,
109
+ steps=steps,
110
+ guidance_scale=guidance_scale,
111
+ seed=(seed + i if seed is not None else None),
112
+ clip_skip=clip_skip,
113
+ )[0]
114
+ for i in range(nbimages)
115
+ ]
116
+ return StableDiffusionOutput(
117
+ base_model_id=self._base_model_id,
118
+ lora_file_name=self._lora_file_name,
119
+ vae_file_name=self._vae_file_name,
120
+ positive_prompt=positive_prompt,
121
+ negative_prompt=negative_prompt,
122
+ height=height,
123
+ width=width,
124
+ steps=steps,
125
+ guidance_scale=guidance_scale,
126
+ seed=seed,
127
+ images=images
128
+ )
tinysd/pipeline.py ADDED
@@ -0,0 +1,145 @@
1
+ """Construction of Stable Diffusion / SDXL pipelines with optional VAE, LoRA and embeddings."""
2
+
3
+ import os
4
+ from os import PathLike
5
+ from typing import Union, Literal, Optional
6
+ import warnings
7
+
8
+ import torch
9
+ from diffusers import (
10
+ AutoencoderKL,
11
+ StableDiffusionPipeline,
12
+ StableDiffusionXLPipeline,
13
+ )
14
+ from safetensors.torch import load_file
15
+ from transformers import AutoModel, AutoTokenizer
16
+
17
+ from .schedulers import set_scheduler
18
+ from .utils import _ensure_text_model_attr
19
+
20
+ #: Deprecated model IDs mapped to their current Hugging Face Hub location.
21
+ MODEL_ID_ALIASES = {
22
+ "runwayml/stable-diffusion-v1-5": "stable-diffusion-v1-5/stable-diffusion-v1-5",
23
+ }
24
+
25
+
26
+ def get_stable_diffusion_pipeline(
27
+ base_model_id: Union[Literal["runwayml/stable-diffusion-v1-5", "stable-diffusion-v1-5/stable-diffusion-v1-5", "stabilityai/stable-diffusion-xl-base-1.0"], str],
28
+ lora_weights_path: Optional[Union[PathLike, str]],
29
+ vae_input_path: Optional[Union[PathLike, str]],
30
+ cuda: bool = True, # quite impractical without CUDA
31
+ text_encoder_id: Optional[str] = None,
32
+ tokenizer_id: Optional[str] = None,
33
+ text_inversion_embedding_path: Optional[Union[PathLike, str]] = None,
34
+ scheduler_name: str = "Euler",
35
+ ) -> Union[StableDiffusionPipeline, StableDiffusionXLPipeline]:
36
+ """Load a Stable Diffusion (1.x) or SDXL pipeline and apply optional add-ons.
37
+
38
+ The pipeline class is chosen by whether ``"xl"`` appears in the model ID. Single
39
+ ``.safetensors``/``.ckpt`` files are loaded with ``from_single_file``; anything
40
+ else with ``from_pretrained``. The safety checker is disabled for SD 1.x.
41
+
42
+ Args:
43
+ base_model_id: Hugging Face model ID, local diffusers directory, or local
44
+ single-file checkpoint. Deprecated IDs in :data:`MODEL_ID_ALIASES` are
45
+ resolved automatically.
46
+ lora_weights_path: Path to a LoRA weights file, a directory containing
47
+ ``pytorch_lora_weights.safetensors``, or a Hub repo ID. ``None`` or an
48
+ empty string skips LoRA loading.
49
+ vae_input_path: Path to a single-file VAE, or a diffusers VAE directory/repo
50
+ ID. ``None`` or an empty string keeps the built-in VAE.
51
+ cuda: Use CUDA with float16 if available; otherwise CPU with float32.
52
+ text_encoder_id: Optional custom text encoder ID. Must be given together
53
+ with ``tokenizer_id``.
54
+ tokenizer_id: Optional custom tokenizer ID. Must be given together with
55
+ ``text_encoder_id``.
56
+ text_inversion_embedding_path: Optional textual inversion embedding, loaded
57
+ under the token ``ng_deepnegative_v1_75t``.
58
+ scheduler_name: A scheduler name from :data:`tinysd.schedulers.SCHEDULERS`.
59
+
60
+ Returns:
61
+ The configured :class:`StableDiffusionPipeline` or
62
+ :class:`StableDiffusionXLPipeline`.
63
+
64
+ Raises:
65
+ ValueError: If ``scheduler_name`` is unknown.
66
+
67
+ Warns:
68
+ UserWarning: If only one of ``text_encoder_id`` / ``tokenizer_id`` is given;
69
+ both are then ignored.
70
+ """
71
+ resolved_model_id = str(base_model_id).strip()
72
+ if resolved_model_id in MODEL_ID_ALIASES and not os.path.exists(resolved_model_id):
73
+ resolved_model_id = MODEL_ID_ALIASES[resolved_model_id]
74
+
75
+ use_cuda = bool(cuda and torch.cuda.is_available())
76
+ dtype = torch.float16 if use_cuda else torch.float32
77
+
78
+ is_xl = "xl" in resolved_model_id.lower()
79
+ pipeline_cls = StableDiffusionXLPipeline if is_xl else StableDiffusionPipeline
80
+
81
+ extra_kwargs = {}
82
+ if not is_xl:
83
+ extra_kwargs["safety_checker"] = None # Disable for freedom
84
+
85
+ if text_encoder_id is not None and tokenizer_id is not None:
86
+ text_encoder = AutoModel.from_pretrained(text_encoder_id, torch_dtype=dtype)
87
+ tokenizer = AutoTokenizer.from_pretrained(tokenizer_id)
88
+ extra_kwargs["text_encoder"] = text_encoder
89
+ extra_kwargs["tokenizer"] = tokenizer
90
+ elif (text_encoder_id is not None) ^ (tokenizer_id is not None):
91
+ warnings.warn("You must give `text_encoder_id` and `tokenizer_id` a value or both None! Now it is assumed both are None!")
92
+
93
+ if os.path.isfile(resolved_model_id) and resolved_model_id.endswith((".safetensors", ".ckpt")):
94
+ pipe = pipeline_cls.from_single_file(
95
+ resolved_model_id,
96
+ torch_dtype=dtype,
97
+ **extra_kwargs,
98
+ )
99
+ else:
100
+ pipe = pipeline_cls.from_pretrained(
101
+ resolved_model_id,
102
+ torch_dtype=dtype,
103
+ **extra_kwargs,
104
+ )
105
+
106
+ if use_cuda:
107
+ pipe = pipe.to("cuda")
108
+
109
+ set_scheduler(pipe, scheduler_name)
110
+
111
+ if vae_input_path is not None:
112
+ vae_path_str = vae_input_path if isinstance(vae_input_path, str) else vae_input_path.as_posix()
113
+ if len(vae_path_str) > 0:
114
+ if os.path.isfile(vae_path_str):
115
+ try:
116
+ pipe.vae = AutoencoderKL.from_single_file(vae_path_str, torch_dtype=dtype)
117
+ except Exception:
118
+ vae_weights = load_file(vae_path_str)
119
+ pipe.vae.load_state_dict(vae_weights, strict=False)
120
+ else:
121
+ pipe.vae = AutoencoderKL.from_pretrained(vae_path_str, torch_dtype=dtype)
122
+ if use_cuda:
123
+ pipe.vae = pipe.vae.to("cuda", dtype=dtype)
124
+
125
+ if lora_weights_path is not None:
126
+ lora_path_str = lora_weights_path if isinstance(lora_weights_path, str) else lora_weights_path.as_posix()
127
+ if len(lora_path_str) > 0:
128
+ if os.path.isfile(lora_path_str):
129
+ pipe.load_lora_weights(
130
+ os.path.dirname(lora_path_str) or ".",
131
+ weight_name=os.path.basename(lora_path_str),
132
+ )
133
+ elif os.path.isdir(lora_path_str) and os.path.isfile(
134
+ os.path.join(lora_path_str, "pytorch_lora_weights.safetensors")
135
+ ):
136
+ pipe.load_lora_weights(lora_path_str, weight_name="pytorch_lora_weights.safetensors")
137
+ else:
138
+ pipe.load_lora_weights(lora_path_str)
139
+
140
+ if text_inversion_embedding_path is not None:
141
+ pipe.load_textual_inversion(text_inversion_embedding_path, token='ng_deepnegative_v1_75t')
142
+
143
+ _ensure_text_model_attr(getattr(pipe, "text_encoder", None))
144
+ _ensure_text_model_attr(getattr(pipe, "text_encoder_2", None))
145
+ return pipe
tinysd/prompt.py ADDED
@@ -0,0 +1,93 @@
1
+ """Conversion of AUTOMATIC1111 (A1111) prompt syntax into Compel prompt syntax."""
2
+
3
+ import re
4
+
5
+
6
+ def _convert_a1111_segment_to_compel(segment: str) -> str:
7
+ """Convert A1111 weighting syntax within a single prompt segment to Compel syntax.
8
+
9
+ Handles ``<lora:...>`` tag removal, ``[text:weight]``, ``[text]`` (de-emphasis),
10
+ ``(text:weight)`` and bare ``(text)`` (A1111's implicit 1.1x emphasis).
11
+
12
+ Args:
13
+ segment: A prompt segment that contains no ``BREAK`` keyword.
14
+
15
+ Returns:
16
+ The segment rewritten in Compel syntax.
17
+ """
18
+ # Remove inline A1111 <lora:name:weight> tags so they aren't tokenized as literal words
19
+ segment = re.sub(r"<lora:[^>]+>", "", segment)
20
+
21
+ # Convert [text:weight] -> (text)weight
22
+ segment = re.sub(
23
+ r"(?<!\\)\[([^\[\]]+?):\s*([0-9]*\.?[0-9]+)\s*(?<!\\)\]",
24
+ r"(\1)\2",
25
+ segment,
26
+ )
27
+
28
+ # Convert [text] (de-emphasis, nested supported) -> (text)-
29
+ prev = None
30
+ while prev != segment:
31
+ prev = segment
32
+ segment = re.sub(r"(?<!\\)\[([^\[\]]+?)(?<!\\)\]", r"(\1)-", segment)
33
+
34
+ # Convert (text:weight) -> (text)weight (innermost first to handle nesting)
35
+ prev = None
36
+ while prev != segment:
37
+ prev = segment
38
+ segment = re.sub(
39
+ r"(?<!\\)\(([^()]+?):\s*([0-9]*\.?[0-9]+)\s*(?<!\\)\)",
40
+ r"(\1)\2",
41
+ segment,
42
+ )
43
+
44
+ # In A1111, bare (text) multiplies weight by 1.1, whereas in Compel bare (text) is 1.0
45
+ # unless followed by +, -, a weight number, or an operator (.and, .blend, .attend, .swap).
46
+ out = []
47
+ i = 0
48
+ n = len(segment)
49
+ while i < n:
50
+ if segment[i] == ")" and (i == 0 or segment[i - 1] != "\\"):
51
+ out.append(")")
52
+ rest = segment[i + 1 :]
53
+ if not re.match(r"^(?:[+\-]|[0-9]|\.(?:attend|blend|and|add|swap)\b)", rest):
54
+ out.append("+")
55
+ i += 1
56
+ else:
57
+ out.append(segment[i])
58
+ i += 1
59
+ return "".join(out)
60
+
61
+
62
+ def convert_a1111_to_compel(prompt: str) -> str:
63
+ """Convert AUTOMATIC1111 prompt syntax (weights, brackets, BREAK) into Compel syntax.
64
+
65
+ Prompts that already use Compel's top-level ``.and()``/``.add()``/``.blend()``
66
+ are returned unchanged. Prompts containing ``BREAK`` are split into chunks and
67
+ combined with Compel's ``.and()`` conjunction.
68
+
69
+ Args:
70
+ prompt: A prompt written in A1111 syntax.
71
+
72
+ Returns:
73
+ The equivalent prompt in Compel syntax. Empty or whitespace-only prompts are
74
+ returned as-is.
75
+
76
+ Examples:
77
+ >>> convert_a1111_to_compel("a (cat:1.3) on a [mat]")
78
+ 'a (cat)1.3 on a (mat)-'
79
+ """
80
+ if not prompt or not prompt.strip():
81
+ return prompt
82
+ # Leave prompts that already use Compel's top-level .and()/.blend() untouched
83
+ if re.search(r"\)\s*\.(?:and|add|blend)\s*\(", prompt):
84
+ return prompt
85
+
86
+ chunks = re.split(r"\bBREAK\b", prompt)
87
+ converted_chunks = [_convert_a1111_segment_to_compel(c).strip() for c in chunks]
88
+ if len(converted_chunks) == 1:
89
+ return converted_chunks[0]
90
+
91
+ escaped_chunks = [c.replace('"', '\\"') for c in converted_chunks]
92
+ joined = ", ".join(f'"{c}"' for c in escaped_chunks)
93
+ return f"({joined}).and()"
tinysd/schedulers.py ADDED
@@ -0,0 +1,56 @@
1
+ """Sampler/scheduler registry using AUTOMATIC1111-style names."""
2
+
3
+ from diffusers import (
4
+ DDIMScheduler,
5
+ DPMSolverMultistepScheduler,
6
+ DPMSolverSinglestepScheduler,
7
+ EulerAncestralDiscreteScheduler,
8
+ EulerDiscreteScheduler,
9
+ HeunDiscreteScheduler,
10
+ KDPM2AncestralDiscreteScheduler,
11
+ KDPM2DiscreteScheduler,
12
+ UniPCMultistepScheduler,
13
+ )
14
+
15
+ #: Mapping of A1111 sampler names to ``(diffusers scheduler class, extra config kwargs)``.
16
+ SCHEDULERS = {
17
+ "Euler a": (EulerAncestralDiscreteScheduler, {}),
18
+ "Euler": (EulerDiscreteScheduler, {}),
19
+ "DPM++ 2M": (DPMSolverMultistepScheduler, {}),
20
+ "DPM++ 2M Karras": (DPMSolverMultistepScheduler, {"use_karras_sigmas": True}),
21
+ "DPM++ 2M SDE": (DPMSolverMultistepScheduler, {"algorithm_type": "sde-dpmsolver++"}),
22
+ "DPM++ 2M SDE Karras": (
23
+ DPMSolverMultistepScheduler,
24
+ {"algorithm_type": "sde-dpmsolver++", "use_karras_sigmas": True},
25
+ ),
26
+ "DPM++ SDE": (DPMSolverSinglestepScheduler, {}),
27
+ "DPM++ SDE Karras": (DPMSolverSinglestepScheduler, {"use_karras_sigmas": True}),
28
+ "Heun": (HeunDiscreteScheduler, {}),
29
+ "KDPM2": (KDPM2DiscreteScheduler, {}),
30
+ "KDPM2 a": (KDPM2AncestralDiscreteScheduler, {}),
31
+ "DDIM": (DDIMScheduler, {}),
32
+ "UniPC": (UniPCMultistepScheduler, {}),
33
+ }
34
+
35
+
36
+ def set_scheduler(pipe, scheduler_name: str = "Euler"):
37
+ """Replace the scheduler of a diffusers pipeline in place.
38
+
39
+ The new scheduler is built from the pipeline's current scheduler config, so
40
+ model-specific settings (e.g. beta schedule) are preserved.
41
+
42
+ Args:
43
+ pipe: A diffusers pipeline exposing a ``scheduler`` attribute.
44
+ scheduler_name: A key of :data:`SCHEDULERS`, e.g. ``"DPM++ 2M Karras"``.
45
+
46
+ Returns:
47
+ The same pipeline object, for chaining.
48
+
49
+ Raises:
50
+ ValueError: If ``scheduler_name`` is not a known scheduler.
51
+ """
52
+ if scheduler_name not in SCHEDULERS:
53
+ raise ValueError(f"Unknown scheduler '{scheduler_name}'. Available: {list(SCHEDULERS.keys())}")
54
+ scheduler_cls, kwargs = SCHEDULERS[scheduler_name]
55
+ pipe.scheduler = scheduler_cls.from_config(pipe.scheduler.config, **kwargs)
56
+ return pipe
tinysd/schemas.py ADDED
@@ -0,0 +1,37 @@
1
+ """Data containers returned by the TinySD public API."""
2
+
3
+ from dataclasses import dataclass, field
4
+ from typing import Optional
5
+
6
+ import PIL.Image
7
+
8
+
9
+ @dataclass
10
+ class StableDiffusionOutput:
11
+ """Result of an image generation request, together with its generation settings.
12
+
13
+ Attributes:
14
+ base_model_id: Hugging Face model ID or local path of the base checkpoint.
15
+ lora_file_name: File name of the LoRA weights used, or ``None``.
16
+ vae_file_name: File name of the custom VAE used, or ``None``.
17
+ positive_prompt: The positive prompt used for generation.
18
+ negative_prompt: The negative prompt used for generation.
19
+ height: Image height in pixels.
20
+ width: Image width in pixels.
21
+ steps: Number of denoising steps.
22
+ guidance_scale: Classifier-free guidance scale.
23
+ seed: Base random seed, or ``None`` for non-deterministic generation.
24
+ images: The generated PIL images.
25
+ """
26
+
27
+ base_model_id: str
28
+ lora_file_name: Optional[str]
29
+ vae_file_name: Optional[str]
30
+ positive_prompt: str
31
+ negative_prompt: str
32
+ height: int
33
+ width: int
34
+ steps: int
35
+ guidance_scale: float
36
+ seed: Optional[int]
37
+ images: list[PIL.Image.Image] = field(default_factory=list)
tinysd/sd.py ADDED
@@ -0,0 +1,23 @@
1
+ """Backward-compatible facade.
2
+
3
+ The implementation now lives in dedicated modules; this module re-exports
4
+ everything that used to be defined here so ``from tinysd.sd import ...`` keeps working.
5
+ """
6
+
7
+ from .generation import generate_image
8
+ from .generator import SDImageGenerator
9
+ from .pipeline import MODEL_ID_ALIASES, get_stable_diffusion_pipeline
10
+ from .prompt import convert_a1111_to_compel
11
+ from .schedulers import SCHEDULERS, set_scheduler
12
+ from .schemas import StableDiffusionOutput
13
+
14
+ __all__ = [
15
+ "MODEL_ID_ALIASES",
16
+ "SCHEDULERS",
17
+ "SDImageGenerator",
18
+ "StableDiffusionOutput",
19
+ "convert_a1111_to_compel",
20
+ "generate_image",
21
+ "get_stable_diffusion_pipeline",
22
+ "set_scheduler",
23
+ ]
tinysd/utils.py ADDED
@@ -0,0 +1,35 @@
1
+ """Internal helpers shared across TinySD modules."""
2
+
3
+ from diffusers import StableDiffusionXLPipeline
4
+
5
+
6
+ def _is_sdxl_pipeline(pipe) -> bool:
7
+ """Return whether ``pipe`` is a Stable Diffusion XL pipeline.
8
+
9
+ A pipeline is considered SDXL if it is a :class:`StableDiffusionXLPipeline`
10
+ instance, or if it has both a second tokenizer and a second text encoder.
11
+
12
+ Args:
13
+ pipe: A diffusers pipeline (or duck-typed equivalent).
14
+
15
+ Returns:
16
+ ``True`` if the pipeline is SDXL-like, ``False`` otherwise.
17
+ """
18
+ return (
19
+ isinstance(pipe, StableDiffusionXLPipeline)
20
+ or (getattr(pipe, "tokenizer_2", None) is not None and getattr(pipe, "text_encoder_2", None) is not None)
21
+ )
22
+
23
+
24
+ def _ensure_text_model_attr(text_encoder) -> None:
25
+ """Ensure compatibility with transformers >= 5.6 where CLIPTextModel flattened `.text_model`.
26
+
27
+ If ``text_encoder`` lacks a ``text_model`` attribute, a property returning the
28
+ encoder itself is added to its class, so Compel can keep accessing
29
+ ``text_encoder.text_model``.
30
+
31
+ Args:
32
+ text_encoder: A text encoder module, or ``None`` (no-op).
33
+ """
34
+ if text_encoder is not None and not hasattr(text_encoder, "text_model"):
35
+ setattr(type(text_encoder), "text_model", property(lambda self: self))
@@ -0,0 +1,205 @@
1
+ Metadata-Version: 2.4
2
+ Name: tinysd
3
+ Version: 0.0.1
4
+ Summary: A small wrapper around diffusers for Stable Diffusion 1.x and SDXL with A1111-style prompts.
5
+ License-Expression: MIT
6
+ Requires-Python: >=3.9
7
+ Description-Content-Type: text/markdown
8
+ License-File: LICENSE
9
+ Requires-Dist: torch
10
+ Requires-Dist: diffusers
11
+ Requires-Dist: transformers
12
+ Requires-Dist: compel
13
+ Requires-Dist: safetensors
14
+ Requires-Dist: accelerate
15
+ Requires-Dist: peft
16
+ Requires-Dist: Pillow
17
+ Provides-Extra: test
18
+ Requires-Dist: pytest; extra == "test"
19
+ Dynamic: license-file
20
+
21
+ # TinySD
22
+
23
+ TinySD is a small Python wrapper around [🤗 diffusers](https://github.com/huggingface/diffusers) for
24
+ **Stable Diffusion 1.x** and **SDXL**. It lets you generate images with a few lines of code while keeping
25
+ the conveniences of the AUTOMATIC1111 (A1111) WebUI:
26
+
27
+ - **A1111 prompt syntax**: `(word:1.3)`, `[word]`, `((word))`, `BREAK`, and `<lora:...>` tags are converted
28
+ automatically to [Compel](https://github.com/damian0815/compel) syntax. Long prompts are not truncated.
29
+ - **A1111 sampler names**: `"Euler a"`, `"DPM++ 2M Karras"`, `"DPM++ 2M SDE Karras"`, `"UniPC"`, and others.
30
+ - **Flexible model loading**: Hugging Face Hub IDs, local diffusers folders, or single `.safetensors` / `.ckpt`
31
+ checkpoints (e.g. from Civitai).
32
+ - **Add-ons**: custom VAE, LoRA weights, textual inversion embeddings, custom text encoder/tokenizer.
33
+ - **CLIP skip** for SD 1.x models, and **reproducible seeds**.
34
+
35
+ ## Installation
36
+
37
+ Requires Python ≥ 3.9. A CUDA GPU is strongly recommended; TinySD falls back to CPU (float32) otherwise.
38
+
39
+ ```bash
40
+ git clone <this-repo> TinySD
41
+ cd TinySD
42
+ pip install -e .
43
+ ```
44
+
45
+ If you need a specific CUDA build of PyTorch, install it first (see [pytorch.org](https://pytorch.org)).
46
+
47
+ ## Quick start
48
+
49
+ ```python
50
+ from tinysd import SDImageGenerator
51
+
52
+ generator = SDImageGenerator(
53
+ base_model_id="stabilityai/stable-diffusion-xl-base-1.0",
54
+ lora_weight_path=None,
55
+ vae_weight_path=None,
56
+ scheduler_name="DPM++ 2M Karras",
57
+ )
58
+
59
+ result = generator.generate_images(
60
+ positive_prompt="a (fluffy cat:1.3) sitting on a windowsill, golden hour, ((highly detailed))",
61
+ negative_prompt="blurry, [low quality], watermark",
62
+ height=1024,
63
+ width=1024,
64
+ steps=30,
65
+ guidance_scale=7.0,
66
+ seed=42,
67
+ nbimages=2,
68
+ )
69
+
70
+ for i, image in enumerate(result.images):
71
+ image.save(f"cat_{i}.png")
72
+
73
+ print(result.seed, result.steps, result.base_model_id)
74
+ ```
75
+
76
+ `generate_images` returns a `StableDiffusionOutput` dataclass that holds the generated PIL images and the
77
+ settings used to produce them (model, LoRA/VAE file names, prompts, size, steps, guidance scale, seed).
78
+ When `seed` is given, image `i` uses `seed + i`, so results are reproducible.
79
+
80
+ ## Usage examples
81
+
82
+ ### Stable Diffusion 1.5 with LoRA, VAE and CLIP skip
83
+
84
+ ```python
85
+ from pathlib import Path
86
+ from tinysd import SDImageGenerator
87
+
88
+ generator = SDImageGenerator(
89
+ base_model_id="stable-diffusion-v1-5/stable-diffusion-v1-5", # "runwayml/..." is aliased automatically
90
+ lora_weight_path=Path("loras/my_style.safetensors"), # file, folder, or Hub repo ID
91
+ vae_weight_path="vae/vae-ft-mse-840000-ema-pruned.safetensors",
92
+ scheduler_name="Euler a",
93
+ )
94
+
95
+ result = generator.generate_images(
96
+ positive_prompt="portrait of a knight, (intricate armor:1.2), BREAK dramatic lighting, castle background",
97
+ negative_prompt="(worst quality:1.4), lowres, bad anatomy",
98
+ seed=1234,
99
+ clip_skip=2,
100
+ )
101
+ result.images[0].save("knight.png")
102
+ ```
103
+
104
+ ### Local single-file checkpoint and textual inversion
105
+
106
+ ```python
107
+ from tinysd import SDImageGenerator
108
+
109
+ generator = SDImageGenerator(
110
+ base_model_id="checkpoints/myModel_v10.safetensors", # "xl" in the name selects the SDXL pipeline
111
+ lora_weight_path=None,
112
+ vae_weight_path=None,
113
+ text_inversion_embedding_path="embeddings/ng_deepnegative_v1_75t.pt",
114
+ )
115
+
116
+ result = generator.generate_images(
117
+ positive_prompt="a cozy cabin in a snowy forest",
118
+ negative_prompt="ng_deepnegative_v1_75t, blurry", # embedding is registered under this token
119
+ )
120
+ ```
121
+
122
+ ### Lower-level API
123
+
124
+ If you want to manage the pipeline yourself, for example to change the scheduler between runs or generate
125
+ a batch in one call:
126
+
127
+ ```python
128
+ from tinysd import get_stable_diffusion_pipeline, generate_image, set_scheduler
129
+
130
+ pipe = get_stable_diffusion_pipeline(
131
+ "stabilityai/stable-diffusion-xl-base-1.0",
132
+ lora_weights_path=None,
133
+ vae_input_path=None,
134
+ cuda=True,
135
+ )
136
+
137
+ set_scheduler(pipe, "UniPC")
138
+
139
+ images = generate_image(
140
+ positive_prompt=["a red apple", "a green pear"], # one image per prompt
141
+ negative_prompt=["blurry", "blurry"],
142
+ stable_diffusion_pipeline=pipe,
143
+ height=1024,
144
+ width=1024,
145
+ steps=25,
146
+ seed=7, # prompt i uses seed + i
147
+ )
148
+ ```
149
+
150
+ ### Prompt conversion only
151
+
152
+ ```python
153
+ from tinysd import convert_a1111_to_compel
154
+
155
+ convert_a1111_to_compel("a (cat:1.3) on a [mat]")
156
+ # 'a (cat)1.3 on a (mat)-'
157
+
158
+ convert_a1111_to_compel("a ((red)) car <lora:style:0.8>")
159
+ # 'a ((red)+)+ car'
160
+
161
+ convert_a1111_to_compel("a cat BREAK a dog")
162
+ # '("a cat", "a dog").and()'
163
+ ```
164
+
165
+ Pass `convert_a1111_syntax=False` to `generate_image` if your prompts are already written in Compel syntax.
166
+
167
+ ### Available schedulers
168
+
169
+ ```python
170
+ from tinysd import SCHEDULERS
171
+ print(list(SCHEDULERS))
172
+ # ['Euler a', 'Euler', 'DPM++ 2M', 'DPM++ 2M Karras', 'DPM++ 2M SDE', 'DPM++ 2M SDE Karras',
173
+ # 'DPM++ SDE', 'DPM++ SDE Karras', 'Heun', 'KDPM2', 'KDPM2 a', 'DDIM', 'UniPC']
174
+ ```
175
+
176
+ ## Package layout
177
+
178
+ ```
179
+ src/tinysd/
180
+ ├── __init__.py # public API
181
+ ├── prompt.py # A1111 -> Compel prompt conversion
182
+ ├── schedulers.py # SCHEDULERS registry and set_scheduler()
183
+ ├── pipeline.py # get_stable_diffusion_pipeline(): model, VAE, LoRA, embeddings
184
+ ├── generation.py # generate_image(): Compel encoding + inference
185
+ ├── generator.py # SDImageGenerator high-level class
186
+ ├── schemas.py # StableDiffusionOutput dataclass
187
+ ├── utils.py # internal helpers
188
+ └── sd.py # backward-compatible re-exports
189
+ ```
190
+
191
+ ## Running tests
192
+
193
+ The unit tests mock all model loading, so they run quickly and need neither a GPU nor network access:
194
+
195
+ ```bash
196
+ PYTHONPATH=src python -m unittest discover -s tests -t .
197
+ # or, with pytest installed:
198
+ pytest
199
+ ```
200
+
201
+ ## Notes
202
+
203
+ - The safety checker is disabled for SD 1.x pipelines.
204
+ - The SD vs. SDXL choice is based on whether `"xl"` appears in the model ID or path.
205
+ - `clip_skip` applies only to SD 1.x. SDXL always uses the penultimate hidden states.
@@ -0,0 +1,14 @@
1
+ tinysd/__init__.py,sha256=7Lu-l0h0tNqLL3ke4M0j6GtwVFleUP1IK6bhIDIk0po,1038
2
+ tinysd/generation.py,sha256=aULNV7uoPB_Wv84tPs8_vxoOTmiX0o0HBGrluTI3yAo,5340
3
+ tinysd/generator.py,sha256=MrqBQD6Ot_HKWDBIIwHN7lhL33zudUz4SHwC34lkYbI,5084
4
+ tinysd/pipeline.py,sha256=AmzhE1EQ5AH1Ntbf95W7LVdEb8ukAOiatKVID0xnnyE,6384
5
+ tinysd/prompt.py,sha256=i4oQqMnoDOuiXpWq8UPeFyaJgr3na6YcwoWCZDo2bNk,3239
6
+ tinysd/schedulers.py,sha256=uLZPn71pZwpJ-d8lCivip9PGJ3Cyfg-8m9ZofOwMmik,2171
7
+ tinysd/schemas.py,sha256=OskD5ISj2Zj0x3O9-oCGfYrmo3DV64DtFG-JB1ByO48,1252
8
+ tinysd/sd.py,sha256=SB2W4bEU2N8OBXhjpfWWQOeezQdL3DSvg25rii5G2zk,706
9
+ tinysd/utils.py,sha256=tESANt8KuPd1DdhFRXVwOTqCicdqN1JieYVF9njBkuY,1295
10
+ tinysd-0.0.1.dist-info/licenses/LICENSE,sha256=e5StoRk2BPyRQh1Iqjo3RkrjS32c4DCr9kzPSKpWkt8,1077
11
+ tinysd-0.0.1.dist-info/METADATA,sha256=ss5NamXdWCNeqQRY6PUrPxkJpkt8rDKCCd3LrpE7Abc,6540
12
+ tinysd-0.0.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
13
+ tinysd-0.0.1.dist-info/top_level.txt,sha256=v0JtwBLizTjtfiHFBfug4Fn_k_EqbEvZKbWP0GvD9Y8,7
14
+ tinysd-0.0.1.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Kwan Yuet Stephen Ho
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1 @@
1
+ tinysd