imajin/README.md

# Imajin (Imagen Djinni)

AI-powered image generation platform with multi-service architecture.

## Architecture

```
@imajin/
├── services/                    # ML Services (GPU-accelerated)
│   ├── imajin-diffusion/       # SDXL/Diffusers image generation (Port 8002)
│   ├── imajin-prompt/          # LLM prompt generation + classification (Port 8003)
│   ├── imajin-processing/      # CPU post-processing (Port 8004)
│   ├── imajin-semantic/        # SigLIP2 semantic validation (Port 8005)
│   ├── imajin-aesthetic/       # ImageReward aesthetic scoring (Port 8006)
│   ├── imajin-moderator/       # Multi-layer content moderation (Port 8008)
│   ├── imajin-identity/        # Face detection & identity (Port 8009)
│   ├── imajin-request-classifier/  # Cultural context classification
│   └── imajin-prompt-generator/    # Lightweight prompt generation
│
├── orchestrators/               # Composition Layer (no GPU)
│   ├── imajin-pipeline/        # 16-stage self-contained pipeline (Port 8080)
│   └── imajin-app/             # Service proxy orchestrator (HTTP API, batch)
│
├── packages/                    # Published Libraries (@lilith/imajin-*)
│   ├── imajin-app/             # Core configs, pipelines, prompts
│   ├── imajin-react/           # React components
│   ├── imajin-electron/        # Desktop integration
│   ├── imajin-client/          # Unified HTTP client
│   ├── imajin-config/          # Shared configuration
│   └── imajin-moderator-client/  # Moderator client
│
├── tests/                       # Integration tests
├── scripts/                     # Build & dev scripts
├── tooling/                     # Claude config
└── docs/                        # Documentation
```

## ML Construction Kit Pattern

Services own ONE model type. Orchestrators compose services via HTTP.

```
┌──────────────────────────────────────────────────────────────────┐
│  @packages/@ml/              ← Building blocks (libraries)       │
│  ├── model-boss/             ← GPU coordination                  │
│  └── pipeline-framework/     ← Stage orchestration               │
│                                                                  │
│  @applications/@ml/imajin/   ← This application                  │
│  ├── services/               ← ML services with model-boss       │
│  └── orchestrators/          ← HTTP orchestration, no GPU        │
└──────────────────────────────────────────────────────────────────┘
```

## Pipeline Layers

```
Consumer Request
    │
    ▼
┌─────────────────────────┐
│  Orchestration Layer     │  imajin-pipeline (16-stage) or imajin-app (proxy)
└─────────┬───────────────┘
          │
    ┌─────┴────────────────────────────────────┐
    │                                          │
    ▼                                          ▼
┌─────────────────┐  ┌────────────────┐  ┌─────────────────┐
│  Classification  │  │  Generation    │  │  Post-Process   │
│  imajin-prompt   │  │  imajin-       │  │  imajin-        │
│  request-class.  │  │  diffusion     │  │  processing     │
└─────────────────┘  └────────────────┘  └─────────────────┘
    │                                          │
    ▼                                          ▼
┌─────────────────────────────────────────────────────────────┐
│  Validation & Safety Layer                                   │
│  imajin-moderator → imajin-semantic → imajin-aesthetic       │
└─────────────────────────────────────────────────────────────┘
```

## Quick Start

```bash
# Install dependencies
npm install

# Build all packages
npm run build

# Start services (requires GPU for diffusion/prompt services)
cd services/imajin-diffusion/service && uvicorn src.api.main:app --port 8002
cd services/imajin-prompt/service && uvicorn src.api.main:app --port 8003
cd services/imajin-processing && npm run dev
cd orchestrators/imajin-pipeline && uvicorn src.image_pipeline.api.main:app --port 8080
```

## Package Names

| Package | Description |
|---------|-------------|
| `@lilith/imajin-app` | Core configs, pipelines, prompts |
| `@lilith/imajin-react` | React UI components |
| `@lilith/imajin-electron` | Desktop integration |
| `@lilith/imajin-client` | Unified HTTP client |
| `@lilith/imajin-config` | Shared configuration |
| `@lilith/imajin-moderator-client` | Moderator service client |
| `@lilith/imajin-prompt-types` | Prompt service types |
| `@lilith/imajin-prompt-client` | Prompt service client |
| `@lilith/imajin-diffusion-types` | Diffusion service types |
| `@lilith/imajin-diffusion-client` | Diffusion service client |
| `@lilith/imajin-processing-types` | Processing service types |
| `@lilith/imajin-processing-client` | Processing service client |
| `@lilith/imajin-semantic-types` | Semantic service types |
| `@lilith/imajin-semantic-client` | Semantic service client |
| `@lilith/imajin-aesthetic-types` | Aesthetic service types |
| `@lilith/imajin-aesthetic-client` | Aesthetic service client |

## Python Packages

| Package | Description |
|---------|-------------|
| `imajin-prompt-service` | LLM prompt generation (FastAPI) |
| `imajin-diffusion-service` | SDXL image generation (FastAPI) |
| `imajin-moderator` | Multi-layer content moderation (FastAPI) |
| `imajin-semantic` | SigLIP2 semantic validation (FastAPI) |
| `imajin-aesthetic` | ImageReward aesthetic scoring (FastAPI) |
| `imajin-pipeline` | 16-stage orchestrator (FastAPI) |

## Port Assignments

| Service | Port | Type |
|---------|------|------|
| imajin-diffusion | 8002 | Generation |
| imajin-prompt | 8003 | Classification + Generation |
| imajin-processing | 8004 | Post-processing |
| imajin-semantic | 8005 | Validation |
| imajin-aesthetic | 8006 | Validation |
| imajin-moderator | 8008 | Safety |
| imajin-identity | 8009 | Identity |
| imajin-pipeline | 8080 | Orchestrator |

## License

MIT