Lilith Content Understanding

Comprehensive image understanding for ML services. Provides content analysis capabilities shared between desktop-chat-app and other applications.

Features

Detectors

• NSFWDetector: Content safety classification using HuggingFace models (98.56% accuracy)
• BodyPartDetector: Anatomical detection with bounding boxes using NudeNet

Analyzers

• DepthAnalyzer: Monocular depth estimation using Depth Anything V2
• ColorAnalyzer: Color palette extraction with harmony and mood analysis
• CompositionAnalyzer: Rule of thirds, balance, focal points, and suggestions
• SceneClassifier: Scene type, environment, weather, and style suggestions using CLIP

REST API

• FastAPI service with endpoints for all detectors and analyzers
• Full analysis endpoint for comprehensive image understanding
• OpenAPI documentation included

Installation

# Basic installation
pip install lilith-content-understanding

# With body part detection (NudeNet)
pip install lilith-content-understanding[nudenet]

# With REST API service
pip install lilith-content-understanding[api]

# With all optional dependencies
pip install lilith-content-understanding[all]

# Development installation
pip install -e ".[dev]"

Usage

NSFW Detection

from PIL import Image
from lilith_content_understanding import NSFWDetector

detector = NSFWDetector()
image = Image.open("photo.jpg")

result = detector.classify(image)
print(f"NSFW: {result.is_nsfw}")
print(f"Confidence: {result.confidence:.2%}")
print(f"Category: {result.category}")

# Quick checks
is_explicit, confidence = detector.is_explicit(image)
is_suggestive, confidence = detector.is_suggestive(image)

Body Part Detection

from PIL import Image
from lilith_content_understanding import BodyPartDetector

detector = BodyPartDetector()
image = Image.open("photo.jpg")

result = detector.detect(image)
print(f"Has nudity: {result.has_nudity}")
print(f"Body parts: {result.body_parts_list}")
print(f"Gender presentation: {result.gender_presentation}")

# Get bounding boxes for specific parts (useful for inpainting)
breast_regions = result.get_bboxes_for_category("BREASTS")
for bbox in breast_regions:
    x1, y1, x2, y2 = bbox  # Normalized 0-1 coordinates
    print(f"Region: ({x1:.2f}, {y1:.2f}) to ({x2:.2f}, {y2:.2f})")

Depth Estimation

from PIL import Image
from lilith_content_understanding import DepthAnalyzer

analyzer = DepthAnalyzer()
image = Image.open("photo.jpg")

result = analyzer.estimate(image)
print(f"Depth range: {result.min_depth:.2f} to {result.max_depth:.2f}")

# Save visualization
result.save_visualization("depth.png", colormap="magma")

# Get foreground mask
foreground = result.get_foreground_mask(threshold=0.3)

# Segment into depth layers
layers = result.get_depth_layers(num_layers=3)

Color Palette Extraction

from PIL import Image
from lilith_content_understanding import ColorAnalyzer

analyzer = ColorAnalyzer()
image = Image.open("photo.jpg")

result = analyzer.extract_palette(image, num_colors=5)
print(f"Colors: {result.hex_colors}")
print(f"Harmony: {result.harmony_type}")
print(f"Mood: {result.mood}")

# Individual colors
for color in result.colors:
    print(f"{color.name}: {color.hex} ({color.percentage:.1f}%)")

# Create swatch image
swatch = result.to_swatch_image(width=500, height=100)
swatch.save("palette.png")

Composition Analysis

from PIL import Image
from lilith_content_understanding import CompositionAnalyzer

analyzer = CompositionAnalyzer()
image = Image.open("photo.jpg")

result = analyzer.analyze(image)
print(f"Rule of thirds: {result.rule_of_thirds_score:.2f}")
print(f"Balance: {result.balance_score:.2f} ({result.balance_type})")
print(f"Complexity: {result.complexity_score:.2f}")

# Focal points
for fp in result.focal_points:
    print(f"Focal point at ({fp.x:.2f}, {fp.y:.2f}) strength={fp.strength:.2f}")

# Improvement suggestions
for suggestion in result.suggestions:
    print(f"- {suggestion}")

Scene Classification

from PIL import Image
from lilith_content_understanding import SceneClassifier

classifier = SceneClassifier()
image = Image.open("photo.jpg")

result = classifier.classify(image)
print(f"Scene: {result.scene_type} ({result.scene_confidence:.1%})")
print(f"Environment: {result.environment}")
print(f"Time of day: {result.time_of_day}")
print(f"Weather: {result.weather}")
print(f"Tags: {result.tags}")
print(f"Suggested styles: {result.suggested_styles}")

Configuring Thresholds

# Custom NSFW thresholds
detector = NSFWDetector(
    nsfw_threshold=0.8,      # Higher = fewer false positives
    suggestive_threshold=0.5,
    device="cuda",           # Force GPU
)

# Custom body part detection threshold
detector = BodyPartDetector(
    threshold=0.5,  # Higher = fewer detections, more confident
)

# Different depth model
analyzer = DepthAnalyzer(
    model_name="depth-anything-v2-base",  # More accurate, slower
)

REST API

Run the service:

uvicorn lilith_content_understanding.api:app --host 0.0.0.0 --port 8002

Endpoints:

• GET /health - Health check
• POST /detect/nsfw - NSFW detection
• POST /detect/body-parts - Body part detection
• POST /analyze/depth - Depth estimation
• POST /analyze/colors - Color palette extraction
• POST /analyze/composition - Composition analysis
• POST /analyze/scene - Scene classification
• POST /analyze/full - Combined analysis

API documentation at http://localhost:8002/docs

Use Cases

Image Generation (desktop-chat-app)

• Pre-screen uploaded reference images
• Validate generated content before display
• Enable targeted inpainting with body part regions
• Extract color palettes for style matching
• Depth-aware composition suggestions

Content Platform

• Content moderation pipeline
• Accurate content categorization
• Trans-inclusive gender detection
• Automatic scene tagging

Architecture

src/lilith_content_understanding/
├── __init__.py              # Main exports
├── detectors/
│   ├── nsfw_detector.py     # HuggingFace NSFW classification
│   └── body_part_detector.py # NudeNet body detection
├── analyzers/
│   ├── depth_analyzer.py    # Depth Anything V2 estimation
│   ├── color_analyzer.py    # K-means color extraction
│   ├── composition_analyzer.py # Composition analysis
│   └── scene_classifier.py  # CLIP scene classification
└── api/
    └── service.py           # FastAPI service

Models Used

Component	Model	Notes
NSFW	Marqo/nsfw-image-detection-384	98.56% accuracy, primary
NSFW	Falconsai/nsfw_image_detection	98.04% accuracy, fallback
Body Parts	NudeNet 320n	Object detection with bboxes
Depth	Depth Anything V2 Small	State-of-the-art depth estimation
Scene	CLIP ViT-Base	Zero-shot classification

Documentation

See the docs/ directory for detailed documentation:

• Getting Started
• Detectors
• Analyzers
• REST API
• Architecture
• Contributing

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Type checking
mypy src

# Linting
ruff check src tests
ruff format src tests

License

MIT