Files
2026-10-12 20:25:07 +03:00

16 KiB
Raw Permalink Blame History

app.py Reference Documentation

This document provides a comprehensive reference for all methods, variables, and configurations in app.py (540 lines). It is designed for agent systems to understand and interact with the e621tagger Flask application.


File Overview

Attribute Value
Location app.py
Lines 540
Framework Flask
Purpose Web application for e621 image tagging
Dependencies flask, flask-limiter, torch, PIL, ua-parser

File Structure Flow

app.py
├── 1. Imports (lines 1-18)
│   └── Standard library + Flask + ML dependencies
│
├── 2. Global Constants (lines 20-83)
│   ├── TAG_CATEGORIES - Tag ID to name mapping
│   ├── SUBCATEGORY_DISPLAY_NAMES - Subcategory code to display name
│   ├── APP_CONFIG - Version, logging, app setup
│   ├── MODEL_CONFIG - Model paths and device settings
│   ├── FILE_LIMITS - Upload and file type limits
│   └── Flask + Limiter initialization
│
├── 3. Helper Functions (lines 84-163)
│   └── Logging and user agent utilities
│
├── 4. Request Hooks (lines 165-227)
│   ├── @before_request - Start timing
│   └── @after_request - Security headers + logging
│
├── 5. Startup (lines 229-251)
│   ├── Directory creation
│   ├── Model loading
│   └── Metadata loading
│
├── 6. Validation Functions (lines 253-265)
│   ├── is_valid_image() - Verify image
│   └── is_allowed_file() - Check extension/MIME
│
├── 7. Processing Functions (lines 267-341)
│   ├── detect_meta_tags_for_image_path() - Auto tags
│   └── save_upload() - File persistence
│
├── 8. Flask Routes (lines 343-537)
│   └── 10 endpoints (+ error handler)
│
└── 9. Main Entry (lines 539-540)
    └── Production run

1. Global Constants

Tag Categories

TAG_CATEGORIES = {
    "general": "General",
    "artist": "Artist",
    "contributor": "Contributor",
    "copyright": "Copyright",
    "character": "Character",
    "species": "Species",
    "invalid": "Invalid",
    "meta": "Meta",
    "lore": "Lore",
}
Usage Map tag category string keys to e621 category display names

Note: The Label class in hydra/label.py uses integer category IDs (0-8, 100-111). The TAG_CATEGORIES dict here maps string keys for the 9 base categories. Subcategories (100-111) are handled via SUBCATEGORY_DISPLAY_NAMES.

Subcategory Display Names

SUBCATEGORY_DISPLAY_NAMES = {
    "accessory": "Accessories, Items, Clothing",
    "action": "Actions, Positions, State",
    "color": "Body Color",
    "body_feature": "Body Features",
    "effect": "Effects, Fluids",
    "fetish": "Fetishes, Specifics, Interactions",
    "demographic": "Genders, Demographics",
    "setting": "Locations, Backgrounds, Setting",
    "pose": "Poses, Scenarios, Situations",
    "style": "Style, Perspective",
    "text": "Text, Symbols, UI, Vocalization",
    "other": "Other",
}
Usage Map internal subcategory codes to display names for the API response and UI

Application Configuration

APP_VERSION = os.getenv('APP_VERSION', 'test')
LOG_LEVEL = logging.DEBUG if APP_VERSION.startswith('test-') else logging.INFO
Variable Default Description
APP_VERSION test Version string (set by Docker build)
LOG_LEVEL DEBUG/test, INFO/prod Logging level based on version

Flask Application

app = Flask(__name__)
app.config['MAX_CONTENT_LENGTH'] = 20 * 1024 * 1024
Config Value Description
MAX_CONTENT_LENGTH 20MB Maximum upload file size

Rate Limiter

limiter = Limiter(
    get_remote_address,
    app=app,
    default_limits=["500 per hour"],
    storage_uri="memory://",
)
Limit Scope
500/hour All endpoints
20/minute /predict (decorated)

Model Configuration

MODEL_PATH = os.getenv('MODEL_PATH', 'models/hydra-3.5.safetensors')
DEVICE = os.getenv('DEVICE', 'cuda' if torch.cuda.is_available() else 'cpu')
MAX_SEQ_LEN = int(os.getenv('MAX_SEQ_LEN', '1024'))
PATCH_SIZE = 16
Variable Default Description
MODEL_PATH models/hydra-3.5.safetensors Model file location
DEVICE cuda/cpu PyTorch device
MAX_SEQ_LEN 1024 Max patches for input
PATCH_SIZE 16 Patch size (pixels)

Prediction Settings

DEFAULT_TOP_K = 200
ALLOWED_TOP_K = {50, 75, 100, 150, 200, 300}
Variable Value Description
DEFAULT_TOP_K 200 Default tag count
ALLOWED_TOP_K {50,75,100,150,200,300} Valid top_k values

File Handling

SAVE_UPLOADS = os.getenv('SAVE_UPLOADS', 'false').lower() == 'true'
UPLOAD_DIR = os.getenv('UPLOAD_DIR', '/app/uploads')
ALLOWED_EXTENSIONS = {'.jpg', '.jpeg', '.png', '.gif', '.webp', '.bmp', '.tiff'}
ALLOWED_MIME_TYPES = {'image/jpeg', 'image/png', 'image/gif', 'image/webp', 'image/bmp', 'image/tiff'}
Variable Default Description
SAVE_UPLOADS false Save uploads to disk
UPLOAD_DIR /app/uploads Upload save directory
ALLOWED_EXTENSIONS 7 formats Valid file extensions
ALLOWED_MIME_TYPES 7 MIME types Valid MIME types

Blocked Tags

BLOCKED_TAGS = {'mature'}
Variable Default Description
BLOCKED_TAGS {'mature'} Set of tag names to exclude from API response. Add deprecated/undesired tags here to prevent them from being returned to clients.

2. Helper Functions

secure_log(s: str | None) -> str

Location app.py:84-89
Input `s: str
Output str - Sanitized string
Purpose Remove control characters and newlines from log strings
def secure_log(s: str | None) -> str:
    if not s:
        return ""
    s = s.replace('\r\n', ' ').replace('\n', ' ').replace('\r', ' ')
    s = re.sub(r'[\x00-\x1f\x7f\u0080-\u009f\u200b\u202e\u2066-\u2069]', '', s)
    return s.strip()

status_emoji(status_code) -> str

Location app.py:91-97
Input status_code: int - HTTP status code
Output str - Emoji (🟢/🟡/🔴)
Purpose Get status emoji for logging
Status Range Emoji
200-299 🟢
300-399 🟡
400+ 🔴

get_country_flag(accept_lang) -> str

Location app.py:99-107
Input accept_lang: str - Accept-Language header
Output str - Country flag emoji
Purpose Extract country code from Accept-Language header

get_ip_identifier(ip: str | None) -> str

Location app.py:109-119
Input ip: str - IP address string
Output str - Colored IP identifier (e.g., "🟪 192.168.1.1")
Purpose Generate consistent color + IP string for logging

The function uses a simple hash of the IP's octets to generate a consistent color. Same IP always maps to same color.

Hash Index Emoji Color
0 ⬛️ Black
1 🟫 Brown
2 🟪 Purple
3 🟦 Blue
4 🟩 Green
5 ⬜ White
6 🟨 Yellow
7 🟧 Orange
8 🟥 Red

parse_user_agent(ua_str: str) -> tuple[str, str]

Location app.py:121-163
Input ua_str: str - User-Agent string
Output tuple[str, str] - (device_type, ua_string)
Purpose Parse User-Agent string into device type and short UA
Device Type Detection
bot spider, bot, crawler
mobile smartphone, or "mobile" in UA
tablet tablet
desktop default

3. Request Hooks

@app.before_request

Location app.py:165-167
Purpose Start request timing for duration tracking
Sets g.start_time - Request start timestamp

@app.after_request

Location app.py:169-227
Purpose Add security headers and request logging
Headers Added HSTS, X-Frame-Options, CSP, etc.

Security Headers Added:

Header Value
Strict-Transport-Security max-age=31536000; includeSubDomains
X-Frame-Options DENY
X-Content-Type-Options nosniff
Referrer-Policy strict-origin-when-cross-origin
Permissions-Policy geolocation=(), microphone=(), camera=()
Content-Security-Policy default-src 'self'; img-src 'self' data: blob:; script-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self' https://e621.net; object-src 'none'; base-uri 'self';

4. Image Validation Functions

is_valid_image(file) -> bool

Location app.py:253-261
Input file - File-like object
Output bool - True if valid image
Purpose Verify file is a valid image
def is_valid_image(file):
    try:
        file.seek(0)
        img = Image.open(file)
        img.verify()
        file.seek(0)
        return True
    except Exception:
        return False

is_allowed_file(filename: str, content_type: str) -> bool

Location app.py:263-265
Input filename: str, content_type: str
Output bool - True if allowed
Purpose Check file extension and MIME type

5. Processing Functions

detect_meta_tags_for_image_path(image_path: str) -> set[str]

Location app.py:267-323
Input image_path: str - Path to image file
Output set[str] - Auto-detected meta tags
Purpose Generate meta tags from image properties
Tag Condition
animated GIF with n_frames > 1
thumbnail w ≤ 250 and h ≤ 250
low_res w ≤ 500 and h ≤ 500
hi_res w ≥ 1600 or h ≥ 1200
absurd_res w ≥ 3200 or h ≥ 2400
4k Exact 3840x2160/4096x2160 variants
superabsurd_res w ≥ 10000 and h ≥ 10000
long_image ratio ≥ 4:1 or ≤ 1:4
tall_image ratio ≤ 1:4
1:1, 2:1, 16:9, etc. Exact aspect ratios
widescreen 16:9 or ~16:10

Note: The current year tag (e.g., 2025, 2026) is added separately in the /predict endpoint after calling this function. It is not part of detect_meta_tags_for_image_path().

save_upload(file, original_filename) -> str | None

Location app.py:325-341
Input file, original_filename: str
Output str - Save path, or None on failure
Purpose Save uploaded file to disk
Requirement SAVE_UPLOADS=true

6. Flask Routes

index() -> str

Location app.py:348-350
Route GET /
Output HTML - Rendered index.html
Purpose Main UI page

favicon() -> Response

Location app.py:352-356
Route GET /favicon.ico
Output ICO file with 24h caching
Purpose Serve favicon

static_files(filename: str) -> Response

Location app.py:358-362
Route GET /static/<path>
Input filename: str - File path
Output Static file with 24h caching
Purpose Serve CSS, JS, icons

service_worker() -> Response

Location app.py:364-371
Route GET /service-worker.js
Output JS with no-cache headers
Purpose PWA service worker

health() -> tuple

Location app.py:373-389
Route GET /health
Output JSON - Health status
Purpose Health check endpoint

Healthy Response:

{
  "status": "healthy",
  "model": "JTP-3 Hydra 3.5",
  "tags_count": 8888,
  "version": "APP_VERSION"
}

Unhealthy Response (503):

{
  "status": "unhealthy",
  "reason": "model not loaded"
}

predict() -> tuple

Location app.py:391-509
Route POST /predict
Rate Limit 20/minute
Input image file (multipart/form-data), optional top_k
Output JSON - Tag predictions

Request Parameters:

Parameter Type Required Description
image file Yes Image file
top_k int No Number of tags (50-300, default 200)

Success Response:

{
  "success": true,
  "tags": [
    {"tag": "female", "prob": 0.95, "category": "General"},
    {"tag": "anthro", "prob": 0.89, "category": "Species"}
  ],
  "auto_meta": ["hi_res", "16:9", "2025"]
}

Note: The auto_meta array includes the current year (e.g., 2025, 2026) as a meta tag with 1.0 confidence. Frontend can filter this via the addCurrentYearTag setting (default: true).

Error Responses:

Status Error Message
400 "No image provided"
400 "Empty filename"
400 "File type not allowed"
400 "Invalid or corrupted image file"
413 "File too large. Maximum size is 20MB."
500 "Internal server error"

robots() -> Response

Location app.py:514-523
Route GET /robots.txt
Output Robots.txt content
Purpose Search engine instructions

Content:

User-agent: *
Disallow: /predict
Disallow: /health
Disallow: /service-worker.js

Sitemap: https://www.tagger.fenrir784.app/sitemap.xml

sitemap() -> Response

Location app.py:525-537
Route GET /sitemap.xml
Output XML sitemap
Purpose SEO sitemap

handle_file_too_large(e) -> tuple

Location app.py:343-346
Handler 413 errors
Purpose Handle file too large

7. Runtime Initialization

These run at module load time (lines 229-251):

# 1. Create upload directory
if SAVE_UPLOADS:
    os.makedirs(UPLOAD_DIR, exist_ok=True)

# 2. Load ML model — labels come from safetensors metadata
model = hydra_load_model(MODEL_PATH)

# 3. Convert dtype based on device
if DEVICE == 'cpu':
    model = model.float()  # float32 for CPU
else:
    model = model.to(dtype=torch.bfloat16, device=DEVICE)  # bfloat16 for GPU

# 4. Set model to inference mode
model.requires_grad_(False)
model.eval()

Global Runtime Objects

Object Type Description
model Hydra Loaded ML model
tag_list list[str] All tag names (8,888 in Hydra 3.5)
_SUBCATEGORY_MAP dict 6,263 general → subcategory mappings (in _subcat.py)

8. Entry Point

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000, debug=False)
Setting Value Description
Host 0.0.0.0 Accept all interfaces
Port 5000 Default port
debug False Production mode

Quick Reference for Agents

Calling the API

# Health check
curl http://localhost:5000/health

# Tag an image
curl -X POST -F "[email protected]" \
     -F "top_k=200" \
     http://localhost:5000/predict

Environment Variables

Variable Required Description
APP_VERSION No Version string
MODEL_PATH No Model file path
DEVICE No cuda or cpu
MAX_SEQ_LEN No Max patches

Error Handling

The app returns different HTTP status codes:

  • 200: Success
  • 400: Bad request (missing file, invalid type)
  • 413: File too large
  • 429: Rate limit exceeded
  • 500: Internal error

Logging

All logs include timestamp, level, and emoji prefix:

  • 🚀 - Startup/version
  • ⚙️ - Loading
  • ✅ - Success
  • ⚠️ - Warning
  • ❌ - Error
  • 📥 - Upload
  • 📤 - Prediction request
  • 👤 - Page view