kiapi 0.1.0__py3-none-any.whl

kiapi/capabilities/qwen/_operations/handle_generate.py

@@ -0,0 +1,46 @@
+"""Qwen Image generate service entry (worker-thread thunk body)."""
+
+from kiapi.capabilities import get_file_path
+from kiapi.core.app import AppContext
+from kiapi.core.file import FileID
+from kiapi.core.job import JobResult
+from kiapi.core.model import model_registry
+
+from .._settings import settings_manager
+from .._views.generate_request import GenerateRequest
+from .is_quantize_override import is_quantize_override
+from .resolve_generate_params import resolve_generate_params
+from .resolve_lora_params import resolve_lora_params
+
+
+def handle_generate(
+    ctx: AppContext, req: GenerateRequest
+) -> tuple[JobResult, list[FileID]]:
+    settings = settings_manager.get_settings()
+    spec = model_registry.resolve("qwen", req.model or "image")
+    ctx.ensure_model_ready(spec)
+    init_image_path = (
+        get_file_path(ctx.file_store, req.init_image, kind="init_image")
+        if req.init_image is not None
+        else None
+    )
+    lora_params = resolve_lora_params(ctx, req.loras)
+    override = is_quantize_override(settings, req)
+    params = resolve_generate_params(
+        settings, req, variant=spec.name, init_image_path=init_image_path
+    )
+
+    if lora_params.paths or override:
+        ctx.memory_manager.reserve(spec.weight_gb + spec.peak_headroom_gb)
+        result = spec.module.run_generate_transient(
+            spec,
+            params,
+            ctx.file_store,
+            lora_paths=lora_params.paths,
+            lora_scales=lora_params.scales,
+        )
+    else:
+        payload = ctx.memory_manager.acquire(spec)
+        result = spec.module.run_generate(payload, params, ctx.file_store)
+
+    return result, [result["file_id"]]

kiapi/capabilities/qwen/_operations/is_quantize_override.py

@@ -0,0 +1,15 @@
+"""Decide whether a request's quantize differs from the variant default.
+
+A True result means the resident model (quantized at its default) can't serve the
+request, so ``handle_*`` runs a one-off transient model instead.
+"""
+
+from .._settings import QwenSettings
+from .._views.edit_request import EditRequest
+from .._views.generate_request import GenerateRequest
+
+
+def is_quantize_override(
+    settings: QwenSettings, req: GenerateRequest | EditRequest
+) -> bool:
+    return req.quantize is not None and req.quantize != settings.default_quantize

kiapi/capabilities/qwen/_operations/resolve_edit_params.py

@@ -0,0 +1,35 @@
+"""Merge an edit request with settings defaults into the complete EditParams."""
+
+import random
+
+from .._settings import QwenSettings
+from .._views.edit_params import EditParams
+from .._views.edit_request import EditRequest
+
+
+def resolve_edit_params(
+    settings: QwenSettings,
+    req: EditRequest,
+    *,
+    variant: str,
+    image_paths: list[str],
+) -> EditParams:
+    return EditParams(
+        model=variant,
+        prompt=req.prompt,
+        negative_prompt=req.negative_prompt,
+        image_file_ids=[],
+        image_paths=image_paths,
+        seed=req.seed if req.seed is not None else random.randint(0, 2**31 - 1),
+        width=req.width if req.width is not None else settings.default_width,
+        height=req.height if req.height is not None else settings.default_height,
+        steps=req.steps if req.steps is not None else settings.edit_steps,
+        guidance=req.guidance if req.guidance is not None else settings.edit_guidance,
+        quantize=req.quantize
+        if req.quantize is not None
+        else settings.default_quantize,
+        scheduler=req.scheduler,
+        format=req.format,
+        quality=req.quality,
+        loras=req.loras,
+    )

kiapi/capabilities/qwen/_operations/resolve_generate_params.py

@@ -0,0 +1,39 @@
+"""Merge a generate request with settings defaults into the complete GenerateParams."""
+
+import random
+
+from .._settings import QwenSettings
+from .._views.generate_params import GenerateParams
+from .._views.generate_request import GenerateRequest
+
+
+def resolve_generate_params(
+    settings: QwenSettings,
+    req: GenerateRequest,
+    *,
+    variant: str,
+    init_image_path: str | None,
+) -> GenerateParams:
+    return GenerateParams(
+        kind="img2img" if init_image_path is not None else "txt2img",
+        model=variant,
+        prompt=req.prompt,
+        negative_prompt=req.negative_prompt,
+        init_image_file_id=None,
+        image_path=init_image_path,
+        image_strength=req.image_strength,
+        seed=req.seed if req.seed is not None else random.randint(0, 2**31 - 1),
+        width=req.width if req.width is not None else settings.default_width,
+        height=req.height if req.height is not None else settings.default_height,
+        steps=req.steps if req.steps is not None else settings.generate_steps,
+        guidance=req.guidance
+        if req.guidance is not None
+        else settings.generate_guidance,
+        quantize=req.quantize
+        if req.quantize is not None
+        else settings.default_quantize,
+        scheduler=req.scheduler,
+        format=req.format,
+        quality=req.quality,
+        loras=req.loras,
+    )

kiapi/capabilities/qwen/_operations/resolve_lora_params.py

@@ -0,0 +1,23 @@
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+
+from kiapi.capabilities import get_file_path
+from kiapi.core.app import AppContext
+
+from .._schemas.lora_ref import LoraRef
+
+
+@dataclass
+class LoraParams:
+    paths: list[str] = field(default_factory=list)
+    scales: list[float] = field(default_factory=list)
+
+
+def resolve_lora_params(ctx: AppContext, loras: Iterable[LoraRef]) -> LoraParams:
+    params = LoraParams()
+
+    for lr in loras:
+        params.paths.append(get_file_path(ctx.file_store, lr.file, kind="lora"))
+        params.scales.append(lr.scale)
+
+    return params

kiapi/capabilities/qwen/_operations/validate_common.py

@@ -0,0 +1,32 @@
+from kiapi.capabilities import ValidationError
+
+from .._settings import QwenSettings
+from .._views.edit_request import EditRequest
+from .._views.generate_request import GenerateRequest
+
+_MULTIPLE = 16
+
+
+def validate_common(
+    req: GenerateRequest | EditRequest, settings: QwenSettings, *, role: str
+) -> None:
+    width = req.width if req.width is not None else settings.default_width
+    height = req.height if req.height is not None else settings.default_height
+
+    if width <= 0 or height <= 0:
+        raise ValidationError("width and height must be positive")
+    if width % _MULTIPLE or height % _MULTIPLE:
+        raise ValidationError(f"width and height must be multiples of {_MULTIPLE}")
+    if width > settings.max_width or height > settings.max_height:
+        raise ValidationError(
+            f"size {width}x{height} exceeds the cap {settings.max_width}x{settings.max_height}"
+        )
+
+    default_steps = settings.edit_steps if role == "edit" else settings.generate_steps
+    steps = req.steps if req.steps is not None else default_steps
+    if steps < 1 or steps > settings.max_steps:
+        raise ValidationError(f"steps must be in 1..{settings.max_steps}")
+    if req.quantize is not None and req.quantize not in (3, 4, 5, 6, 8):
+        raise ValidationError("quantize must be one of 3, 4, 5, 6, 8")
+    if len(req.loras) > settings.max_loras:
+        raise ValidationError(f"at most {settings.max_loras} loras may be applied")

kiapi/capabilities/qwen/_schemas/lora_ref.py

@@ -0,0 +1,27 @@
+"""A single LoRA adapter reference (file + scale) applied to a qwen run."""
+
+from pydantic import BaseModel, Field
+
+from kiapi.core.file import FileRef
+
+
+class LoraRef(BaseModel):
+    """One LoRA adapter to apply, by Files-API reference and blend scale.
+
+    Any lora forces a one-off transient model (slower, not reused). Up to 4 may
+    be passed in a request's ``loras`` list.
+    """
+
+    file: FileRef = Field(
+        description=(
+            "The LoRA adapter (`.safetensors`) to apply, as a Files-API file id, "
+            "http(s) URL, or data URL."
+        ),
+    )
+    scale: float = Field(
+        default=1.0,
+        description=(
+            "Blend strength for this adapter. 1.0 applies it at full weight; lower "
+            "values weaken its effect, higher values exaggerate it."
+        ),
+    )

kiapi/capabilities/qwen/_settings.py

@@ -0,0 +1,107 @@
+"""Qwen Image capability defaults + caps, read from ``KIAPI_QWEN_`` env vars."""
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from pydantic_settings_manager import SettingsManager
+
+
+class QwenSettings(BaseSettings):
+    """Settings for Qwen Image models, generation defaults, and LoRA limits."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="KIAPI_QWEN_",
+        extra="ignore",
+        protected_namespaces=(),
+    )
+
+    image_model: str = Field(
+        default="Qwen/Qwen-Image",
+        title="Image generation model repo",
+        description="Hugging Face repo ID used for Qwen Image text-to-image generation.",
+    )
+
+    edit_model: str = Field(
+        default="Qwen/Qwen-Image-Edit-2509",
+        title="Image editing model repo",
+        description="Hugging Face repo ID used for Qwen Image editing.",
+    )
+
+    default_quantize: int | None = Field(
+        default=8,
+        title="Default quantization bits",
+        description=(
+            "Default quantization bit count used when loading the Qwen Image model.\n"
+            "Use a bit count such as 8, or None to disable quantization."
+        ),
+    )
+
+    # --------------------------------------------------
+    # generate
+    # --------------------------------------------------
+
+    default_width: int = Field(
+        default=1024,
+        title="Default width",
+        description="Output image width in pixels used when a request omits width.",
+    )
+
+    default_height: int = Field(
+        default=1024,
+        title="Default height",
+        description="Output image height in pixels used when a request omits height.",
+    )
+
+    max_width: int = Field(
+        default=2048,
+        title="Maximum width",
+        description="Upper pixel limit for the output image width accepted in a request.",
+    )
+
+    max_height: int = Field(
+        default=2048,
+        title="Maximum height",
+        description="Upper pixel limit for the output image height accepted in a request.",
+    )
+
+    max_steps: int = Field(
+        default=100,
+        title="Maximum inference steps",
+        description="Upper limit for the diffusion step count accepted in a request.",
+    )
+
+    max_loras: int = Field(
+        default=4,
+        title="Maximum LoRA count",
+        description="Maximum number of LoRA adapters that can be applied in one generation or edit request.",
+    )
+
+    generate_steps: int = Field(
+        default=30,
+        title="Default generation steps",
+        description="Diffusion step count used when a text-to-image request omits steps.",
+    )
+
+    generate_guidance: float = Field(
+        default=4.0,
+        title="Default generation guidance",
+        description="Guidance strength used when a text-to-image request omits guidance.",
+    )
+
+    # --------------------------------------------------
+    # edit
+    # --------------------------------------------------
+
+    edit_steps: int = Field(
+        default=30,
+        title="Default editing steps",
+        description="Diffusion step count used when an image editing request omits steps.",
+    )
+
+    edit_guidance: float = Field(
+        default=2.5,
+        title="Default editing guidance",
+        description="Guidance strength used when an image editing request omits guidance.",
+    )
+
+
+settings_manager = SettingsManager(QwenSettings)

kiapi/capabilities/qwen/_views/edit_params.py

@@ -0,0 +1,36 @@
+"""The complete contract for one Qwen Image edit run.
+
+Built from settings + request by ``resolve_edit_params``; the model needs nothing
+else to produce the image and its metadata. ``image_paths`` are the locally
+resolved input files, kept out of the recorded metadata in favour of
+``image_file_ids``.
+"""
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+from .._schemas.lora_ref import LoraRef
+
+
+class EditParams(BaseModel):
+    kind: Literal["edit"] = "edit"
+    model: str
+
+    prompt: str
+    negative_prompt: str | None
+    image_file_ids: list[str]
+    image_paths: list[str]
+
+    seed: int
+    width: int
+    height: int
+    steps: int
+    guidance: float
+    quantize: int | None
+    scheduler: str
+
+    format: Literal["png", "jpeg", "webp"]
+    quality: int
+
+    loras: list[LoraRef]

kiapi/capabilities/qwen/_views/edit_request.py

@@ -0,0 +1,138 @@
+"""Qwen Image edit request model. Natural-language single/multi-image editing.
+
+One endpoint serves both sync and async via ``mode``. Takes one or more reference
+``images`` plus a ``prompt``; defaults for ``width`` / ``height`` / ``steps`` /
+``guidance`` / ``quantize`` are resolved server-side when omitted. A ``quantize``
+override or any ``loras`` builds a one-off transient model (slower, not reused).
+"""
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from kiapi.core.file import FileRef
+
+from .._schemas.lora_ref import LoraRef
+
+
+class EditRequest(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    model: str | None = Field(
+        default=None,
+        description=(
+            "Model variant (see GET /v1/image/qwen/models). Omit for the default "
+            "`edit-2509`; `/edit` only accepts `edit-2509` (use `/generate` for "
+            "`image`)."
+        ),
+    )
+    mode: Literal["sync", "async"] = Field(
+        default="sync",
+        description=(
+            "`sync` waits for the image (504 on timeout); `async` returns 202 with "
+            "a job_id immediately — poll GET /v1/jobs/{job_id}."
+        ),
+    )
+
+    prompt: str = Field(
+        ...,
+        min_length=1,
+        description="Natural-language instruction describing the edit (required).",
+    )
+    negative_prompt: str | None = Field(
+        default=None,
+        description="Optional text describing what to avoid in the result.",
+    )
+    images: list[FileRef] = Field(
+        ...,
+        min_length=1,
+        description=(
+            "One or more reference images (Files-API file ids, http(s) URLs, or data "
+            "URLs) to edit / compose under the prompt. At least one is required."
+        ),
+    )
+
+    width: int | None = Field(
+        default=None,
+        description=(
+            "Output width in pixels. Omit for the server default (1024). Must be a "
+            "multiple of 16 and at most 2048."
+        ),
+    )
+    height: int | None = Field(
+        default=None,
+        description=(
+            "Output height in pixels. Omit for the server default (1024). Must be a "
+            "multiple of 16 and at most 2048."
+        ),
+    )
+    steps: int | None = Field(
+        default=None,
+        ge=1,
+        description=(
+            "Number of denoising steps (1..100). Omit for the server default (30). "
+            "More steps = slower, sometimes higher quality."
+        ),
+    )
+    guidance: float | None = Field(
+        default=None,
+        description=(
+            "Classifier-free guidance scale. Omit for the server default (2.5); "
+            "higher follows the prompt more strictly."
+        ),
+    )
+    seed: int | None = Field(
+        default=None,
+        description=(
+            "Random seed for reproducibility. Omit for a random seed (the resolved "
+            "seed is recorded in the result `params`)."
+        ),
+    )
+    quantize: int | None = Field(
+        default=None,
+        description=(
+            "Quantization bits, one of {3, 4, 5, 6, 8}. Omit to use the resident "
+            "model's quantization (q8). A differing value builds a one-off transient "
+            "model (slower, not reused)."
+        ),
+    )
+    scheduler: str = Field(
+        default="linear",
+        description="Noise scheduler. `linear` is the default and tested value.",
+    )
+
+    format: Literal["png", "jpeg", "webp"] = Field(
+        default="png",
+        description="Output image encoding for the produced file.",
+    )
+    quality: int = Field(
+        default=90,
+        ge=1,
+        le=100,
+        description="Encoder quality 1..100 (used for jpeg/webp; ignored for png).",
+    )
+
+    loras: list[LoraRef] = Field(
+        default_factory=list,
+        description=(
+            "Up to 4 LoRA adapters [{file, scale}] referencing Files-API ids. Any "
+            "lora forces a one-off transient model (slower, not reused)."
+        ),
+    )
+
+    def gen_params(self) -> dict:
+        return {
+            "prompt": self.prompt,
+            "negative_prompt": self.negative_prompt,
+            "images": [image.model_dump(mode="json") for image in self.images],
+            "width": self.width,
+            "height": self.height,
+            "steps": self.steps,
+            "guidance": self.guidance,
+            "seed": self.seed,
+            "quantize": self.quantize,
+            "scheduler": self.scheduler,
+            "format": self.format,
+            "quality": self.quality,
+            "loras": [lr.model_dump() for lr in self.loras],
+        }

kiapi/capabilities/qwen/_views/generate_params.py

@@ -0,0 +1,37 @@
+"""The complete contract for one Qwen Image generate run.
+
+Built from settings + request by ``resolve_generate_params``; the model needs
+nothing else to produce the image and its metadata. ``kind`` is ``img2img`` when
+``image_path`` is set (resolved from ``init_image_file_id``), else ``txt2img``;
+``image_path`` is kept out of the recorded metadata in favour of the file id.
+"""
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+from .._schemas.lora_ref import LoraRef
+
+
+class GenerateParams(BaseModel):
+    kind: Literal["txt2img", "img2img"]
+    model: str
+
+    prompt: str
+    negative_prompt: str | None
+    init_image_file_id: str | None
+    image_path: str | None
+    image_strength: float | None
+
+    seed: int
+    width: int
+    height: int
+    steps: int
+    guidance: float
+    quantize: int | None
+    scheduler: str
+
+    format: Literal["png", "jpeg", "webp"]
+    quality: int
+
+    loras: list[LoraRef]

kiapi/capabilities/qwen/_views/generate_request.py

@@ -0,0 +1,149 @@
+"""Qwen Image generate request model. txt2img, or img2img when init_image is set.
+
+One endpoint serves both sync and async via ``mode``. ``init_image`` is optional:
+when present ``/generate`` runs img2img, otherwise txt2img. Defaults for
+``width`` / ``height`` / ``steps`` / ``guidance`` / ``quantize`` are resolved
+server-side when omitted. A ``quantize`` override or any ``loras`` builds a
+one-off transient model (slower, not reused).
+"""
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from kiapi.core.file import FileRef
+
+from .._schemas.lora_ref import LoraRef
+
+
+class GenerateRequest(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    model: str | None = Field(
+        default=None,
+        description=(
+            "Model variant (see GET /v1/image/qwen/models). Omit for the default "
+            "`image`; `/generate` only accepts `image` (use `/edit` for `edit-2509`)."
+        ),
+    )
+    mode: Literal["sync", "async"] = Field(
+        default="sync",
+        description=(
+            "`sync` waits for the image (504 on timeout); `async` returns 202 with "
+            "a job_id immediately — poll GET /v1/jobs/{job_id}."
+        ),
+    )
+
+    prompt: str = Field(
+        ...,
+        min_length=1,
+        description="Text prompt describing the image to generate (required).",
+    )
+    negative_prompt: str | None = Field(
+        default=None,
+        description="Optional text describing what to avoid in the image.",
+    )
+    init_image: FileRef | None = Field(
+        default=None,
+        description=(
+            "Optional input image (Files-API file id, http(s) URL, or data URL). "
+            "When set, `/generate` runs img2img seeded from this image; omit for "
+            "plain txt2img."
+        ),
+    )
+    image_strength: float | None = Field(
+        default=None,
+        description=(
+            "img2img only: how much the `init_image` is preserved, in 0..1. Lower "
+            "keeps more of the input; higher follows the prompt more freely. "
+            "Ignored when `init_image` is absent."
+        ),
+    )
+
+    width: int | None = Field(
+        default=None,
+        description=(
+            "Output width in pixels. Omit for the server default (1024). Must be a "
+            "multiple of 16 and at most 2048."
+        ),
+    )
+    height: int | None = Field(
+        default=None,
+        description=(
+            "Output height in pixels. Omit for the server default (1024). Must be a "
+            "multiple of 16 and at most 2048."
+        ),
+    )
+    steps: int | None = Field(
+        default=None,
+        ge=1,
+        description=(
+            "Number of denoising steps (1..100). Omit for the server default (30). "
+            "More steps = slower, sometimes higher quality."
+        ),
+    )
+    guidance: float | None = Field(
+        default=None,
+        description=(
+            "Classifier-free guidance scale. Omit for the server default (4.0); "
+            "higher follows the prompt more strictly."
+        ),
+    )
+    seed: int | None = Field(
+        default=None,
+        description=(
+            "Random seed for reproducibility. Omit for a random seed (the resolved "
+            "seed is recorded in the result `params`)."
+        ),
+    )
+    quantize: int | None = Field(
+        default=None,
+        description=(
+            "Quantization bits, one of {3, 4, 5, 6, 8}. Omit to use the resident "
+            "model's quantization (q8). A differing value builds a one-off transient "
+            "model (slower, not reused)."
+        ),
+    )
+    scheduler: str = Field(
+        default="linear",
+        description="Noise scheduler. `linear` is the default and tested value.",
+    )
+
+    format: Literal["png", "jpeg", "webp"] = Field(
+        default="png",
+        description="Output image encoding for the produced file.",
+    )
+    quality: int = Field(
+        default=90,
+        ge=1,
+        le=100,
+        description="Encoder quality 1..100 (used for jpeg/webp; ignored for png).",
+    )
+
+    loras: list[LoraRef] = Field(
+        default_factory=list,
+        description=(
+            "Up to 4 LoRA adapters [{file, scale}] referencing Files-API ids. Any "
+            "lora forces a one-off transient model (slower, not reused)."
+        ),
+    )
+
+    def gen_params(self) -> dict:
+        return {
+            "prompt": self.prompt,
+            "negative_prompt": self.negative_prompt,
+            "init_image": self.init_image.model_dump(mode="json")
+            if self.init_image is not None
+            else None,
+            "image_strength": self.image_strength,
+            "width": self.width,
+            "height": self.height,
+            "steps": self.steps,
+            "guidance": self.guidance,
+            "seed": self.seed,
+            "quantize": self.quantize,
+            "scheduler": self.scheduler,
+            "format": self.format,
+            "quality": self.quality,
+            "loras": [lr.model_dump() for lr in self.loras],
+        }