kcai-data-sampling-lama 0.1.0__tar.gz

kcai_data_sampling_lama-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: kcai-data-sampling-lama
+Version: 0.1.0
+Summary: Generative inpaint transformation (LaMa) and the associated tool-model plugin for kcai data-sampling
+Author-email: Safenai <support@safenai.io>
+License-Expression: Apache-2.0
+Keywords: ml,data,augmentation,robustness,images,inpainting
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: torch>=2.0.0
+Requires-Dist: kcai-data-sampling-core
+
+# kcai-data-sampling-lama
+
+The **generative** slot of kcai data-sampling: transformations where a model
+*produces* the output. Here the model is a **tool** — it fills in content that
+was not in the source sample, so the family's defining property is that the
+output is genuinely new rather than a rearrangement of the input.
+
+This package implements inpainting with
+[LaMa](https://github.com/advimman/lama) (Suvorov et al., WACV 2022) as a tool
+model, and exposes it through two entry-point groups: `inpaint` under
+`kcai_data_sampling.transformations`, and `lama_inpaint` under
+`kcai_data_sampling.models`.
+
+A tool model declares `model_role = "tool"`, which is what makes the framework
+treat it as generative. The map is deterministic — no randomness is drawn, so
+the recorded seed is `None` — and not reversible, because what was in the filled
+region is gone.
+
+## What it ships today
+
+- `inpaint` — one method: erase a rectangular region and let the model refill it.
+- `lama_inpaint` — the LaMa tool model behind it.
+
+One method, as an example of the slot rather than a catalogue.
+
+## Install
+
+```bash
+pip install "kcai-data-sampling[lama]"
+```
+
+**This is the package that brings torch.** It is the only one of the
+transformation packages that depends on a deep-learning framework, so an install
+that does not ask for it stays torch-free. `torch` is imported lazily — importing
+this package does not itself require torch — and the checkpoint is a weights
+file fetched at run time, not a dependency.
+
+The released *big-lama* TorchScript checkpoint (~200 MB) is downloaded into the
+weight cache on first use, from the upstream release. The cache is
+`$KCAI_WEIGHTS_DIR` when that is set; otherwise `.cache/` beside the working
+directory — inside a checkout that resolves to the repository's own `.cache/`.
+Checkpoints are never committed.
+
+## Example
+
+The `models` and `operations` sections of a job configuration:
+
+```yaml
+models:
+  lama:
+    type: lama_inpaint
+    weights: big-lama.pt
+    params: { margin: 256 }
+operations:
+  transformations:
+    - name: inpaint
+      type: inpaint
+      tool_model: lama
+      top: 350
+      left: 700
+      height: 300
+      width: 500
+```
+
+The transformation names its model with `tool_model: lama`, referring to the
+key under `models:`. `top`/`left`/`height`/`width` describe the rectangle to
+erase; the window must fit inside the frame, which is only knowable at run time,
+so a window that would leave it is refused rather than silently wrapped.
+`margin` is how many pixels of surrounding context are cropped around the mask
+for the network.
+
+Only the channels the network consumes are sent to it — three, RGB — so the
+alpha plane of an RGBA batch is passed through untouched.
+
+## Bring your own model
+
+Any object reachable through a `kcai_data_sampling.models` entry point is a
+model, exactly like a transformation. To use a custom inference routine, ship a
+small importable package that registers your adapter under that entry-point group
+and lets it declare its own dependencies (`torch`, your inference library) in its
+own metadata. They never belong to the core contracts or to the job package.
+A classic-sketch adapter to paste into your package:
+
+```python
+class MyModel:
+    channels = 3  # RGB only: the adapter receives exactly those planes
+
+    def __init__(self, weights: str, **params):
+        self.name = weights  # the ledger records this string
+        self._load(weights, **params)
+
+    def inpaint(self, xs, masks):
+        """(B, H, W, C) uint8 image batch in, (B, H, W, C) uint8 out."""
+        ...  # fill every masked pixel; leave the rest unchanged
+
+
+def plugin() -> MyModel:
+    return MyModel
+```
+
+and point `[project.entry-points."kcai_data_sampling.models"]` at it (e.g.
+`mymodel = "my_package.models:plugin"`). A tool model is recognised by a
+non-empty `name` plus an `inpaint` method, and conformance is checked against
+the `tool` role the transformation declares.
+
+Known-architecture custom weights need no code at all: keep `type: lama_inpaint`
+and set `weights` to your own checkpoint file.

kcai_data_sampling_lama-0.1.0/README.md

@@ -0,0 +1,107 @@
+# kcai-data-sampling-lama
+
+The **generative** slot of kcai data-sampling: transformations where a model
+*produces* the output. Here the model is a **tool** — it fills in content that
+was not in the source sample, so the family's defining property is that the
+output is genuinely new rather than a rearrangement of the input.
+
+This package implements inpainting with
+[LaMa](https://github.com/advimman/lama) (Suvorov et al., WACV 2022) as a tool
+model, and exposes it through two entry-point groups: `inpaint` under
+`kcai_data_sampling.transformations`, and `lama_inpaint` under
+`kcai_data_sampling.models`.
+
+A tool model declares `model_role = "tool"`, which is what makes the framework
+treat it as generative. The map is deterministic — no randomness is drawn, so
+the recorded seed is `None` — and not reversible, because what was in the filled
+region is gone.
+
+## What it ships today
+
+- `inpaint` — one method: erase a rectangular region and let the model refill it.
+- `lama_inpaint` — the LaMa tool model behind it.
+
+One method, as an example of the slot rather than a catalogue.
+
+## Install
+
+```bash
+pip install "kcai-data-sampling[lama]"
+```
+
+**This is the package that brings torch.** It is the only one of the
+transformation packages that depends on a deep-learning framework, so an install
+that does not ask for it stays torch-free. `torch` is imported lazily — importing
+this package does not itself require torch — and the checkpoint is a weights
+file fetched at run time, not a dependency.
+
+The released *big-lama* TorchScript checkpoint (~200 MB) is downloaded into the
+weight cache on first use, from the upstream release. The cache is
+`$KCAI_WEIGHTS_DIR` when that is set; otherwise `.cache/` beside the working
+directory — inside a checkout that resolves to the repository's own `.cache/`.
+Checkpoints are never committed.
+
+## Example
+
+The `models` and `operations` sections of a job configuration:
+
+```yaml
+models:
+  lama:
+    type: lama_inpaint
+    weights: big-lama.pt
+    params: { margin: 256 }
+operations:
+  transformations:
+    - name: inpaint
+      type: inpaint
+      tool_model: lama
+      top: 350
+      left: 700
+      height: 300
+      width: 500
+```
+
+The transformation names its model with `tool_model: lama`, referring to the
+key under `models:`. `top`/`left`/`height`/`width` describe the rectangle to
+erase; the window must fit inside the frame, which is only knowable at run time,
+so a window that would leave it is refused rather than silently wrapped.
+`margin` is how many pixels of surrounding context are cropped around the mask
+for the network.
+
+Only the channels the network consumes are sent to it — three, RGB — so the
+alpha plane of an RGBA batch is passed through untouched.
+
+## Bring your own model
+
+Any object reachable through a `kcai_data_sampling.models` entry point is a
+model, exactly like a transformation. To use a custom inference routine, ship a
+small importable package that registers your adapter under that entry-point group
+and lets it declare its own dependencies (`torch`, your inference library) in its
+own metadata. They never belong to the core contracts or to the job package.
+A classic-sketch adapter to paste into your package:
+
+```python
+class MyModel:
+    channels = 3  # RGB only: the adapter receives exactly those planes
+
+    def __init__(self, weights: str, **params):
+        self.name = weights  # the ledger records this string
+        self._load(weights, **params)
+
+    def inpaint(self, xs, masks):
+        """(B, H, W, C) uint8 image batch in, (B, H, W, C) uint8 out."""
+        ...  # fill every masked pixel; leave the rest unchanged
+
+
+def plugin() -> MyModel:
+    return MyModel
+```
+
+and point `[project.entry-points."kcai_data_sampling.models"]` at it (e.g.
+`mymodel = "my_package.models:plugin"`). A tool model is recognised by a
+non-empty `name` plus an `inpaint` method, and conformance is checked against
+the `tool` role the transformation declares.
+
+Known-architecture custom weights need no code at all: keep `type: lama_inpaint`
+and set `weights` to your own checkpoint file.

kcai_data_sampling_lama-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "kcai-data-sampling-lama"
+dynamic = ["dependencies", "version"]
+description = "Generative inpaint transformation (LaMa) and the associated tool-model plugin for kcai data-sampling"
+authors = [
+  {name = "Safenai", email = "support@safenai.io"},
+]
+license = "Apache-2.0"
+readme = "README.md"
+requires-python = ">=3.11"
+keywords = ["ml", "data", "augmentation", "robustness", "images", "inpainting"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+[project.entry-points."kcai_data_sampling.transformations"]
+inpaint = "kcai_data_sampling_lama.api.transformations.inpaint:Inpaint"
+
+[project.entry-points."kcai_data_sampling.models"]
+lama_inpaint = "kcai_data_sampling_lama.api.models.lama:LamaTool"
+
+[build-system]
+requires = ["setuptools>=80", "setuptools-scm[simple]>=8"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools_scm]
+version_file = "src/kcai_data_sampling_lama/_version_.py"
+root = "../.."
+fallback_version = "0.0.1"
+
+[tool.setuptools.dynamic]
+dependencies = {file = ["requirements.txt"]}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+kcai_data_sampling_lama = ["py.typed"]

kcai_data_sampling_lama-0.1.0/requirements.txt

@@ -0,0 +1,2 @@
+torch>=2.0.0
+kcai-data-sampling-core

kcai_data_sampling_lama-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kcai_data_sampling_lama-0.1.0/src/kcai_data_sampling_lama/__init__.py

@@ -0,0 +1,12 @@
+"""Generative inpainting with LaMa.
+
+Ships the ``inpaint`` transformation and its ``lama_inpaint`` tool model: the
+transformation erases a rectangle of each image and a LaMa artifact fills the
+hole with content that was not in the image. The transformation class lives
+under ``api/transformations/``, the model under ``api/models/``, and the pure
+mask math under ``transformations/``. ``torch`` is needed only here; the
+checkpoint downloads into the weight cache (``$KCAI_WEIGHTS_DIR`` or the
+repository's ``.cache/``) on first use.
+"""
+
+from kcai_data_sampling_lama._version_ import __version__ as __version__

kcai_data_sampling_lama-0.1.0/src/kcai_data_sampling_lama/_version_.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

kcai_data_sampling_lama-0.1.0/src/kcai_data_sampling_lama/api/__init__.py

@@ -0,0 +1,9 @@
+"""Model and transformation subclasses owned by this package.
+
+The generic contracts live in ``kcai_data_sampling_core.api``; this package
+holds its own model adapter (``api/models/``) and its own transformation class
+(``api/transformations/``), each implementing the generic core contract for
+the LaMa inpainting tool. Nothing here reads or writes images: batches flow in
+as ``(B, H, W, 4)`` uint8 RGBA arrays and the only disk I/O in the package is
+the weight cache.
+"""

kcai_data_sampling_lama-0.1.0/src/kcai_data_sampling_lama/api/models/__init__.py

@@ -0,0 +1,10 @@
+"""Tool-model adapters for this package.
+
+Adapters implement the generic ``ToolModel`` protocol from
+``kcai_data_sampling_core.api.roles``; the LaMa adapter is the package's first
+one. The weight-cache helper lives here too.
+"""
+
+from kcai_data_sampling_lama.api.models.lama import LamaTool
+
+__all__ = ["LamaTool"]

kcai_data_sampling_lama-0.1.0/src/kcai_data_sampling_lama/api/models/lama.py

@@ -0,0 +1,108 @@
+"""LaMa (Suvorov et al., WACV 2022) as a tool model.
+
+Wraps the official *big-lama* TorchScript checkpoint (~200 MB, downloaded into
+the weight cache on first use) behind the ``inpaint(xs, masks)`` tool-model
+contract. ``torch`` is imported lazily so that importing this package never
+requires it; ``big-lama`` itself is a weights file fetched at run time, not a
+dependency.
+"""
+
+import warnings
+
+import numpy as np
+
+from kcai_data_sampling_lama.api.models.weights import fetch
+
+URL = "https://github.com/enesmsahin/simple-lama-inpainting/releases/download/v0.1.0/big-lama.pt"
+
+
+class LamaTool:
+    """The ``inpaint`` tool model backed by LaMa.
+
+    Attributes:
+        name: The checkpoint's file stem (``"big-lama"``), recorded on every
+            output row.
+        weights: The local path of the checkpoint in the weight cache.
+        margin: Pixels of context cropped around the mask union for the network.
+        channels: Image planes the network consumes (``3`` = RGB). The alpha
+            plane of an RGBA batch is then never sent to the network and is
+            returned untouched.
+    """
+
+    channels = 3
+
+    def __init__(self, weights: str = "big-lama.pt", margin: int = 256):
+        """Load the LaMa checkpoint.
+
+        Args:
+            weights: The checkpoint's file name in the weight cache; downloaded
+                from the upstream release on first use.
+            margin: Pixels of context cropped around the mask union for the
+                network (sides are padded to multiples of 8).
+
+        Raises:
+            ImportError: If ``torch`` is not installed.
+        """
+        import torch
+
+        self._torch = torch
+        self.weights = fetch(weights, URL)
+        self.name = self.weights.stem
+        self.margin = margin
+        with warnings.catch_warnings():  # TorchScript checkpoint; torch >= 2.9 deprecates jit.load
+            warnings.simplefilter("ignore", FutureWarning)
+            self.net = torch.jit.load(str(self.weights), map_location="cpu").eval()
+
+    def inpaint(self, xs: np.ndarray, masks: np.ndarray) -> np.ndarray:
+        """Fill every masked pixel with network output, leave the rest untouched.
+
+        The ``(B, H, W, 4)`` uint8 RGBA batch is converted to the network's
+        NCHW float input (the ``channels`` first planes, in ``[0, 1]``) and back.
+        The network runs once, on a crop around the union of the masks plus
+        ``margin`` pixels of context (sides padded to multiples of 8); only the
+        masked pixels of the selected planes are rewritten.
+
+        Args:
+            xs: Batch of image arrays shaped ``(B, H, W, 4)``, uint8 RGBA.
+            masks: One boolean mask per sample ``(B, H, W)``; True = erase and fill in.
+
+        Returns:
+            A batch of the same shape, uint8 in ``[0, 255]``. Unmasked pixels
+            and (when ``channels`` is 3) the whole alpha plane are exactly as
+            in ``xs``.
+
+        Raises:
+            ValueError: If ``xs`` does not carry at least ``channels`` planes.
+        """
+        if xs.ndim != 4 or xs.shape[-1] < self.channels:
+            raise ValueError(f"LamaTool.inpaint expects a (B, H, W, 4) uint8 RGBA batch, got shape {xs.shape}")
+        rows, cols = np.where(masks.any(axis=0))
+        if rows.size == 0:
+            return xs.copy()
+        h, w = masks.shape[-2:]
+        top, bottom = max(rows.min() - self.margin, 0), min(rows.max() + 1 + self.margin, h)
+        left, right = max(cols.min() - self.margin, 0), min(cols.max() + 1 + self.margin, w)
+        pad_h, pad_w = (-(bottom - top)) % 8, (-(right - left)) % 8
+
+        image = np.pad(
+            xs[:, top:bottom, left:right, : self.channels],
+            ((0, 0), (0, pad_h), (0, pad_w), (0, 0)),
+            mode="symmetric",
+        )
+        image = image.astype("float32").transpose(0, 3, 1, 2) / 255.0
+        hole = np.pad(
+            masks[:, top:bottom, left:right],
+            ((0, 0), (0, pad_h), (0, pad_w)),
+            mode="symmetric",
+        ).astype("float32")
+        torch = self._torch
+        with torch.inference_mode():
+            out = self.net(torch.from_numpy(image), torch.from_numpy(hole)[:, None])
+        filled = out[:, :, : bottom - top, : right - left].numpy()
+
+        result = xs.copy()
+        region = result[:, top:bottom, left:right, : self.channels]
+        hole_pixels = np.broadcast_to(masks[:, top:bottom, left:right, None], region.shape)
+        filled_pixels = np.transpose(filled, (0, 2, 3, 1))[hole_pixels]
+        region[hole_pixels] = np.clip(filled_pixels * 255.0, 0.0, 255.0).astype(np.uint8)
+        return result

kcai_data_sampling_lama-0.1.0/src/kcai_data_sampling_lama/api/models/weights.py

@@ -0,0 +1,56 @@
+"""Where model checkpoints live: ``$KCAI_WEIGHTS_DIR`` or the repository's ``.cache/``.
+
+The default cache directory is the repo-relative ``.cache/`` (discovered by
+walking up from the working directory to the nearest ancestor that contains a
+``.git`` directory, falling back to the working directory), so a checkout's
+checkpoints stay together with its code. ``$KCAI_WEIGHTS_DIR`` overrides it for
+shared or pre-fetched caches.
+"""
+
+import os
+from pathlib import Path
+import urllib.request
+
+
+def weights_path(name: str) -> Path:
+    """The cache path of a checkpoint, creating the directory if needed.
+
+    Args:
+        name: The checkpoint's file name inside the cache directory.
+
+    Returns:
+        The absolute path where the checkpoint is (or will be) cached.
+    """
+    directory = Path(os.environ.get("KCAI_WEIGHTS_DIR", _default_cache_dir()))
+    directory.mkdir(parents=True, exist_ok=True)
+    return directory / name
+
+
+def fetch(name: str, url: str) -> Path:
+    """The checkpoint's path, downloaded from ``url`` on first use.
+
+    Args:
+        name: The checkpoint's file name inside the cache directory.
+        url: The remote location to download from when the file is missing.
+
+    Returns:
+        The path the checkpoint was cached at.
+    """
+    path = weights_path(name)
+    if not path.exists():
+        urllib.request.urlretrieve(url, path)
+    return path
+
+
+def _default_cache_dir() -> Path:
+    """The repository root's ``.cache/`` (nearest ancestor with a ``.git`` dir).
+
+    Returns:
+        ``<repo root>/.cache``, or ``<cwd>/.cache`` when no ancestor has a
+        ``.git`` directory.
+    """
+    cwd = Path.cwd()
+    for candidate in (cwd, *cwd.parents):
+        if (candidate / ".git").exists():
+            return candidate / ".cache"
+    return cwd / ".cache"

kcai_data_sampling_lama-0.1.0/src/kcai_data_sampling_lama/api/transformations/__init__.py

@@ -0,0 +1,12 @@
+"""Unary transformation classes in this package.
+
+The generic core contract lives in ``kcai_data_sampling_core.api``; the class
+here (``api.transformations.inpaint.Inpaint``) is the package's own subclass,
+wrapping a pure algorithm function from
+``kcai_data_sampling_lama.transformations`` into the unary ``apply``
+contract.
+"""
+
+from kcai_data_sampling_lama.api.transformations.inpaint import Inpaint
+
+__all__ = ["Inpaint"]

kcai_data_sampling_lama-0.1.0/src/kcai_data_sampling_lama/api/transformations/inpaint.py

@@ -0,0 +1,65 @@
+"""The ``inpaint`` transformation class.
+
+Wraps the region-mask math
+(:func:`kcai_data_sampling_lama.transformations.inpaint.build_region_mask`)
+into the unary transformation contract: each sample's window is erased and the
+tool model fills it with content that was not in the image.
+"""
+
+from kcai_data_sampling_core.api.roles import check_output
+from kcai_data_sampling_core.api.unary import UnaryTransformation
+import numpy as np
+from typing_extensions import override
+
+from kcai_data_sampling_lama.configs import InpaintTransformationConfig
+from kcai_data_sampling_lama.transformations.inpaint import build_region_mask
+
+
+class Inpaint(UnaryTransformation):
+    """Erase a rectangle of each image and let a tool model fill it in.
+
+    ``top``/``left`` default to 0; ``height``/``width`` are required (a
+    degenerate empty region is refused). The replacement is invented by the
+    ``tool_model``, so the map is not reversible: what was in the region is
+    gone. ``apply`` is deterministic (``stochastic`` not set), so the seed
+    records ``None``.
+    """
+
+    algorithm = "inpaint"
+
+    #: The registered config schema this algorithm validates against.
+    Config = InpaintTransformationConfig
+
+    #: The model slot this algorithm fills, and the methods it must expose.
+    model_role = "tool"
+    model_methods = ("inpaint",)
+
+    @override
+    def apply(
+        self,
+        xs: np.ndarray,  # (b, h, w, c) uint8
+        rngs: list[np.random.Generator] | None = None,
+    ) -> np.ndarray:
+        """Erase the configured rectangle and fill it via the tool model.
+
+        Args:
+            xs: Batch of image arrays shaped ``(B, H, W, C)``.
+            rngs: Unused for this deterministic operation.
+
+        Returns:
+            A batch of the same shape; the masked rectangle is rewritten from
+            the tool model's output, every other pixel returns untouched.
+
+        Raises:
+            ValueError: If the region leaves the frame, or the tool model's
+                output breaks the numeric contract.
+        """
+        del rngs
+        masks = build_region_mask(xs.shape, **self.params)
+        return check_output(
+            self.algorithm,
+            self.tool_model,
+            "inpaint",
+            xs,
+            self.tool_model.inpaint(xs, masks),
+        )

kcai_data_sampling_lama-0.1.0/src/kcai_data_sampling_lama/configs.py

@@ -0,0 +1,72 @@
+"""Per-algorithm config schemas for the inpaint transformation.
+
+The schema subclasses the core base ``TransformationConfig`` and pins ``type``
+to the algorithm's literal, so the registry-resolved validator in ``JobConfig``
+picks it by `type`. A parameter that can sweep accepts ``SweepConfig``; the
+ranges the algorithm allows are enforced here, on both the plain value and the
+sweep interval (``top``/``left`` within ``[0, +oo)``, ``height``/``width``
+within ``(0, +oo)``). ``tool_model`` names a model from the ``models:`` section
+of the job config; the CLI resolves the name to an instance.
+"""
+
+from typing import Literal, Self
+
+from kcai_data_sampling_core.models.config import TransformationConfig
+from kcai_data_sampling_core.models.sweep import SweepConfig
+from pydantic import Field, model_validator
+
+
+class InpaintTransformationConfig(TransformationConfig):
+    """Configuration of the ``inpaint`` transformation.
+
+    Attributes:
+        tool_model: Name of a tool model from the job's ``models:`` section;
+            the CLI resolves it to an instance. Optional here because the
+            transformation base consumes it before re-validating the remaining
+            parameters against this schema; a model-role transformation without
+            one is refused loudly at construction (the slot check).
+        top: Region top offset in pixels (default 0), or a sweep (its interval
+            must be ``>= 0``).
+        left: Region left offset in pixels (default 0), or a sweep (its
+            interval must be ``>= 0``).
+        height: Region height in pixels; required (a degenerate empty region is
+            refused), or a sweep (its interval must be ``> 0``).
+        width: Region width in pixels; required (a degenerate empty region is
+            refused), or a sweep (its interval must be ``> 0``).
+    """
+
+    type: Literal["inpaint"] = "inpaint"
+    tool_model: str | None = Field(
+        default=None,
+        exclude=True,
+        description="Name of a tool model from the job's models: section; excluded"
+        " from the resolved parameters (the base consumes it before validation).",
+    )
+    top: int | SweepConfig = Field(
+        default=0,
+        description="Region top offset in pixels; a SweepConfig expands it.",
+    )
+    left: int | SweepConfig = Field(
+        default=0,
+        description="Region left offset in pixels; a SweepConfig expands it.",
+    )
+    height: int | SweepConfig = Field(description="Region height in pixels; a SweepConfig expands it.")
+    width: int | SweepConfig = Field(description="Region width in pixels; a SweepConfig expands it.")
+
+    @model_validator(mode="after")
+    def _parameter_bounds(self) -> Self:
+        """Enforce each parameter's algorithm range on the value or the sweep.
+
+        Returns:
+            The validated config.
+
+        Raises:
+            ValueError: If ``top``/``left`` go below ``0`` or
+                ``height``/``width`` do not stay positive, whether given
+                directly or as a sweep interval.
+        """
+        for name in ("top", "left"):
+            self._check_parameter_bounds(name, minimum=0)
+        for name in ("height", "width"):
+            self._check_parameter_bounds(name, minimum=0, exclusive_min=True)
+        return self

kcai_data_sampling_lama-0.1.0/src/kcai_data_sampling_lama/transformations/__init__.py

@@ -0,0 +1,11 @@
+"""Transformation math functions for this package.
+
+The module-level function here (``transformations.inpaint.build_region_mask``)
+is the pure mask math; the transformation class that wraps it into the unary
+contract lives in ``kcai_data_sampling_lama.api.transformations``. All
+batches share the RGBA-U8 array convention ``(B, H, W, 4) uint8``.
+"""
+
+from kcai_data_sampling_lama.transformations.inpaint import build_region_mask
+
+__all__ = ["build_region_mask"]

kcai_data_sampling_lama-0.1.0/src/kcai_data_sampling_lama/transformations/inpaint.py

@@ -0,0 +1,50 @@
+"""Inpainting: generate a region fill — the mask math.
+
+``build_region_mask`` is the pure function that marks the rectangle a tool
+model should erase and refill; the transformation class that wraps it into the
+unary contract lives in ``kcai_data_sampling_lama.api.transformations.inpaint``.
+"""
+
+import numpy as np
+
+
+def build_region_mask(
+    xs_shape: tuple[int, ...],
+    top: int,
+    left: int,
+    height: int,
+    width: int,
+) -> np.ndarray:
+    """The boolean ``(B, H, W)`` mask of the rectangle to erase.
+
+    ``True`` marks every pixel of the ``top:top+height`` by
+    ``left:left+width`` window of each sample. The window must fit inside the
+    frame: the frame size is only known at run time (from the ``(H, W)`` axes
+    of ``xs_shape``), so this check is apply-time, and it refuses out-of-frame
+    windows loudly instead of silently wrapping.
+
+    Args:
+        xs_shape: The batch shape ``(B, H, W, C)``; the frame is read from the
+            ``(H, W)`` axes.
+        top: Window top offset in pixels, ``>= 0``.
+        left: Window left offset in pixels, ``>= 0``.
+        height: Window height in pixels, ``> 0``.
+        width: Window width in pixels, ``> 0``.
+
+    Returns:
+        A boolean ``(B, H, W)`` array; ``True`` inside the window.
+
+    Raises:
+        ValueError: If ``top``/``left`` are negative or ``height``/``width``
+            are not positive, or if the window leaves the frame.
+    """
+    if top < 0 or left < 0 or height <= 0 or width <= 0:
+        raise ValueError(
+            f"inpaint region needs top/left >= 0 and height/width > 0, got {top=}, {left=}, {height=}, {width=}"
+        )
+    frame_h, frame_w = int(xs_shape[1]), int(xs_shape[2])
+    if top + height > frame_h or left + width > frame_w:
+        raise ValueError(f"inpaint region {height}x{width} at ({top},{left}) leaves the {frame_h}x{frame_w} frame")
+    masks = np.zeros((int(xs_shape[0]), frame_h, frame_w), dtype=bool)
+    masks[:, top : top + height, left : left + width] = True
+    return masks

kcai_data_sampling_lama-0.1.0/src/kcai_data_sampling_lama.egg-info/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: kcai-data-sampling-lama
+Version: 0.1.0
+Summary: Generative inpaint transformation (LaMa) and the associated tool-model plugin for kcai data-sampling
+Author-email: Safenai <support@safenai.io>
+License-Expression: Apache-2.0
+Keywords: ml,data,augmentation,robustness,images,inpainting
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: torch>=2.0.0
+Requires-Dist: kcai-data-sampling-core
+
+# kcai-data-sampling-lama
+
+The **generative** slot of kcai data-sampling: transformations where a model
+*produces* the output. Here the model is a **tool** — it fills in content that
+was not in the source sample, so the family's defining property is that the
+output is genuinely new rather than a rearrangement of the input.
+
+This package implements inpainting with
+[LaMa](https://github.com/advimman/lama) (Suvorov et al., WACV 2022) as a tool
+model, and exposes it through two entry-point groups: `inpaint` under
+`kcai_data_sampling.transformations`, and `lama_inpaint` under
+`kcai_data_sampling.models`.
+
+A tool model declares `model_role = "tool"`, which is what makes the framework
+treat it as generative. The map is deterministic — no randomness is drawn, so
+the recorded seed is `None` — and not reversible, because what was in the filled
+region is gone.
+
+## What it ships today
+
+- `inpaint` — one method: erase a rectangular region and let the model refill it.
+- `lama_inpaint` — the LaMa tool model behind it.
+
+One method, as an example of the slot rather than a catalogue.
+
+## Install
+
+```bash
+pip install "kcai-data-sampling[lama]"
+```
+
+**This is the package that brings torch.** It is the only one of the
+transformation packages that depends on a deep-learning framework, so an install
+that does not ask for it stays torch-free. `torch` is imported lazily — importing
+this package does not itself require torch — and the checkpoint is a weights
+file fetched at run time, not a dependency.
+
+The released *big-lama* TorchScript checkpoint (~200 MB) is downloaded into the
+weight cache on first use, from the upstream release. The cache is
+`$KCAI_WEIGHTS_DIR` when that is set; otherwise `.cache/` beside the working
+directory — inside a checkout that resolves to the repository's own `.cache/`.
+Checkpoints are never committed.
+
+## Example
+
+The `models` and `operations` sections of a job configuration:
+
+```yaml
+models:
+  lama:
+    type: lama_inpaint
+    weights: big-lama.pt
+    params: { margin: 256 }
+operations:
+  transformations:
+    - name: inpaint
+      type: inpaint
+      tool_model: lama
+      top: 350
+      left: 700
+      height: 300
+      width: 500
+```
+
+The transformation names its model with `tool_model: lama`, referring to the
+key under `models:`. `top`/`left`/`height`/`width` describe the rectangle to
+erase; the window must fit inside the frame, which is only knowable at run time,
+so a window that would leave it is refused rather than silently wrapped.
+`margin` is how many pixels of surrounding context are cropped around the mask
+for the network.
+
+Only the channels the network consumes are sent to it — three, RGB — so the
+alpha plane of an RGBA batch is passed through untouched.
+
+## Bring your own model
+
+Any object reachable through a `kcai_data_sampling.models` entry point is a
+model, exactly like a transformation. To use a custom inference routine, ship a
+small importable package that registers your adapter under that entry-point group
+and lets it declare its own dependencies (`torch`, your inference library) in its
+own metadata. They never belong to the core contracts or to the job package.
+A classic-sketch adapter to paste into your package:
+
+```python
+class MyModel:
+    channels = 3  # RGB only: the adapter receives exactly those planes
+
+    def __init__(self, weights: str, **params):
+        self.name = weights  # the ledger records this string
+        self._load(weights, **params)
+
+    def inpaint(self, xs, masks):
+        """(B, H, W, C) uint8 image batch in, (B, H, W, C) uint8 out."""
+        ...  # fill every masked pixel; leave the rest unchanged
+
+
+def plugin() -> MyModel:
+    return MyModel
+```
+
+and point `[project.entry-points."kcai_data_sampling.models"]` at it (e.g.
+`mymodel = "my_package.models:plugin"`). A tool model is recognised by a
+non-empty `name` plus an `inpaint` method, and conformance is checked against
+the `tool` role the transformation declares.
+
+Known-architecture custom weights need no code at all: keep `type: lama_inpaint`
+and set `weights` to your own checkpoint file.

kcai_data_sampling_lama-0.1.0/src/kcai_data_sampling_lama.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+README.md
+pyproject.toml
+requirements.txt
+src/kcai_data_sampling_lama/__init__.py
+src/kcai_data_sampling_lama/_version_.py
+src/kcai_data_sampling_lama/configs.py
+src/kcai_data_sampling_lama/py.typed
+src/kcai_data_sampling_lama.egg-info/PKG-INFO
+src/kcai_data_sampling_lama.egg-info/SOURCES.txt
+src/kcai_data_sampling_lama.egg-info/dependency_links.txt
+src/kcai_data_sampling_lama.egg-info/entry_points.txt
+src/kcai_data_sampling_lama.egg-info/requires.txt
+src/kcai_data_sampling_lama.egg-info/scm_file_list.json
+src/kcai_data_sampling_lama.egg-info/top_level.txt
+src/kcai_data_sampling_lama/api/__init__.py
+src/kcai_data_sampling_lama/api/models/__init__.py
+src/kcai_data_sampling_lama/api/models/lama.py
+src/kcai_data_sampling_lama/api/models/weights.py
+src/kcai_data_sampling_lama/api/transformations/__init__.py
+src/kcai_data_sampling_lama/api/transformations/inpaint.py
+src/kcai_data_sampling_lama/transformations/__init__.py
+src/kcai_data_sampling_lama/transformations/inpaint.py

kcai_data_sampling_lama-0.1.0/src/kcai_data_sampling_lama.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

kcai_data_sampling_lama-0.1.0/src/kcai_data_sampling_lama.egg-info/entry_points.txt

@@ -0,0 +1,5 @@
+[kcai_data_sampling.models]
+lama_inpaint = kcai_data_sampling_lama.api.models.lama:LamaTool
+
+[kcai_data_sampling.transformations]
+inpaint = kcai_data_sampling_lama.api.transformations.inpaint:Inpaint

kcai_data_sampling_lama-0.1.0/src/kcai_data_sampling_lama.egg-info/requires.txt

@@ -0,0 +1,2 @@
+torch>=2.0.0
+kcai-data-sampling-core

kcai_data_sampling_lama-0.1.0/src/kcai_data_sampling_lama.egg-info/scm_file_list.json

@@ -0,0 +1,18 @@
+{
+  "files": [
+    "README.md",
+    "pyproject.toml",
+    "requirements.txt",
+    "src/kcai_data_sampling_lama/__init__.py",
+    "src/kcai_data_sampling_lama/api/__init__.py",
+    "src/kcai_data_sampling_lama/api/models/__init__.py",
+    "src/kcai_data_sampling_lama/api/models/lama.py",
+    "src/kcai_data_sampling_lama/api/models/weights.py",
+    "src/kcai_data_sampling_lama/api/transformations/__init__.py",
+    "src/kcai_data_sampling_lama/api/transformations/inpaint.py",
+    "src/kcai_data_sampling_lama/configs.py",
+    "src/kcai_data_sampling_lama/py.typed",
+    "src/kcai_data_sampling_lama/transformations/__init__.py",
+    "src/kcai_data_sampling_lama/transformations/inpaint.py"
+  ]
+}

kcai_data_sampling_lama-0.1.0/src/kcai_data_sampling_lama.egg-info/top_level.txt

@@ -0,0 +1 @@
+kcai_data_sampling_lama