| # 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) | |