Add request specific preset

Author: ildyria

README.md

@@ -108,6 +108,20 @@ VISION_NSFW_PRESET=strict
 
 Individual tier settings (`VISION_NSFW_BLOCK`, `VISION_NSFW_REVIEW`, `VISION_NSFW_SENSITIVE`) always override the preset, so you can start from a preset and refine from there.
 
+You can also **fine-tune each preset independently** at startup and let callers **select a preset per request**:
+
+```dotenv
+# Raise the confidence bar for the strict preset's block tier
+VISION_NSFW_STRICT__BLOCK__CONFIDENCE=0.9
+
+# Require detections to cover ≥ 5 % of the image for nude_female's review tier
+VISION_NSFW_NUDE_FEMALE__REVIEW__AREA_RATIO=0.05
+```
+
+```json
+{ "photo_id": "42", "photo_path": "2024/01/photo.jpg", "preset": "strict" }
+```
+
 See [Choose a preset](docs/2-how-to/choose-a-preset.md) and [Configure classification tiers](docs/2-how-to/tune-thresholds.md) for details.
 
 ## Environment variables
@@ -131,6 +145,7 @@ All variables are prefixed `VISION_NSFW_`. Copy `.env.example` to `.env` and fil
 | `VISION_NSFW_BLOCK` | _(see defaults)_ | JSON object configuring the block tier. See [Configuration Reference](docs/3-reference/configuration.md). |
 | `VISION_NSFW_REVIEW` | _(see defaults)_ | JSON object configuring the review tier. |
 | `VISION_NSFW_SENSITIVE` | _(see defaults)_ | JSON object configuring the sensitive tier. |
+| `VISION_NSFW_<PRESET>__<TIER>__<FIELD>` | _(none)_ | Per-preset threshold override. Tunes a specific preset in isolation so all presets are ready for per-request selection. Example: `VISION_NSFW_STRICT__BLOCK__CONFIDENCE=0.9`. |
 
 Full reference: [docs/3-reference/configuration.md](docs/3-reference/configuration.md)
 
@@ -154,11 +169,16 @@ Interactive docs: `http://localhost:8000/docs`
 ```json
 {
   "photo_id": "42",
-  "photo_path": "2024/01/photo.jpg"
+  "photo_path": "2024/01/photo.jpg",
+  "preset": "strict"
 }
 ```
 
-`photo_path` is relative to the shared volume root (`VISION_NSFW_PHOTOS_PATH`). The service validates it stays within that root.
+| Field | Required | Description |
+|---|---|---|
+| `photo_id` | Yes | Lychee photo identifier, echoed back in the callback. |
+| `photo_path` | Yes | Path relative to `VISION_NSFW_PHOTOS_PATH`. Validated to stay within that root. |
+| `preset` | No | Override the service-level preset for this job. See [Choose a preset](docs/2-how-to/choose-a-preset.md). |
 
 The endpoint returns **`202 Accepted`** immediately. Results arrive via callback.
 

app/api/routes.py

@@ -90,13 +90,19 @@ async def detect(
         )
         raise HTTPException(status_code=400, detail="photo_path does not exist or is not a file")
 
+    if body.preset is not None:
+        from app.config.presets import PRESETS
+
+        if body.preset not in PRESETS:
+            raise HTTPException(status_code=400, detail=f"Unknown preset {body.preset!r}")
+
     import json
 
     queue: JobQueue = get_queue(request)
     accepted = await queue.enqueue(
         job_type="detect",
         photo_id=body.photo_id,
-        payload=json.dumps({"photo_path": str(resolved)}),
+        payload=json.dumps({"photo_path": str(resolved), "preset": body.preset}),
     )
     if not accepted:
         raise HTTPException(status_code=429, detail="Queue is full — try again later")
@@ -194,21 +200,37 @@ async def _run_detection_job(
     image_path: Path,
     executor: Executor,
     settings: AppSettings,
+    preset_name: str | None = None,
 ) -> None:
     """Classify an image for NSFW content and notify Lychee via callback.
 
     Runs entirely as an async background task after the ``/detect`` route has
     returned 202.  CPU-bound NudeNet inference is offloaded to ``executor`` via
     ``run_in_executor`` so the event loop remains responsive.
+
+    When *preset_name* is given it overrides the service-level label-set
+    configuration for this job only; per-preset env overrides still apply.
     """
-    logger.info("Starting NSFW detection job for photo_id=%s, path=%s", photo_id, image_path)
+    logger.info(
+        "Starting NSFW detection job for photo_id=%s, path=%s, preset=%s",
+        photo_id,
+        image_path,
+        preset_name,
+    )
     try:
         from app.detection.detector import classify, detect_from_path
 
         loop = asyncio.get_running_loop()
 
         raw, w, h = await loop.run_in_executor(executor, detect_from_path, str(image_path))
-        result = classify(raw, w, h, settings)
+
+        if preset_name is not None:
+            block, review, sensitive = settings.resolve_preset(preset_name)
+            effective_settings = settings.model_copy(update={"block": block, "review": review, "sensitive": sensitive})
+        else:
+            effective_settings = settings
+
+        result = classify(raw, w, h, effective_settings)
 
         logger.info(
             "NSFW detection complete for photo_id=%s: should_block=%s, should_review=%s, is_sensitive=%s | "

app/api/schemas.py

@@ -27,6 +27,17 @@ class DetectRequest(BaseModel):
     before opening the file (path-traversal protection).
     """
 
+    preset: str | None = None
+    """Named preset to apply for this specific request.
+
+    When set, overrides the service-level ``VISION_NSFW_PRESET`` / ``VISION_NSFW_BLOCK`` /
+    ``VISION_NSFW_REVIEW`` / ``VISION_NSFW_SENSITIVE`` configuration for this job only.
+    Per-preset env overrides (e.g. ``VISION_NSFW_STRICT__BLOCK__CONFIDENCE``) still apply.
+
+    Valid values: ``strict``, ``moderation``, ``nude_female``, ``permissive``, ``social_media``.
+    Omit (or ``null``) to use the service default.
+    """
+
 
 class BoundingBox(BaseModel):
     """Pixel-space bounding box for a single detection."""

app/config/models.py

@@ -1,5 +1,7 @@
 """Pydantic models for label-set configuration."""
 
+from __future__ import annotations
+
 from pydantic import BaseModel, Field, field_validator, model_validator
 
 from app.config.labels import VALID_LABELS
@@ -56,8 +58,75 @@ def _validate_threshold_keys(cls, value: dict[str, LabelThreshold]) -> dict[str,
         return value
 
     @model_validator(mode="after")
-    def _validate_threshold_keys_subset_of_labels(self) -> "LabelSetConfig":
+    def _validate_threshold_keys_subset_of_labels(self) -> LabelSetConfig:
         orphans = sorted(set(self.label_thresholds.keys()) - set(self.labels))
         if orphans:
             raise ValueError(f"label_thresholds contains labels not present in labels: {orphans}")
         return self
+
+
+class PresetTierOverride(BaseModel):
+    """Optional per-preset threshold/label overrides for one classification tier.
+
+    All fields default to ``None`` / empty, meaning "inherit from the preset definition".
+    Only the fields you set are applied on top of the base preset tier.
+
+    Env var examples (with ``VISION_NSFW_STRICT__`` prefix for the *strict* preset):
+      ``VISION_NSFW_STRICT__BLOCK__CONFIDENCE=0.9``
+      ``VISION_NSFW_STRICT__REVIEW__AREA_RATIO=0.05``
+      ``VISION_NSFW_STRICT__BLOCK__LABELS='["ANUS_EXPOSED"]'``  (replaces preset labels)
+    """
+
+    labels: list[str] | None = None
+    """Replace the preset's label list for this tier.  ``None`` keeps the preset labels."""
+
+    confidence: float | None = Field(default=None, ge=0.0, le=1.0)
+    """Override the per-set confidence threshold.  ``None`` keeps the preset default."""
+
+    area_ratio: float | None = Field(default=None, ge=0.0, le=1.0)
+    """Override the per-set area-ratio threshold.  ``None`` keeps the preset default."""
+
+    label_thresholds: dict[str, LabelThreshold] = {}
+    """Per-label threshold overrides.  Empty dict keeps the preset label_thresholds."""
+
+    @field_validator("labels", mode="after")
+    @classmethod
+    def _validate_labels(cls, value: list[str] | None) -> list[str] | None:
+        if value is None:
+            return value
+        unknown = sorted(set(value) - VALID_LABELS)
+        if unknown:
+            raise ValueError(f"Unknown label(s): {unknown}. Valid labels are: {sorted(VALID_LABELS)}")
+        return value
+
+    @field_validator("label_thresholds", mode="after")
+    @classmethod
+    def _validate_threshold_keys(cls, value: dict[str, LabelThreshold]) -> dict[str, LabelThreshold]:
+        unknown = sorted(set(value.keys()) - VALID_LABELS)
+        if unknown:
+            raise ValueError(f"Unknown label(s) in label_thresholds: {unknown}")
+        return value
+
+    def apply_to(self, base: LabelSetConfig) -> LabelSetConfig:
+        """Return a new ``LabelSetConfig`` with this override merged onto *base*."""
+        return LabelSetConfig(
+            labels=self.labels if self.labels is not None else base.labels,
+            confidence=self.confidence if self.confidence is not None else base.confidence,
+            area_ratio=self.area_ratio if self.area_ratio is not None else base.area_ratio,
+            label_thresholds=self.label_thresholds if self.label_thresholds else base.label_thresholds,
+        )
+
+
+class PresetOverride(BaseModel):
+    """Per-preset configuration overrides for all three classification tiers.
+
+    Loaded from env vars such as:
+      ``VISION_NSFW_STRICT__BLOCK__CONFIDENCE=0.9``
+      ``VISION_NSFW_NUDE_FEMALE__REVIEW__AREA_RATIO=0.05``
+
+    Unset tiers are inherited unchanged from the preset definition.
+    """
+
+    block: PresetTierOverride = Field(default_factory=PresetTierOverride)
+    review: PresetTierOverride = Field(default_factory=PresetTierOverride)
+    sensitive: PresetTierOverride = Field(default_factory=PresetTierOverride)

app/config/settings.py

@@ -7,7 +7,7 @@
 from pydantic import Field, ValidationError, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
-from app.config.models import LabelSetConfig
+from app.config.models import LabelSetConfig, PresetOverride
 
 _RED = "\033[31m"
 _YELLOW = "\033[33m"
@@ -113,7 +113,19 @@ class AppSettings(BaseSettings):
     """Load a named preset as the baseline for block / review / sensitive.
 
     Explicit ``VISION_NSFW_BLOCK``, ``VISION_NSFW_REVIEW``, or
-    ``VISION_NSFW_SENSITIVE`` values still override the preset.
+    ``VISION_NSFW_SENSITIVE`` values still override the preset.  Two override
+    modes are supported:
+
+    * **Full override** — supply ``labels`` (and optionally thresholds).  The
+      preset's label list is ignored entirely for that tier.
+      Example: ``VISION_NSFW_BLOCK='{"labels":["ANUS_EXPOSED"]}'``
+
+    * **Threshold-only override** — supply only threshold keys
+      (``confidence``, ``area_ratio``, ``label_thresholds``) *without*
+      ``labels``.  The preset's labels are kept and the explicit thresholds
+      are merged on top.
+      Example: ``VISION_NSFW_BLOCK__CONFIDENCE=0.9``
+      Example: ``VISION_NSFW_REVIEW__AREA_RATIO=0.05``
 
     Valid names: ``strict``, ``moderation``, ``nude_female``, ``permissive``,
     ``social_media``."""
@@ -129,9 +141,35 @@ def _apply_preset(cls, data: dict) -> dict:
         preset = PRESETS.get(preset_name)
         if preset is None:
             raise ValueError(f"Unknown preset {preset_name!r}. Valid presets: {sorted(PRESETS)}")
+
+        # Per-preset env overrides, e.g. VISION_NSFW_STRICT__BLOCK__CONFIDENCE=0.9
+        preset_override_raw = data.get(preset_name) or {}
+
         for field in ("block", "review", "sensitive"):
+            preset_config = getattr(preset, field).model_dump()
+
+            # Merge preset-specific tier override (labels replaced only when explicitly set)
+            tier_raw = {}
+            if isinstance(preset_override_raw, dict):
+                raw = preset_override_raw.get(field) or {}
+                if isinstance(raw, dict):
+                    if "labels" in raw and raw["labels"] is not None:
+                        tier_raw["labels"] = raw["labels"]
+                    for key in ("confidence", "area_ratio", "label_thresholds"):
+                        if raw.get(key) is not None:
+                            tier_raw[key] = raw[key]
+
+            merged_preset = {**preset_config, **tier_raw}
+
             if field not in data:
-                data[field] = getattr(preset, field).model_dump()
+                data[field] = merged_preset
+            elif isinstance(data[field], dict) and "labels" not in data[field]:
+                # Global threshold-only override on top of the (already merged) preset config.
+                # e.g. VISION_NSFW_BLOCK__CONFIDENCE=0.8 with VISION_NSFW_PRESET=strict
+                # keeps strict's labels but uses confidence=0.8.
+                data[field] = {**merged_preset, **data[field]}
+            # else: global override includes explicit labels → use as-is (full override).
+
         return data
 
     # --- Label set configurations ---
@@ -169,6 +207,38 @@ def _apply_preset(cls, data: dict) -> dict:
     )
     """Labels and thresholds for the *sensitive* tier (``is_sensitive`` in the callback)."""
 
+    # --- Per-preset overrides ---
+    # Each field holds threshold/label overrides for the corresponding named preset.
+    # These are loaded from env vars using the preset name as the nested key, e.g.:
+    #   VISION_NSFW_STRICT__BLOCK__CONFIDENCE=0.9
+    #   VISION_NSFW_NUDE_FEMALE__REVIEW__AREA_RATIO=0.05
+    # All fields default to no-op (inherit from the preset definition).
+    strict: PresetOverride = Field(default_factory=PresetOverride)
+    moderation: PresetOverride = Field(default_factory=PresetOverride)
+    nude_female: PresetOverride = Field(default_factory=PresetOverride)
+    permissive: PresetOverride = Field(default_factory=PresetOverride)
+    social_media: PresetOverride = Field(default_factory=PresetOverride)
+
+    def resolve_preset(self, name: str) -> tuple[LabelSetConfig, LabelSetConfig, LabelSetConfig]:
+        """Return ``(block, review, sensitive)`` for a preset with its env overrides applied.
+
+        Used for per-request preset selection: the caller swaps in these label sets
+        instead of the global ``block`` / ``review`` / ``sensitive`` fields.
+
+        Raises ``ValueError`` for unknown preset names.
+        """
+        from app.config.presets import PRESETS
+
+        if name not in PRESETS:
+            raise ValueError(f"Unknown preset {name!r}. Valid presets: {sorted(PRESETS)}")
+        preset = PRESETS[name]
+        override: PresetOverride = getattr(self, name)
+        return (
+            override.block.apply_to(preset.block),
+            override.review.apply_to(preset.review),
+            override.sensitive.apply_to(preset.sensitive),
+        )
+
     # --- Concurrency ---
     thread_pool_size: int = 1
     """Number of threads in the ``ThreadPoolExecutor`` used for CPU-bound inference."""

app/queue/worker.py

@@ -53,4 +53,5 @@ async def _handle_detect(job: Any, state: Any, settings: AppSettings) -> None:
         image_path=Path(payload["photo_path"]),
         executor=state.executor,
         settings=settings,
+        preset_name=payload.get("preset"),
     )