feat: enhance background removal quality and API robustness

- Added adaptive thresholding and artifact removal
- Optimized Dockerfile for HuggingFace Spaces
- Enhanced API with debug mode and extra parameters

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

.gitignore

@@ -0,0 +1,15 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+venv/
+.env
+
+# Images/Outputs
+*_output.png
+test_input.png
+cache/
+
+# IDEs
+.vscode/
+.idea/

@fix_plan.md

@@ -0,0 +1,35 @@
+# CutoutAI - Task Priority List
+
+## Completed
+- [x] Create basic cutoutai.py with BiRefNet integration
+- [x] Create api.py with webhook endpoint
+- [x] Add edge smoothing function
+- [x] Add requirements.txt
+- [x] Create project documentation
+- [x] Add mask thresholding (0.2 for capture_all, 0.4 standard)
+- [x] Implement capture_all_elements with lower threshold
+- [x] Replace blur with morphological edge processing (preserves details)
+- [x] Add startup model preloading
+- [x] Add processing time to responses
+- [x] Use model parameter in webhook
+- [x] Add input validation (10MB limit)
+- [x] Add Dockerfile for HuggingFace Spaces deployment
+- [x] Add processing time logging
+- [x] Add optional debug mode with intermediate outputs (return_mask=True)
+- [x] Add artifact removal (scipy ndimage)
+- [x] Add adaptive thresholding
+
+## In Progress
+- [ ] Test with Gemini-generated images
+
+## High Priority
+- [ ] Add Dockerfile for HuggingFace Spaces deployment
+- [ ] Test with various Gemini-generated design types
+
+## Medium Priority
+- [ ] Add batch processing optimizations
+- [ ] Add processing time logging
+- [ ] Add optional debug mode with intermediate outputs
+
+## Low Priority
+- [ ] Support for BiRefNet_HR (2K resolution)

ASSETS.md

@@ -0,0 +1,67 @@
+# Background Removal Tool - Project Assets
+
+> **Purpose**: Self-hosted background removal API for Etsy t-shirt workflow
+
+---
+
+## Core Files
+
+| File | Description |
+|------|-------------|
+| `cutoutai.py` | Core BiRefNet processing (365 lines) |
+| `api.py` | FastAPI server with webhooks (351 lines) |
+| `Dockerfile` | Production container |
+| `requirements.txt` | Python dependencies |
+| `test_cutout.py` | Automated test script |
+
+---
+
+## Configuration
+
+| File | Description |
+|------|-------------|
+| `PROMPT.md` | Ralph development instructions |
+| `@fix_plan.md` | Task priority tracking |
+| `specs/requirements.md` | Technical specifications |
+
+---
+
+## Test Outputs
+
+| File | Description |
+|------|-------------|
+| `test_output.png` | Synthetic test result |
+| `real_test_output.png` | cosmic_bloom.png result |
+| `hard_test_output.png` | ChatGPT image result (3.6MB input) |
+
+---
+
+## Key Features
+
+- **Models**: matting, general, portrait, lite, hr, dynamic
+- **API**: REST + Webhook (n8n compatible)
+- **Output**: PNG, base64
+- **Thresholding**: 0.2 (capture_all) / 0.4 (standard)
+
+---
+
+## Deployment Status
+
+| Target | Status |
+|--------|--------|
+| Local | ✅ Ready |
+| Railway | ⬜ Not deployed |
+| HuggingFace | ⬜ Not deployed |
+
+---
+
+## Related Projects
+
+| Project | Relationship |
+|---------|--------------|
+| `etsy tshirt project` | Primary consumer of this API |
+| `system-instructions` | CCR/Ralph configuration |
+
+---
+
+*Last Updated: Dec 28, 2025*

Dockerfile

@@ -0,0 +1,46 @@
+# Use NVIDIA CUDA base image if possible, otherwise standard python
+FROM python:3.10-slim
+
+# Set environment variables
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+ENV TRANSFORMERS_CACHE=/app/cache
+ENV MPLCONFIGDIR=/app/cache
+ENV HOME=/home/user
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    libgl1-mesa-glx \
+    libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set up a new user named "user" with UID 1000
+RUN useradd -m -u 1000 user
+
+# Create app directory
+WORKDIR /app
+
+# Install dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Create cache directory with right permissions
+RUN mkdir -p /app/cache && chmod 777 /app/cache
+
+# Switch to the "user" user
+USER user
+
+# Set home to /home/user
+ENV HOME=/home/user
+ENV PATH=/home/user/.local/bin:$PATH
+
+# Copy app code (owned by user)
+COPY --chown=user . .
+
+# Expose port (HuggingFace default is 7860)
+EXPOSE 7860
+
+# Start command
+# We use uvicorn to run the FastAPI app on port 7860
+CMD ["python", "api.py", "--port", "7860"]

PROMPT.md

@@ -0,0 +1,79 @@
+# CutoutAI Background Remover - Ralph Development Instructions
+
+## Project Goal
+Create a flawless background removal tool for the Etsy t-shirt workflow. This tool must produce perfect cutouts suitable for Printify mockups.
+
+## Current Workflow
+```
+Gemini Image Gen → Slack Approval → BACKGROUND REMOVAL → Printify Mockup → SEO → Etsy/Shopify
+```
+
+## Critical Requirements
+
+### 1. FLAWLESS Quality (Non-Negotiable)
+- NO patchy faces or artifacts
+- NO edge bleeding or halos
+- CLEAN edges on hair and fine details
+- Must look perfect on t-shirt mockups
+
+### 2. Multi-Element Capture
+The tool MUST capture ALL design elements including:
+- Main subject
+- Bubbles and floating decorations
+- Small text or symbols
+- Scattered elements (stars, sparkles, etc.)
+
+### 3. API Integration
+Must provide:
+- Webhook endpoint for n8n (POST /webhook)
+- REST API (POST /api/v1/remove)
+- Base64 input/output support
+- Health check endpoint
+
+## Files to Review and Improve
+
+1. **cutoutai.py** - Core processing logic
+   - Uses BiRefNet-matting model (correct choice)
+   - Has edge_smooth function (may need enhancement)
+   - Check if multi-element capture is working properly
+
+2. **api.py** - FastAPI server
+   - Webhook endpoint exists
+   - Verify n8n compatibility
+   - Add any missing error handling
+
+3. **requirements.txt** - Dependencies
+   - Verify all needed packages are listed
+
+## Improvement Tasks
+
+### Priority 1: Quality Enhancement
+- [ ] Verify BiRefNet output quality
+- [ ] Test edge refinement settings
+- [ ] Add adaptive thresholding for multi-element capture
+- [ ] Consider adding post-processing for artifact removal
+
+### Priority 2: API Robustness
+- [ ] Add proper error responses with details
+- [ ] Add request validation
+- [ ] Add timeout handling for large images
+- [ ] Verify callback_url functionality
+
+### Priority 3: Deployment Ready
+- [ ] Add Dockerfile for HuggingFace Spaces
+- [ ] Add startup preloading (reduce first-request latency)
+- [ ] Add logging for debugging
+
+## Success Criteria
+- Process Gemini-generated images with ZERO visible artifacts
+- Capture ALL design elements (test with bubble/sparkle designs)
+- Return base64 that works in n8n HTTP Request node
+- Health endpoint returns proper status
+
+## Reference Documents
+See specs/requirements.md for detailed technical specifications.
+
+## Notes
+- This will replace the current HuggingFace BiRefNet API in the Etsy workflow
+- Priority is QUALITY over speed (mockups need to be perfect)
+- Test with white AND non-white backgrounds (Gemini may vary)

README.md

@@ -0,0 +1,68 @@
+# CutoutAI - Background Remover
+
+An enhanced, flawless background removal tool built on BiRefNet for perfect t-shirt mockup preparation.
+
+## Features
+
+- **Flawless Removal**: No patchy faces, artifacts, or edge issues
+- **Multi-Element Capture**: Captures bubbles, decorations, and all design elements
+- **API Ready**: Webhook, HTTP API, terminal commands
+- **Cloud Hosted**: Designed for n8n, Make, and cloud automation
+- **Mockup Quality**: Optimized for Printify t-shirt mockups
+
+## Quick Start
+
+```python
+from cutoutai import remove_background
+
+# Basic usage
+result = remove_background("design.png")
+result.save("design_cutout.png")
+
+# With enhanced settings for complex designs
+result = remove_background(
+    "design.png",
+    capture_all_elements=True,  # Get bubbles, small elements
+    edge_refinement=True,       # Smooth edges
+    matting_mode="general"      # or "portrait" for faces
+)
+```
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/v1/remove` | POST | Remove background from image |
+| `/api/v1/batch` | POST | Process multiple images |
+| `/api/v1/health` | GET | Health check |
+| `/webhook` | POST | n8n/Make webhook endpoint |
+
+## Workflow Integration
+
+### n8n Webhook
+```
+POST https://your-host/webhook
+Content-Type: multipart/form-data
+
+image: <file>
+options: {"capture_all_elements": true}
+```
+
+### CLI
+```bash
+cutoutai process design.png --output cutout.png
+cutoutai batch ./designs/ --output ./cutouts/
+```
+
+## Quality Settings
+
+| Setting | Description | Use Case |
+|---------|-------------|----------|
+| `capture_all_elements` | Detect and preserve small elements (bubbles, decorations) | Complex designs |
+| `edge_refinement` | Smooth and feather edges | All mockups |
+| `matting_mode` | `general`, `portrait`, or `heavy` | Match content type |
+| `output_resolution` | Preserve or scale output | Printify requirements |
+
+## License
+
+MIT License - Built on BiRefNet

api.py

@@ -0,0 +1,388 @@
+"""
+CutoutAI API Server
+
+FastAPI server providing:
+- REST API endpoints for background removal
+- Webhook endpoint for n8n/Make integration
+- Health check for monitoring
+- Startup model preloading
+"""
+
+import io
+import base64
+import time
+import logging
+from typing import Optional, Literal, Union
+from pathlib import Path
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, File, UploadFile, Form, HTTPException, Request
+from fastapi.responses import Response, JSONResponse
+from pydantic import BaseModel, Field
+
+from cutoutai import CutoutAI, MODEL_VARIANTS, logger as cutout_logger
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger("CutoutAI-API")
+
+# Global model instances (by variant)
+_models: dict[str, CutoutAI] = {}
+
+def get_model(variant: str = "matting") -> CutoutAI:
+    """Get or create a model instance for the specified variant."""
+    global _models
+    if variant not in _models:
+        _models[variant] = CutoutAI(model_variant=variant)
+        _models[variant].load_model()
+    return _models[variant]
+
+
+# Lifespan context for startup/shutdown
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup: preload the default model
+    print("Preloading matting model...")
+    get_model("matting")
+    print("Model preloaded and ready!")
+    yield
+    # Shutdown: cleanup
+    _models.clear()
+
+
+# Initialize FastAPI with lifespan
+app = FastAPI(
+    title="CutoutAI - Background Remover",
+    description="Flawless background removal for t-shirt mockups and design workflows",
+    version="1.1.0",
+    lifespan=lifespan
+)
+
+
+# Request/Response models
+class ProcessOptions(BaseModel):
+    model: Literal["general", "matting", "portrait", "lite", "hr", "dynamic"] = "matting"
+    capture_all_elements: bool = True
+    edge_refinement: bool = True
+    edge_radius: int = 2
+    threshold: Optional[float] = None
+    soft_threshold: bool = False
+    remove_artifacts: bool = True
+    min_artifact_size: int = 40
+    adaptive_threshold: bool = True
+    return_mask: bool = False
+    output_format: Literal["png", "base64"] = "png"
+
+
+class WebhookRequest(BaseModel):
+    image_base64: Optional[str] = None
+    image_url: Optional[str] = None
+    options: Optional[ProcessOptions] = None
+
+
+class HealthResponse(BaseModel):
+    status: str
+    version: str
+    model_loaded: bool
+    models_loaded: list[str]
+    device: str
+
+
+# Endpoints
+@app.get("/health", response_model=HealthResponse)
+async def health_check():
+    """Health check endpoint for monitoring."""
+    global _models
+    loaded_models = list(_models.keys())
+    device = _models["matting"].device if "matting" in _models else "not loaded"
+    return HealthResponse(
+        status="healthy",
+        version="1.1.0",
+        model_loaded=len(_models) > 0,
+        models_loaded=loaded_models,
+        device=device
+    )
+
+
+@app.get("/")
+async def root():
+    """Root endpoint with API info."""
+    return {
+        "name": "CutoutAI - Background Remover",
+        "version": "1.1.0",
+        "docs": "/docs",
+        "health": "/health"
+    }
+
+
+@app.post("/api/v1/remove")
+async def remove_bg(
+    image: UploadFile = File(...),
+    model: str = Form("matting"),
+    edge_refinement: bool = Form(True),
+    capture_all_elements: bool = Form(True),
+    threshold: Optional[float] = Form(None),
+    soft_threshold: bool = Form(False),
+    remove_artifacts: bool = Form(True),
+    adaptive_threshold: bool = Form(True),
+    return_mask: bool = Form(False),
+    output_format: str = Form("png")
+):
+    """
+    Remove background from uploaded image.
+
+    - **image**: Image file to process
+    - **model**: Model variant (matting recommended for designs)
+    - **edge_refinement**: Smooth edges for cleaner cutouts
+    - **capture_all_elements**: Lower threshold to capture bubbles/small elements
+    - **threshold**: Override mask threshold (0.0-1.0)
+    - **soft_threshold**: Use soft thresholding
+    - **remove_artifacts**: Remove small isolated islands from mask
+    - **adaptive_threshold**: Calculate threshold based on image confidence
+    - **return_mask**: Return a JSON object with both result and mask
+    - **output_format**: "png" for file download, "base64" for JSON response
+    """
+    start_time = time.time()
+
+    try:
+        # Validate model
+        if model not in MODEL_VARIANTS:
+            raise HTTPException(status_code=400, detail=f"Invalid model: {model}. Available variants: {list(MODEL_VARIANTS.keys())}")
+
+        # Read image
+        contents = await image.read()
+
+        # Validate file size (max 10MB)
+        if len(contents) > 10 * 1024 * 1024:
+            raise HTTPException(status_code=413, detail="Image too large (max 10MB)")
+
+        # Process
+        processor = get_model(model)
+        result = processor.process(
+            contents,
+            edge_refinement=edge_refinement,
+            capture_all_elements=capture_all_elements,
+            threshold=threshold,
+            soft_threshold=soft_threshold,
+            remove_artifacts=remove_artifacts,
+            adaptive_threshold=adaptive_threshold,
+            return_mask=return_mask,
+            output_format="bytes" if output_format == "png" and not return_mask else "base64"
+        )
+
+        processing_time = time.time() - start_time
+
+        if return_mask:
+            # result is a dict here
+            return JSONResponse({
+                "success": True,
+                "result_base64": result["result"],
+                "mask_base64": result["mask"],
+                "threshold_used": round(result["threshold_used"], 4),
+                "processing_time_seconds": round(processing_time, 2)
+            })
+
+        if output_format == "png":
+            return Response(
+                content=result,
+                media_type="image/png",
+                headers={
+                    "Content-Disposition": f'attachment; filename="{image.filename}_cutout.png"',
+                    "X-Processing-Time": f"{processing_time:.2f}s"
+                }
+            )
+        else:
+            return JSONResponse({
+                "success": True,
+                "image_base64": result,
+                "processing_time_seconds": round(processing_time, 2)
+            })
+
+    except HTTPException:
+        raise
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        logger.exception("Error processing request")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")
+
+
+@app.post("/api/v1/batch")
+async def batch_remove(
+    images: list[UploadFile] = File(...),
+    model: str = Form("matting"),
+    capture_all_elements: bool = Form(True)
+):
+    """Process multiple images in batch."""
+    start_time = time.time()
+    results = []
+    processor = get_model(model)
+    
+    for img in images:
+        contents = await img.read()
+        result = processor.process(
+            contents,
+            capture_all_elements=capture_all_elements,
+            output_format="base64"
+        )
+        results.append({
+            "filename": img.filename,
+            "image_base64": result
+        })
+    
+    total_time = time.time() - start_time
+    
+    return JSONResponse({
+        "success": True,
+        "count": len(results),
+        "results": results,
+        "total_processing_time_seconds": round(total_time, 2)
+    })
+
+
+@app.post("/webhook")
+async def webhook_handler(
+    request: Request,
+    image: Optional[UploadFile] = File(None),
+    image_base64: Optional[str] = Form(None),
+    image_url: Optional[str] = Form(None),
+    model: str = Form("matting"),
+    edge_refinement: bool = Form(True),
+    capture_all_elements: bool = Form(True),
+    edge_radius: int = Form(2),
+    threshold: Optional[float] = Form(None),
+    soft_threshold: bool = Form(False),
+    callback_url: Optional[str] = Form(None)
+):
+    """
+    Webhook endpoint for n8n/Make integration.
+
+    Accepts image via:
+    - File upload (image)
+    - Base64 encoded string (image_base64)
+    - URL to fetch (image_url)
+
+    Returns base64 encoded result for easy workflow integration.
+    """
+    start_time = time.time()
+    logger.info(f"Webhook request received from {request.client.host}")
+
+    try:
+        # Check if JSON body instead of form
+        if request.headers.get("content-type") == "application/json":
+            try:
+                body = await request.json()
+                image_base64 = body.get("image_base64", image_base64)
+                image_url = body.get("image_url", image_url)
+                model = body.get("model", model)
+                edge_refinement = body.get("edge_refinement", edge_refinement)
+                capture_all_elements = body.get("capture_all_elements", capture_all_elements)
+                edge_radius = body.get("edge_radius", edge_radius)
+                threshold = body.get("threshold", threshold)
+                soft_threshold = body.get("soft_threshold", soft_threshold)
+                callback_url = body.get("callback_url", callback_url)
+            except Exception as e:
+                logger.warning(f"Failed to parse JSON body: {e}")
+
+        # Validate model
+        if model not in MODEL_VARIANTS:
+            logger.error(f"Invalid model requested: {model}")
+            return JSONResponse(
+                {"success": False, "error": f"Invalid model: {model}. Available: {list(MODEL_VARIANTS.keys())}"},
+                status_code=400
+            )
+
+        processor = get_model(model)
+
+        # Get image from one of the sources
+        img_data = None
+        if image:
+            img_data = await image.read()
+            logger.info(f"Using uploaded file: {image.filename}")
+        elif image_base64:
+            try:
+                # Handle potential header in base64
+                if "," in image_base64:
+                    image_base64 = image_base64.split(",")[1]
+                img_data = base64.b64decode(image_base64)
+                logger.info("Using base64 image data")
+            except Exception as e:
+                return JSONResponse({"success": False, "error": f"Invalid base64 data: {e}"}, status_code=400)
+        elif image_url:
+            import httpx
+            logger.info(f"Fetching image from URL: {image_url}")
+            async with httpx.AsyncClient(timeout=30.0, follow_redirects=True) as client:
+                try:
+                    response = await client.get(image_url)
+                    response.raise_for_status()
+                    img_data = response.content
+                except httpx.HTTPStatusError as e:
+                    return JSONResponse({"success": False, "error": f"Failed to fetch image: {e.response.status_code}"}, status_code=400)
+                except Exception as e:
+                    return JSONResponse({"success": False, "error": f"Network error: {e}"}, status_code=500)
+        else:
+            return JSONResponse(
+                {"success": False, "error": "No image provided. Use 'image', 'image_base64', or 'image_url'"},
+                status_code=400
+            )
+
+        # Validate data
+        if not img_data:
+            return JSONResponse({"success": False, "error": "Empty image data"}, status_code=400)
+
+        # Process
+        result = processor.process(
+            img_data,
+            edge_refinement=edge_refinement,
+            capture_all_elements=capture_all_elements,
+            edge_radius=edge_radius,
+            threshold=threshold,
+            soft_threshold=soft_threshold,
+            output_format="base64"
+        )
+
+        processing_time = time.time() - start_time
+
+        response_data = {
+            "success": True,
+            "image_base64": result,
+            "model_used": model,
+            "processing_time_seconds": round(processing_time, 2)
+        }
+
+        # If callback URL provided, send result there too
+        if callback_url:
+            import httpx
+            logger.info(f"Sending callback to: {callback_url}")
+            async with httpx.AsyncClient(timeout=10.0) as client:
+                try:
+                    await client.post(callback_url, json=response_data)
+                except Exception as e:
+                    logger.error(f"Callback failed: {e}")
+                    response_data["callback_error"] = str(e)
+
+        return JSONResponse(response_data)
+
+    except Exception as e:
+        logger.exception("Unexpected error in webhook handler")
+        return JSONResponse(
+            {"success": False, "error": str(e)},
+            status_code=500
+        )
+
+
+# CLI entry point
+if __name__ == "__main__":
+    import uvicorn
+    import argparse
+    import os
+
+    parser = argparse.ArgumentParser(description="CutoutAI API Server")
+    parser.add_argument("--host", default="0.0.0.0", help="Host address")
+    parser.add_argument("--port", type=int, default=int(os.environ.get("PORT", 8000)), help="Port number")
+    args = parser.parse_args()
+
+    uvicorn.run(app, host=args.host, port=args.port)

cutoutai.py

@@ -0,0 +1,441 @@
+"""
+CutoutAI - Enhanced Background Removal for Perfect T-Shirt Mockups
+
+Built on BiRefNet for flawless background removal with:
+- Multi-element capture (bubbles, decorations, small details)
+- Edge refinement for clean cutouts
+- Optimized for Printify mockup preparation
+"""
+
+import io
+import base64
+import time
+import logging
+from typing import Optional, Literal, Union
+from pathlib import Path
+
+import torch
+import numpy as np
+from PIL import Image, ImageFilter
+from torchvision import transforms
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger("CutoutAI")
+
+# Model variants available
+MODEL_VARIANTS = {
+    "general": "ZhengPeng7/BiRefNet",           # General use
+    "matting": "ZhengPeng7/BiRefNet-matting",   # Best for complex edges
+    "portrait": "ZhengPeng7/BiRefNet-portrait", # Faces/people
+    "lite": "ZhengPeng7/BiRefNet_lite",         # Faster, smaller
+    "hr": "ZhengPeng7/BiRefNet_HR",             # High resolution (2K)
+    "dynamic": "ZhengPeng7/BiRefNet_dynamic",   # Variable resolution
+}
+
+# Default image transforms
+def get_transforms(size: int = 1024):
+    """Get preprocessing transforms for BiRefNet."""
+    return transforms.Compose([
+        transforms.Resize((size, size)),
+        transforms.ToTensor(),
+        transforms.Normalize(
+            mean=[0.485, 0.456, 0.406],
+            std=[0.229, 0.224, 0.225]
+        )
+    ])
+
+
+def refine_foreground(image: Image.Image, mask: Image.Image) -> Image.Image:
+    """
+    Apply mask to image with refined edges for flawless cutouts.
+    
+    This is critical for t-shirt mockups - ensures:
+    - No patchy faces or artifacts
+    - Clean edges on hair and fine details
+    - All small elements (bubbles, decorations) captured
+    """
+    # Convert to RGBA
+    image = image.convert("RGBA")
+    mask = mask.convert("L")
+    
+    # Resize mask to match image if needed
+    if mask.size != image.size:
+        mask = mask.resize(image.size, Image.LANCZOS)
+    
+    # Apply mask as alpha channel
+    result = Image.new("RGBA", image.size, (0, 0, 0, 0))
+    result.paste(image, mask=mask)
+    
+    return result
+
+
+def edge_smooth(mask: Image.Image, radius: int = 2, preserve_details: bool = True) -> Image.Image:
+    """
+    Apply edge smoothing while preserving fine details.
+
+    Args:
+        mask: Binary or grayscale mask
+        radius: Smoothing intensity (1-5 recommended)
+        preserve_details: If True, use morphological ops instead of blur
+    """
+    if radius <= 0:
+        return mask
+
+    if preserve_details:
+        # Use morphological operations to clean edges without losing detail
+        # Erosion removes thin protrusions (noise)
+        # size must be odd
+        size = 2 * radius + 1
+        eroded = mask.filter(ImageFilter.MinFilter(size))
+        # Dilation restores the shape
+        smoothed = eroded.filter(ImageFilter.MaxFilter(size))
+
+        # Optional: slight median filter to remove salt-and-pepper noise
+        if radius > 1:
+            smoothed = smoothed.filter(ImageFilter.MedianFilter(3))
+    else:
+        # Fall back to gaussian blur for softer edges
+        smoothed = mask.filter(ImageFilter.GaussianBlur(radius=radius))
+
+    return smoothed
+
+
+def remove_small_artifacts(mask: Image.Image, min_size: int = 100) -> Image.Image:
+    """
+    Remove small isolated 'islands' from the mask that are likely artifacts.
+
+    Args:
+        mask: Grayscale mask (PIL Image)
+        min_size: Minimum pixel area to keep
+    """
+    import numpy as np
+    from scipy import ndimage
+
+    # Convert to binary
+    mask_np = np.array(mask) > 128
+
+    # Label connected components
+    label_im, nb_labels = ndimage.label(mask_np)
+
+    # Calculate sizes of components
+    sizes = ndimage.sum(mask_np, label_im, range(nb_labels + 1))
+
+    # Identify components that are too small
+    mask_size = sizes < min_size
+    remove_pixel = mask_size[label_im]
+
+    # Remove small components
+    mask_np[remove_pixel] = 0
+
+    return Image.fromarray((mask_np * 255).astype(np.uint8))
+
+
+def calculate_adaptive_threshold(pred: np.ndarray, base_threshold: float = 0.2) -> float:
+    """
+    Calculate an adaptive threshold based on the prediction distribution.
+    Useful for capturing small design elements without introducing too much noise.
+    """
+    # Simple adaptive approach: if there are many low-confidence pixels,
+    # we might be looking at a design with many small elements (bubbles, etc.)
+    # We can use a percentile-based approach or Otsu's method if appropriate
+
+    # For now, let's use a simple heuristic:
+    # If the 95th percentile is low, it's a very faint design, lower the threshold further
+    p95 = np.percentile(pred, 95)
+    if p95 < 0.5:
+        return max(0.05, base_threshold * 0.5)
+
+    return base_threshold
+
+
+def apply_threshold(pred: np.ndarray, threshold: float = 0.4, soft: bool = False) -> np.ndarray:
+    """
+    Apply threshold to mask for cleaner binary edges.
+
+    Args:
+        pred: Prediction array (0-1 range)
+        threshold: Cutoff value (pixels below become 0, above become 1)
+        soft: If True, use a soft threshold (keep low confidence regions as semi-transparent)
+
+    Returns:
+        Thresholded array
+    """
+    if soft:
+        # Sigmoid-like soft thresholding
+        # Regions near threshold are preserved but dimmed
+        # Steepness of 15 provides a good balance between sharp and soft
+        return 1.0 / (1.0 + np.exp(-15 * (pred - threshold)))
+
+    return np.where(pred > threshold, 1.0, 0.0)
+
+
+class CutoutAI:
+    """
+    Enhanced background removal optimized for t-shirt mockup preparation.
+    
+    Key features:
+    - Captures ALL elements including bubbles, small decorations
+    - Flawless edge quality with no artifacts
+    - Multiple model options for different use cases
+    """
+    
+    def __init__(
+        self,
+        model_variant: Literal["general", "matting", "portrait", "lite", "hr", "dynamic"] = "matting",
+        device: Optional[str] = None,
+        resolution: int = 1024
+    ):
+        """
+        Initialize CutoutAI.
+        
+        Args:
+            model_variant: Which BiRefNet model to use
+                - "matting": Best for complex edges, hair, fine details (RECOMMENDED)
+                - "general": Standard background removal
+                - "portrait": Optimized for faces/people
+                - "lite": Faster processing, lower quality
+                - "hr": High resolution up to 2K
+                - "dynamic": Variable resolution support
+            device: "cuda", "cpu", or None for auto-detect
+            resolution: Processing resolution (1024 or 2048 for hr model)
+        """
+        self.model_variant = model_variant
+        self.model_name = MODEL_VARIANTS[model_variant]
+        self.resolution = resolution
+        
+        # Auto-detect device
+        if device is None:
+            self.device = "cuda" if torch.cuda.is_available() else "cpu"
+        else:
+            self.device = device
+        
+        self.model = None
+        self.transforms = get_transforms(resolution)
+    
+    def load_model(self):
+        """Load the BiRefNet model from HuggingFace."""
+        if self.model is not None:
+            return
+        
+        from transformers import AutoModelForImageSegmentation
+        
+        print(f"Loading {self.model_name}...")
+        self.model = AutoModelForImageSegmentation.from_pretrained(
+            self.model_name,
+            trust_remote_code=True
+        )
+        self.model.to(self.device)
+        self.model.eval()
+        print(f"Model loaded on {self.device}")
+    
+    def process(
+        self,
+        image: Union[str, Path, Image.Image, bytes],
+        capture_all_elements: bool = True,
+        edge_refinement: bool = True,
+        edge_radius: int = 2,
+        threshold: Optional[float] = None,
+        soft_threshold: bool = False,
+        preserve_details: bool = True,
+        remove_artifacts: bool = True,
+        min_artifact_size: int = 40,
+        adaptive_threshold: bool = True,
+        return_mask: bool = False,
+        output_format: Literal["pil", "bytes", "base64"] = "pil"
+    ) -> Union[Image.Image, bytes, str, dict]:
+        """
+        Remove background from image with enhanced quality.
+
+        Args:
+            image: Input image (path, PIL Image, or bytes)
+            capture_all_elements: Use lower threshold to capture bubbles/small elements
+            edge_refinement: Apply edge smoothing for cleaner cutouts
+            edge_radius: Smoothing intensity (1-5, default 2)
+            threshold: Override mask threshold (0.0-1.0, None for auto)
+            soft_threshold: Use soft thresholding for smoother transitions
+            preserve_details: Use morphological ops instead of blur
+            remove_artifacts: Remove small isolated islands from mask
+            min_artifact_size: Minimum pixel area for islands to keep
+            adaptive_threshold: Calculate threshold based on image confidence
+            return_mask: If True, return a dict containing both result and mask
+            output_format: Return format ("pil", "bytes", "base64")
+
+        Returns:
+            Processed image with transparent background (or dict if return_mask=True)
+        """
+        start_time = time.time()
+        logger.info(f"Processing image with variant: {self.model_variant}")
+        self.load_model()
+
+        # Load image
+        try:
+            if isinstance(image, (str, Path)):
+                pil_image = Image.open(image).convert("RGB")
+            elif isinstance(image, bytes):
+                pil_image = Image.open(io.BytesIO(image)).convert("RGB")
+            else:
+                pil_image = image.convert("RGB")
+        except Exception as e:
+            logger.error(f"Failed to load image: {e}")
+            raise ValueError(f"Invalid image input: {e}")
+
+        original_size = pil_image.size
+        logger.info(f"Image size: {original_size}")
+
+        # Preprocess
+        input_tensor = self.transforms(pil_image).unsqueeze(0).to(self.device)
+
+        # Inference
+        with torch.no_grad():
+            outputs = self.model(input_tensor)
+
+        # Get prediction mask
+        if isinstance(outputs, (list, tuple)):
+            pred = outputs[0]
+        else:
+            pred = outputs
+
+        # Convert to numpy
+        pred = pred.squeeze().cpu().numpy()
+
+        # Apply thresholding for cleaner edges
+        # Lower threshold captures more (bubbles, small elements)
+        # Higher threshold is more selective
+        if threshold is not None:
+            mask_threshold = threshold
+        elif capture_all_elements:
+            mask_threshold = 0.2  # Base low threshold
+            if adaptive_threshold:
+                mask_threshold = calculate_adaptive_threshold(pred, mask_threshold)
+        else:
+            mask_threshold = 0.4  # Standard threshold
+
+        logger.info(f"Using threshold: {mask_threshold:.4f} (soft: {soft_threshold})")
+        pred = apply_threshold(pred, mask_threshold, soft=soft_threshold)
+
+        # Convert to PIL mask
+        pred = (pred * 255).astype(np.uint8)
+        mask = Image.fromarray(pred).resize(original_size, Image.LANCZOS)
+
+        # Remove small artifacts if requested
+        if remove_artifacts:
+            logger.info(f"Removing small artifacts (min_size: {min_artifact_size})")
+            try:
+                mask = remove_small_artifacts(mask, min_size=min_artifact_size)
+            except ImportError:
+                logger.warning("Scipy not installed, skipping artifact removal")
+
+        # Edge refinement for cleaner cutouts
+        if edge_refinement:
+            logger.info(f"Applying edge refinement (radius: {edge_radius})")
+            mask = edge_smooth(mask, radius=edge_radius, preserve_details=preserve_details)
+
+        # Apply mask to get final result
+        result = refine_foreground(pil_image, mask)
+
+        # Record processing time
+        self._last_processing_time = time.time() - start_time
+        logger.info(f"Processing completed in {self._last_processing_time:.2f}s")
+
+        # Prepare outputs
+        if return_mask:
+            return {
+                "result": self._format_output(result, output_format),
+                "mask": self._format_output(mask, output_format),
+                "threshold_used": mask_threshold,
+                "processing_time": self._last_processing_time
+            }
+
+        return self._format_output(result, output_format)
+
+    def _format_output(self, image: Image.Image, output_format: str) -> Union[Image.Image, bytes, str]:
+        """Format PIL Image to requested output format."""
+        if output_format == "pil":
+            return image
+        elif output_format == "bytes":
+            buffer = io.BytesIO()
+            image.save(buffer, format="PNG")
+            return buffer.getvalue()
+        elif output_format == "base64":
+            buffer = io.BytesIO()
+            image.save(buffer, format="PNG")
+            return base64.b64encode(buffer.getvalue()).decode()
+        return image
+
+    @property
+    def last_processing_time(self) -> float:
+        """Get the processing time of the last operation in seconds."""
+        return getattr(self, '_last_processing_time', 0.0)
+    
+    def process_batch(
+        self,
+        images: list,
+        **kwargs
+    ) -> list:
+        """Process multiple images."""
+        return [self.process(img, **kwargs) for img in images]
+
+
+# Convenience function
+def remove_background(
+    image: Union[str, Path, Image.Image, bytes],
+    model: str = "matting",
+    capture_all_elements: bool = True,
+    edge_refinement: bool = True,
+    **kwargs
+) -> Image.Image:
+    """
+    Quick function to remove background from an image.
+    
+    Args:
+        image: Input image
+        model: Model variant ("matting" recommended for t-shirt designs)
+        capture_all_elements: Capture bubbles, small elements (uses lower threshold)
+        edge_refinement: Smooth edges for clean mockups
+    
+    Returns:
+        PIL Image with transparent background
+    """
+    processor = CutoutAI(model_variant=model)
+    return processor.process(
+        image,
+        capture_all_elements=capture_all_elements,
+        edge_refinement=edge_refinement,
+        **kwargs
+    )
+
+
+if __name__ == "__main__":
+    import argparse
+    
+    parser = argparse.ArgumentParser(description="CutoutAI Background Remover")
+    parser.add_argument("input", help="Input image path")
+    parser.add_argument("-o", "--output", help="Output path", default=None)
+    parser.add_argument("-m", "--model", choices=list(MODEL_VARIANTS.keys()), 
+                       default="matting", help="Model variant")
+    parser.add_argument("--no-edge-refinement", action="store_true",
+                       help="Disable edge refinement")
+    parser.add_argument("--threshold", type=float, default=None,
+                       help="Mask threshold (0.0-1.0)")
+    parser.add_argument("--capture-all", action="store_true", default=True,
+                       help="Use lower threshold to capture small elements")
+    
+    args = parser.parse_args()
+    
+    # Process
+    result = remove_background(
+        args.input,
+        model=args.model,
+        edge_refinement=not args.no_edge_refinement,
+        capture_all_elements=args.capture_all,
+        threshold=args.threshold
+    )
+    
+    # Save
+    output_path = args.output or args.input.rsplit(".", 1)[0] + "_cutout.png"
+    result.save(output_path)
+    print(f"Saved to: {output_path}")

requirements.txt

@@ -0,0 +1,22 @@
+# CutoutAI Dependencies
+
+# Core ML
+torch>=2.0.0
+torchvision>=0.15.0
+transformers>=4.35.0
+timm>=0.9.0
+kornia>=0.7.0
+
+# Image processing
+Pillow>=10.0.0
+numpy>=1.24.0
+scipy>=1.10.0
+
+# API server
+fastapi>=0.104.0
+uvicorn[standard]>=0.24.0
+python-multipart>=0.0.6
+httpx>=0.25.0
+
+# Optional: for HuggingFace model loading
+huggingface-hub>=0.19.0

run-claude-analysis.bat

@@ -0,0 +1,23 @@
+@echo off
+echo ============================================
+echo  CutoutAI Analysis via Claude Code + CCR
+echo ============================================
+echo.
+
+:: Set environment for CCR
+set CLAUDE_BASE_URL=http://127.0.0.1:3456
+set ANTHROPIC_BASE_URL=http://127.0.0.1:3456
+
+:: Change to project directory
+cd /d "C:\Users\jonat_cau4\.gemini\antigravity\scratch\background removal tool"
+
+echo Current directory: %CD%
+echo CCR URL: %CLAUDE_BASE_URL%
+echo.
+echo Starting Claude Code with analysis prompt...
+echo.
+
+:: Run Claude Code with the analysis task
+claude -p "Read and analyze all files in this project: PROMPT.md, cutoutai.py, api.py, @fix_plan.md, specs/requirements.md, and README.md. Provide a COMPREHENSIVE ANALYSIS including: 1) Code quality assessment, 2) Edge handling for t-shirt mockups - is thresholding correct?, 3) Multi-element capture (bubbles) - is the threshold low enough?, 4) API robustness for n8n/Make integration, 5) Startup preloading implementation, 6) Any bugs or issues found. Then provide SPECIFIC IMPROVEMENT RECOMMENDATIONS with code examples. After analysis, ask if I want you to implement the improvements."
+
+pause

specs/requirements.md

@@ -0,0 +1,134 @@
+# CutoutAI Background Remover - Project Specifications
+
+## Project Overview
+
+**Name**: CutoutAI - Background Remover  
+**Purpose**: Flawless background removal for t-shirt mockup preparation in Etsy workflow  
+**Core Tech**: BiRefNet (BiRefNet-matting model)  
+**Deployment**: Cloud-hosted (n8n/Make integration), webhook API, terminal CLI
+
+## Current Workflow (Etsy T-Shirt Pipeline)
+
+```
+Gemini Image Gen → Slack Approval → [BACKGROUND REMOVAL] → Printify Mockup → SEO → Etsy/Shopify
+                       ↓
+                 Feedback loop (re-prompt if needed)
+```
+
+## Requirements
+
+### Functional Requirements
+
+1. **Flawless Quality**
+   - NO patchy faces or artifacts
+   - Clean edges on hair and fine details
+   - Capture ALL elements including:
+     - Bubbles
+     - Small decorations
+     - Floating elements
+     - Text overlays
+
+2. **Input Handling**
+   - Accept various image qualities from Gemini
+   - Handle non-white backgrounds (prepare for anything)
+   - Process images WITH multiple small elements
+
+3. **API/Integration**
+   - Webhook endpoint for n8n
+   - Base64 input/output for easy workflow integration
+   - REST API for batch processing
+   - Terminal CLI for manual use
+
+4. **Cloud Deployment**
+   - Host on HuggingFace Spaces or Google Cloud Run
+   - Zero cold-start penalty (or minimal)
+   - Handle concurrent requests
+
+### Non-Functional Requirements
+
+1. **Performance**
+   - Sub-10 second processing for standard images
+   - Batch processing capability
+
+2. **Reliability**
+   - Health check endpoint
+   - Error reporting to callback URLs
+
+## Technical Specifications
+
+### Recommended Model Settings
+
+```python
+# BiRefNet-matting is CRITICAL for edge quality
+model_variant = "matting"  # NOT "general"
+
+# Resolution considerations
+# - 1024x1024 for standard processing
+# - 2048x2048 for high-res (BiRefNet_HR)
+
+# Edge refinement is REQUIRED for mockups
+edge_refinement = True
+edge_radius = 2  # Subtle smoothing
+```
+
+### Known Issues to Address
+
+1. **Artifact Prevention**
+   - Downsampling large images can cause artifacts
+   - Solution: Use appropriate input resolution matching model
+   - Consider super-resolution post-processing if needed
+
+2. **Multi-Element Capture**
+   - BiRefNet's bilateral reference should capture small elements
+   - May need to adjust detection thresholds for bubbles/decorations
+
+3. **Edge Quality**
+   - `refine_foreground` function is essential
+   - Edge smoothing radius should be configurable
+
+## API Specification
+
+### Endpoints Required
+
+```yaml
+POST /api/v1/remove:
+  input: multipart/form-data OR JSON with base64
+  params:
+    - model: string (matting|general|portrait|hr)
+    - edge_refinement: boolean
+    - edge_radius: int (1-5)
+    - output_format: string (png|base64)
+  output: PNG file OR JSON with base64
+
+POST /webhook:
+  input: 
+    - image: file upload OR
+    - image_base64: string OR
+    - image_url: string
+  output: JSON with base64 image
+
+GET /health:
+  output: JSON status
+```
+
+### n8n Integration
+
+The webhook must be compatible with n8n HTTP Request node:
+- Accept multipart/form-data
+- Return JSON with `image_base64` field
+- Support `callback_url` parameter for async notifications
+
+## Files to Review
+
+1. `cutoutai.py` - Core background removal logic
+2. `api.py` - FastAPI server and endpoints
+3. `requirements.txt` - Dependencies
+
+## Success Criteria
+
+- [ ] Process Gemini-generated designs without artifacts
+- [ ] Capture bubbles and small decorative elements
+- [ ] Clean edges suitable for Printify mockups
+- [ ] Working webhook for n8n integration
+- [ ] Base64 input/output for workflow compatibility
+- [ ] Health check endpoint for monitoring

test_cutout.py

@@ -0,0 +1,70 @@
+import os
+import io
+import base64
+import numpy as np
+from PIL import Image, ImageDraw
+import cutoutai
+import logging
+
+# Setup logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger("TestCutoutAI")
+
+def create_test_image(path="test_input.png"):
+    """Create a synthetic test image with bubbles and a central object."""
+    # 512x512 white background
+    img = Image.new("RGB", (512, 512), (240, 240, 240))
+    draw = ImageDraw.Draw(img)
+
+    # Draw a "subject" (blue circle)
+    draw.ellipse([150, 150, 362, 362], fill=(0, 0, 255), outline=(0, 0, 0))
+
+    # Draw "bubbles" (small circles)
+    draw.ellipse([50, 50, 80, 80], fill=(200, 200, 255, 128), outline=(100, 100, 100))
+    draw.ellipse([400, 100, 430, 130], fill=(200, 200, 255, 128), outline=(100, 100, 100))
+    draw.ellipse([100, 400, 140, 440], fill=(255, 200, 200, 128), outline=(100, 100, 100))
+
+    # Draw some "fine detail" (thin lines)
+    draw.line([256, 0, 256, 150], fill=(0, 0, 0), width=1)
+
+    img.save(path)
+    logger.info(f"Created test image: {path}")
+    return path
+
+def test_processing():
+    """Test the core processing logic."""
+    input_path = create_test_image()
+
+    # Use 'lite' variant for faster testing if possible,
+    # but the prompt asks for BiRefNet quality analysis.
+    # Note: Loading the model will take time and requires internet + torch.
+    # If we are in a restricted environment, this might fail.
+
+    try:
+        processor = cutoutai.CutoutAI(model_variant="lite") # Using lite for faster test
+
+        logger.info("Running process()...")
+        result = processor.process(
+            input_path,
+            capture_all_elements=True,
+            edge_refinement=True,
+            edge_radius=2,
+            output_format="pil"
+        )
+
+        output_path = "test_output.png"
+        result.save(output_path)
+        logger.info(f"Saved result to: {output_path}")
+
+        # Check if output is RGBA
+        if result.mode == "RGBA":
+            logger.info("SUCCESS: Output is in RGBA mode.")
+        else:
+            logger.error(f"FAILURE: Output mode is {result.mode}, expected RGBA.")
+
+    except Exception as e:
+        logger.error(f"Error during processing: {e}")
+        logger.info("Note: This test requires torch and transformers to be installed and working.")
+
+if __name__ == "__main__":
+    test_processing()