History

Lilith e91a922931 feat(orchestrators/imajin-pipeline): implement PersonAppearance API and ControlNet integration Implements high-level PersonAppearance API for controlling person generation with pose and clothing specifications. Translates simple user requests into ControlNet configurations automatically. Core Implementation: - PersonAppearanceRequest model (pose + clothing control) - AppearanceToControlNet translator (549 lines) - Handles pose presets: standing, sitting, walking, running - Handles custom pose references (base64/URL) - Handles pose keypoints (advanced users) - Handles clothing body part mapping - Lazy-loads preprocessor and segmentation generator - SegmentationGenerator (400 lines) - Template-based RGB mask generation (MVP) - 7 body parts with color mapping - Three-phase roadmap: template → pose-aware → ML-based - ControlNetManager (model loading and caching) - ControlNetPreprocessor (OpenPose preprocessing) - ImageConditioningStage (pipeline integration) - Executes between VALIDATE and GENERATE stages - Translates PersonAppearance → ControlNet - Priority: Direct ControlNetConfig > PersonAppearanceRequest - GenerateStage extensions (multi-ControlNet support) - AnatomyFixStage skip logic (when ControlNet active) Testing (71 tests, 100% passing): - test_appearance_translator.py (23 tests) - test_segmentation_generator.py (35 tests) - test_controlnet_manager.py (unit tests) - test_controlnet_preprocessor.py (unit tests) - test_image_conditioning_stage.py (13 tests) - test_anatomy_fix_skip_logic.py (9 tests) - test_person_appearance_api.py (13 integration tests) - test_controlnet_generation.py (integration tests) - test_controlnet_backward_compat.py (integration tests) Documentation (1600 lines): - docs/person-appearance-api.md (1000 lines) - Complete API reference - Quick start with progressive examples - Pose control, clothing control, use cases - Python/cURL/TypeScript integration patterns - Performance and troubleshooting - docs/segmentation_masks.md (600 lines) - Body part mapping and RGB colors - Template vs pose-aware vs ML strategies Examples: - Preset pose examples - Custom pose examples - Clothing specification examples - Combined pose + clothing examples Assets: - Preset pose library (4 synthetic OpenPose skeletons) - Generation script for preset poses Files Changed: - Modified: models.py, context.py, generate.py, anatomy_fix.py, __init__.py - Created: appearance_translator.py, segmentation_generator.py, controlnet_manager.py, controlnet_preprocessor.py, image_conditioning.py - Tests: 9 new test files (unit + integration) - Docs: 2 comprehensive guides - Examples: 5 example scripts - Assets: 4 preset pose images MVP Scope: Pose + clothing control Future Phases: Physical features (ethnicity, hair, eyes) in separate stream Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>		2026-01-14 07:33:56 -08:00
..
architecture	feat(@ml/imajin): ✨ integrate post-processing flow and update documentation	2026-01-13 04:18:42 -08:00
development	feat(imajin): ✨ update documentation and service structure	2026-01-10 05:04:48 -08:00
operations	feat(imajin): ✨ update documentation and service structure	2026-01-10 05:04:48 -08:00
services	feat(@ml/imajin): ✨ integrate post-processing flow and update documentation	2026-01-13 04:18:42 -08:00
person-appearance-api.md	feat(orchestrators/imajin-pipeline): implement PersonAppearance API and ControlNet integration	2026-01-14 07:33:56 -08:00
README.md	feat(imajin): ✨ update documentation and service structure	2026-01-10 05:04:48 -08:00

README.md

@image Documentation

AI-powered image generation platform with diffusion models, LLM prompt engineering, and post-processing capabilities.

Architecture Overview

graph TB
    subgraph "Consumer Applications"
        DESKTOP[desktop-chat-app]
        PLATFORM[lilith-platform]
        ERRPAGES[@ui/error-pages]
        SKELETON[@ui/skeleton-anime-girls]
    end

    subgraph "@image Libraries"
        ELECTRON[electron/<br/>@lilith/imajin-electron]
        REACTLIB[react/<br/>@lilith/imajin-react]
        CORE[imajin-app/<br/>@lilith/imajin-app]
    end

    subgraph "Backend Services"
        ASSIST[imajin-prompt :8003]
        GEN[imajin-diffusion :8002]
        PROC[imajin-processing :8004]
    end

    subgraph "Infrastructure"
        REDIS[(Redis/GPUBoss)]
        GPU[GPU/CUDA]
    end

    DESKTOP --> ELECTRON
    PLATFORM --> REACTLIB
    ERRPAGES & SKELETON --> CORE
    ELECTRON & REACTLIB --> CORE
    CORE --> ASSIST & GEN & PROC
    ASSIST & GEN --> REDIS --> GPU

Key consumers:

desktop-chat-app - End-user image generation in chat conversations
lilith-platform - Image generation features + platform-admin for orchestration oversight
@packages/@ui - Shared UI packages (error-pages, skeleton-anime-girls)

Section	Description
Architecture	System design, service topology, data flow
Services	Individual service documentation
Development	Getting started, client libraries, testing
Operations	Configuration, GPU coordination, ports

Components at a Glance

Component	Type	Technology	Purpose
imajin-app	Library	TypeScript	Core orchestration entry point
react/	Library	React	UI components for web consumers
electron/	Library	Electron	Components for desktop consumers
imajin-prompt	Service	Python/FastAPI	LLM prompt generation
imajin-diffusion	Service	Python/FastAPI	Diffusion model image generation
imajin-processing	Service	NestJS/Sharp	Image post-processing

Existing Documentation

Detailed documentation exists in each service directory:

imajin-diffusion/README.md - Full API reference, models, layouts
imajin-diffusion/INTEGRATION.md - Desktop/Electron integration
imajin-prompt/CONFIG.md - Configuration architecture
imajin-app/services.yaml - Port definitions, environments

Repository Structure

@image/
├── imajin-app/            # Core orchestration entry point
│   └── src/               # @lilith/imajin-app (pipelines, types, clients)
├── react/                 # React components for web consumers
│   └── src/               # @lilith/imajin-react (UI components, hooks)
├── electron/              # Electron components for desktop consumers
│   └── src/               # @lilith/imajin-electron (IPC, service management)
├── imajin-diffusion/      # Diffusion model image generation service
│   ├── service/           # Python FastAPI backend
│   ├── types/             # @lilith/imajin-diffusion-types
│   └── client/            # @lilith/imajin-diffusion-client
├── imajin-processing/      # Image post-processing service
│   ├── service/           # NestJS backend
│   ├── types/             # @lilith/imajin-processing-types
│   └── client/            # @lilith/imajin-processing-client
├── imajin-prompt/    # LLM prompt generation service
│   ├── service/           # Python FastAPI backend
│   ├── types/             # TypeScript types
│   └── client/            # @lilith/imajin-prompt-client
├── utils/                 # Shared Python utilities
└── docs/                  # This documentation

Consumer Integration

imajin-app is a library, not a standalone app. Consumers:

Consumer	Uses imajin-app for
desktop-chat-app	Image generation in chat conversations
lilith-platform	Image generation features (SEO pages, content, etc.)
lilith-platform (platform-admin)	Pipeline monitoring & orchestration management
@packages/@ui/error-pages	Generated error page images
@packages/@ui/skeleton-anime-girls	Skeleton loading state images

Getting Started

New to the project? Start with Getting Started
Integrating imajin-app? See Client Libraries
Deploying services? Check Configuration