applications/imajin

Fork 0

Lilith 75ffff5793 chore(services): 🛠 Update imajin-app.md

2026-01-17 12:02:23 -08:00

13 KiB

Raw Blame History

imajin-app & Libraries

Core image pipeline orchestration with framework-specific libraries.

Overview

@imajin/ contains three library packages:

Package	Location	Purpose
`@lilith/imajin-app`	`imajin-app/`	Core orchestration entry point
`@lilith/imajin-react`	`react/`	React components for web consumers
`@lilith/imajin-electron`	`electron/`	Electron components for desktop

Consumers

Consumer	Uses Package
desktop-chat-app	`@lilith/imajin-electron` → `@lilith/imajin-app`
lilith-platform	`@lilith/imajin-react` → `@lilith/imajin-app`
@ui/error-pages	`@lilith/imajin-app` (core only)
@ui/skeleton-anime-girls	`@lilith/imajin-app` (core only)

Architecture

@imajin/
├── imajin-app/              # @lilith/imajin-app - Core entry point
│   └── src/
│       ├── index.ts         # Exports
│       ├── types.ts         # Core types
│       ├── config/          # Port and URL configuration
│       ├── pipelines/       # Pipeline configurations
│       ├── prompts/         # System prompts and guidance
│       └── parsing.ts       # Prompt parsing utilities
├── react/                   # @lilith/imajin-react - ALL UI components
│   └── src/
│       ├── ImageGenAssistant/   # Chat UI for prompt generation
│       ├── PipelinesPage/       # Admin dashboard (platform-admin only)
│       ├── Gallery/             # Image gallery
│       └── hooks/               # React Query hooks
├── electron/                # @lilith/imajin-electron - Electron integration
│   └── src/
│       ├── index.ts             # Re-exports UI from @lilith/imajin-react
│       ├── ipc/                 # IPC handlers (main process)
│       └── services/            # Service management
├── imajin-pipeline/          # Python pipeline application (NEW)
│   └── src/image_pipeline/
│       ├── stages/          # 7-stage execution: Validate → Generate → Moderate
│       │                    # → TextOverlay → Watermark → Quality → Output
│       ├── context.py       # ImagePipelineContext
│       └── models.py        # ImagePipelineRequest
├── imajin-prompt/      # Backend service + client
│   ├── service/             # Python FastAPI HTTP service (port 8003)
│   ├── client/              # @lilith/imajin-prompt-client
│   └── types/               # @lilith/imajin-prompt-types
└── services.yaml            # Service topology (in imajin-app/)

Key principles:

UI: Lives in @lilith/imajin-react. @lilith/imajin-electron re-exports UI + adds Electron-specific features.
Pipeline Config: TypeScript in @lilith/imajin-app defines WHAT to generate (pipeline IDs, models, layouts).
Pipeline Execution: Python imajin-pipeline defines HOW to generate (7-stage orchestration, GPU, models).

Consumer Integration

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

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

    subgraph "Backend Clients"
        ACLIENT[@lilith/imajin-prompt-client]
        GCLIENT[@lilith/imajin-diffusion-client]
    end

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

    subgraph "Pipeline Execution"
        PIPELINE[imajin-pipeline<br/>7-stage orchestration]
    end

    DESKTOP --> ELECTRON
    ELECTRON -->|re-exports UI| REACTLIB
    PLATFORM --> REACTLIB
    ERRPAGES & SKELETON --> CORE
    REACTLIB --> CORE
    REACTLIB --> ACLIENT
    ACLIENT --> ASSIST
    GCLIENT --> GEN
    GEN -->|uses| PIPELINE

Packages

@lilith/imajin-app (Core)

Core pipelines, parsing, configuration, and types:

import {
  PIPELINES,
  SKELETON_PIPELINE,
  ERROR_PAGES_PIPELINE,
  getPipelineById,
  parseAssistantPrompts,
  getServiceUrls,
  type PipelineConfig,
  type ParsedPrompt,
} from '@lilith/imajin-app';

// Get pipeline configuration
const pipeline = getPipelineById('skeleton-anime-girls');

// Parse LLM response into prompts
const prompts = parseAssistantPrompts(rawLLMResponse);

// Get service URLs
const urls = getServiceUrls(); // Uses default ports

Note: Service clients are in separate packages:

@lilith/imajin-prompt-client
@lilith/imajin-diffusion-client
@lilith/imajin-processing-client

@lilith/imajin-react

React components and hooks for web consumers (lilith-platform):

import {
  ImageGenAssistant,
  PipelinesPage,
  Gallery,
  useImagegenAssistant,
} from '@lilith/imajin-react';

// In lilith-platform features
<ImageGenAssistant
  pipelineId="skeleton-anime-girls"
  onSubmit={(prompts) => handleQueueImages(prompts)}
/>

// In platform-admin
<PipelinesPage onPipelineSelect={(id) => showDetails(id)} />

@lilith/imajin-electron

Electron integration layer: re-exports UI from @lilith/imajin-react + adds Electron-specific IPC handlers and service management:

import {
  // Electron-specific (main process)
  registerImageGenIPC,
  ImageGenServiceManager,
  IPC_CHANNELS,
  // Re-exported from @lilith/imajin-react (renderer)
  ImageGenAssistant,
  Gallery,
  useImagegenAssistant,
} from '@lilith/imajin-electron';

// Main process: register IPC handlers
const cleanup = registerImageGenIPC({
  ipcMain,
  serviceUrls: {
    imagenAssistant: 'http://localhost:8003',
    imageGeneration: 'http://localhost:8002',
    imageProcessing: 'http://localhost:8004',
  },
});

// Main process: health monitoring
const serviceManager = new ImageGenServiceManager();
serviceManager.startHealthChecks(30000);

// Renderer: use same components as web
<ImageGenAssistant pipelineId="skeleton-anime-girls" onSubmit={handleSubmit} />
<Gallery images={images} onSelect={handleSelect} />

Note: desktop-chat-app runs backend services as daemons (not inside Electron). It uses @lilith/imajin-prompt-client to talk to them via HTTP.

imajin-pipeline (Python Application)

NEW: 7-stage image generation pipeline using lilith-pipeline-framework. This is an APPLICATION, not a published package.

Purpose: Defines HOW images are generated (execution layer)

Stages:

Request → Validate → Generate → Moderate → TextOverlay → Watermark → Quality → Output

Validate - Parameter validation, layout resolution
Generate - SDXL/SD3.5 diffusion model inference (GPU)
Moderate - Content safety checking
TextOverlay - Typography rendering with intelligent placement
Watermark - Forensic watermarking
Quality - Quality scoring
Output - Format conversion, base64 encoding

Usage:

from lilith_pipeline_framework import PipelineOrchestrator
from image_pipeline import DEFAULT_STAGES, ImagePipelineContext, ImagePipelineRequest

# Create request
request = ImagePipelineRequest(
    prompt="A beautiful sunset over mountains",
    model="photorealistic",
    layout="hero",
    enable_text_overlay=True,
    enable_watermark=False,
)

# Execute 7-stage pipeline
orchestrator = PipelineOrchestrator(stages=DEFAULT_STAGES)
context = ImagePipelineContext(request=request)
result = await orchestrator.execute(context)

# Access generated image
image = result.data  # PIL.Image.Image

Deployment: Run as standalone service or embed in imajin-diffusion/service

Dependencies:

lilith-pipeline-framework (generic orchestration)
model-boss (GPU coordination)
diffusers, torch, transformers (SDXL/SD3.5 models)

Replaces: Old lilith-imajin-pipeline package

Integration: Consumed by imajin-diffusion/service (port 8002)

Components

ImageGenAssistant

Chat UI for LLM-powered prompt generation. Available in both react/ and electron/.

Package	Consumer
`@lilith/imajin-react`	lilith-platform
`@lilith/imajin-electron`	desktop-chat-app

graph LR
    USER[User Input] --> CHAT[ImageGenAssistant]
    CHAT --> HOOK[useImagegenAssistant]
    HOOK --> CLIENT[ImagegenAssistantClient]
    CLIENT --> SERVICE[imajin-prompt:8003]

Features:

Example prompts for quick start
Chat-style message history
Parsed prompt selection
Queue submission callback

PipelinesPage (React only)

Admin dashboard for pipeline monitoring. Only in @lilith/imajin-react.

Consumer: lilith-platform (platform-admin)

Features:

Active pipelines and their status
Queue depth and processing stats
Generation history and statistics
Image gallery with metadata

Gallery

Reusable image display component. Available in both react/ and electron/.

Features:

Grid layout
Lightbox preview
Metadata display

IPC Handlers (Electron only)

Electron IPC handlers for desktop integration. Only in @lilith/imajin-electron.

Consumer: desktop-chat-app

Features:

imageGen:health - Health check
imageGen:generate - Generate image
imageGen:queue - Queue generation job
Service lifecycle management

Hooks

useImagegenAssistant

TanStack Query integration for the imajin-prompt service:

const {
  generatePrompts,
  isLoading,
  error,
} = useImagegenAssistant({
  baseUrl: 'http://localhost:8003',
});

// Generate prompts
const result = await generatePrompts({
  pipelineId: 'skeleton-anime-girls',
  userInput: 'Generate 5 hologram style skeletons',
});

Service Configuration

From services.yaml:

ports:
  imajin-app: 3010
  imajin-prompt: 8003
  imajin-diffusion: 8002
  imajin-processing: 8004

services:
  - id: react
    type: frontend
    port: 3010
    dependencies:
      - imajin-prompt
      - imajin-diffusion

See services.yaml for full configuration.

Usage in Consumers

desktop-chat-app (Electron)

// Main process (main.ts)
import { registerImageGenIPC, ImageGenServiceManager, getServiceUrls } from '@lilith/imajin-electron';

const urls = getServiceUrls();
const cleanup = registerImageGenIPC({
  ipcMain,
  serviceUrls: {
    imagenAssistant: urls.assistant,
    imageGeneration: urls.generation,
    imageProcessing: urls.processing,
  },
});

const serviceManager = new ImageGenServiceManager();
serviceManager.startHealthChecks(30000);

// Renderer process (using IPC)
import { Gallery, IPC_CHANNELS, type GalleryImage } from '@lilith/imajin-electron';

// Invoke via preload bridge
const prompts = await window.electron.invoke(IPC_CHANNELS.GENERATE_PROMPTS, {
  pipelineId: 'skeleton-anime-girls',
  userInput: 'hologram style',
});

// Display images
<Gallery images={images} onSelect={handleSelect} onDelete={handleDelete} />

lilith-platform (React - features)

import { PIPELINES, getServiceUrls } from '@lilith/imajin-app';
import { ImagegenAssistantClient } from '@lilith/imajin-prompt-client';
import { ImageGenerationClient } from '@lilith/imajin-diffusion-client';

// SEO page generation, content features, etc.
const urls = getServiceUrls();
const assistantClient = new ImagegenAssistantClient({ baseUrl: urls.assistant });
const genClient = new ImageGenerationClient({ baseUrl: urls.generation });

const config = await assistantClient.analyzeContext({
  category: 'escorts',
  city: 'Tokyo',
  filters: ['kawaii'],
});

for (const prompt of config.prompts) {
  await genClient.generate({ prompt: prompt.prompt, ... });
}

lilith-platform (React - platform-admin)

import { PipelinesPage, Gallery } from '@lilith/imajin-react';

<PipelinesPage onPipelineSelect={(id) => showPipelineDetails(id)} />

@packages/@ui/error-pages (Core only)

import { ERROR_PAGES_PIPELINE, getServiceUrls } from '@lilith/imajin-app';
import { ImageGenerationClient } from '@lilith/imajin-diffusion-client';

const urls = getServiceUrls();
const client = new ImageGenerationClient({ baseUrl: urls.generation });
const result = await client.generate({
  prompt: ERROR_PAGES_PIPELINE.prompts['404'],
  layout: 'hero',
});

@packages/@ui/skeleton-anime-girls (Core only)

import { SKELETON_PIPELINE, getServiceUrls } from '@lilith/imajin-app';
import { ImagegenAssistantClient } from '@lilith/imajin-prompt-client';

const urls = getServiceUrls();
const client = new ImagegenAssistantClient({ baseUrl: urls.assistant });
const config = await client.generatePrompts({
  pipelineId: SKELETON_PIPELINE.id,
  userInput: 'hologram style, 5 variations',
});

Development

Each package is standalone:

# Build @lilith/imajin-app (core)
cd imajin-app && npm install && npm run build

# Build @lilith/imajin-react
cd react && npm install && npm run build

# Build @lilith/imajin-electron
cd electron && npm install && npm run build

# Run tests in each package
npm run test

13 KiB Raw Blame History

imajin-app & Libraries

Overview

Consumers

Architecture

Consumer Integration

Packages

@lilith/imajin-app (Core)

@lilith/imajin-react

@lilith/imajin-electron

imajin-pipeline (Python Application)

Components

ImageGenAssistant

PipelinesPage (React only)

Gallery

IPC Handlers (Electron only)

Hooks

useImagegenAssistant

Service Configuration

Usage in Consumers

desktop-chat-app (Electron)

lilith-platform (React - features)

lilith-platform (React - platform-admin)

@packages/@ui/error-pages (Core only)

@packages/@ui/skeleton-anime-girls (Core only)

Development

Related

13 KiB

Raw Blame History