Metadata-Version: 2.4
Name: fastsdcpu-pip
Version: 0.1.6
Summary: Fast stable diffusion on CPU and AI PC ported to a pip module
Home-page: https://github.com/Flyns157/fastsdcpu/pip
Author: Cuisset Mattéo
Author-email: matteo.cuisset@gmail.com
License: MIT AND (Apache-2.0 OR BSD-2-Clause)
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: THIRD-PARTY-LICENSES
License-File: LICENSE
Requires-Dist: accelerate
Requires-Dist: diffusers
Requires-Dist: transformers
Requires-Dist: PyQt5
Requires-Dist: Pillow
Requires-Dist: openvino
Requires-Dist: optimum-intel[diffusers,openvino]
Requires-Dist: onnx
Requires-Dist: numpy
Requires-Dist: onnxruntime
Requires-Dist: pydantic
Requires-Dist: typing-extensions
Requires-Dist: pyyaml
Requires-Dist: gradio
Requires-Dist: peft
Requires-Dist: opencv-python
Requires-Dist: omegaconf
Requires-Dist: controlnet-aux
Requires-Dist: tomesd
Requires-Dist: mcp
Requires-Dist: fastapi-mcp
Requires-Dist: torch<=2.8
Requires-Dist: huggingface_hub[hf_xet]
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Documentation fastsdcpu-pip

## Table des matiÃ¨res

1. [Introduction](#introduction)
2. [Installation](#installation)
3. [Architecture du module](#architecture-du-module)
4. [Modes d'optimisation](#modes-doptimisation)
5. [Utilisation](#utilisation)
6. [Configuration avancÃ©e](#configuration-avancÃ©e)
7. [API Reference](#api-reference)
8. [Exemples pratiques](#exemples-pratiques)

---

## Introduction

`fastsdcpu-pip` est un module Python conÃ§u pour exÃ©cuter des modÃ¨les **Stable Diffusion** de maniÃ¨re optimisÃ©e sur **CPU** et **AI PC** (PC avec accÃ©lÃ©rateurs IA). Il s'agit d'une adaptation du projet [fastsdcpu](https://github.com/rupeshs/fastsdcpu) sous forme de package pip.

### CaractÃ©ristiques principales

- **Optimisations CPU** : Utilisation de modÃ¨les LCM (Latent Consistency Models) pour une infÃ©rence rapide
- **Support OpenVINO** : Optimisations spÃ©cifiques pour les processeurs Intel et NPU
- **Support GGUF** : ModÃ¨les quantifiÃ©s pour une utilisation efficace de la mÃ©moire
- **Modes multiples** : CLI, API Web, serveur MCP
- **FlexibilitÃ©** : Text-to-Image, Image-to-Image, ControlNet, LoRA, upscaling

### PrÃ©requis

- Python â‰¥ 3.11
- CPU moderne (Intel/AMD/Apple Silicon)
- 8 GB RAM minimum (16 GB recommandÃ©)
- Optionnel : NPU Intel pour accÃ©lÃ©ration matÃ©rielle

---

## Installation

### Installation standard

```bash
pip install fastsdcpu-pip
```

### Installation depuis les sources

```bash
git clone https://github.com/Flyns157/fastsdcpu.git
cd fastsdcpu/pip
pip install -e .
```

### DÃ©pendances principales

Le module installe automatiquement :
- `diffusers` : Pipelines Stable Diffusion
- `transformers` : ModÃ¨les de langage (CLIP, T5)
- `torch` : Framework de deep learning
- `openvino` + `optimum-intel` : Optimisations Intel
- `onnxruntime` : Runtime ONNX
- `peft` : Support LoRA
- `controlnet-aux` : PrÃ©processeurs ControlNet

---

## Architecture du module

### Structure des rÃ©pertoires

```
fastsdcpu-pip/
â”œâ”€â”€ configs/               # Fichiers de configuration
â”‚   â”œâ”€â”€ lcm-models.txt        # Liste des modÃ¨les LCM
â”‚   â”œâ”€â”€ lcm-lora-models.txt   # Liste des modÃ¨les LCM-LoRA
â”‚   â”œâ”€â”€ openvino-lcm-models.txt
â”‚   â””â”€â”€ stable-diffusion-models.txt
â”œâ”€â”€ fastsdcpu/             # Code source principal
â”‚   â”œâ”€â”€ annotators/           # PrÃ©processeurs ControlNet
â”‚   â”œâ”€â”€ api/                  # Serveurs API (Web, MCP)
â”‚   â”œâ”€â”€ models/               # ModÃ¨les de donnÃ©es (Pydantic)
â”‚   â”œâ”€â”€ pipelines/            # Pipelines de diffusion
â”‚   â”‚   â”œâ”€â”€ lcm/                 # Pipelines LCM/LoRA
â”‚   â”‚   â””â”€â”€ openvino/            # Pipelines OpenVINO
â”‚   â”œâ”€â”€ upscaler/             # Modules d'upscaling
â”‚   â”œâ”€â”€ utils/                # Utilitaires
â”‚   â”œâ”€â”€ app.py                # Point d'entrÃ©e CLI
â”‚   â”œâ”€â”€ context.py            # Gestion du contexte d'exÃ©cution
â”‚   â”œâ”€â”€ state.py              # Ã‰tat global de l'application
â”‚   â””â”€â”€ gguf_diffusion.py     # Wrapper GGUF (stable-diffusion.cpp)
â”œâ”€â”€ models/                # Dossier pour les modÃ¨les
â”‚   â”œâ”€â”€ controlnet_models/
â”‚   â”œâ”€â”€ lora_models/
â”‚   â””â”€â”€ gguf/
â”‚       â”œâ”€â”€ clip/
â”‚       â”œâ”€â”€ diffusion/
â”‚       â”œâ”€â”€ t5xxl/
â”‚       â””â”€â”€ vae/
â””â”€â”€ scripts/               # Scripts utilitaires
```

### Composants clÃ©s

#### 1. **Context** (`context.py`)
GÃ¨re le cycle de vie de gÃ©nÃ©ration d'images :
- Initialise les pipelines de diffusion
- Mesure la latence
- GÃ¨re les erreurs
- Sauvegarde les images

#### 2. **AppSettings** (`app_settings.py`)
Gestion de la configuration :
- Chargement/sauvegarde des paramÃ¨tres (YAML)
- Liste des modÃ¨les disponibles
- ParamÃ¨tres par dÃ©faut

#### 3. **LCMTextToImage** (`pipelines/lcm/text_to_image.py`)
CÅ“ur du systÃ¨me de gÃ©nÃ©ration :
- Initialisation des pipelines (LCM, OpenVINO, GGUF)
- GÃ©nÃ©ration d'images (text-to-image, image-to-image)
- Gestion des optimisations (FreeU, Token Merging, TAESD)

#### 4. **State Management** (`state.py`)
Singleton global pour :
- `get_settings()` : AccÃ¨s aux paramÃ¨tres
- `get_context()` : AccÃ¨s au contexte d'exÃ©cution
- `get_safety_checker()` : Filtre de contenu NSFW

---

## Modes d'optimisation

### 1. LCM (Latent Consistency Models)

**Principe** : ModÃ¨les distillÃ©s permettant une gÃ©nÃ©ration en 1-4 Ã©tapes.

**Avantages** :
- InfÃ©rence trÃ¨s rapide (1-2 secondes sur CPU moderne)
- Bonne qualitÃ© d'image
- Compatible avec tous les processeurs

**Utilisation** :
```python
from fastsdcpu.state import get_settings, get_context
from fastsdcpu.models.interface_types import InterfaceType

settings = get_settings()
context = get_context(InterfaceType.CLI)

# Configuration LCM
settings.settings.lcm_diffusion_setting.lcm_model_id = "stabilityai/sd-turbo"
settings.settings.lcm_diffusion_setting.use_lcm_lora = False
settings.settings.lcm_diffusion_setting.use_openvino = False

# GÃ©nÃ©ration
images = context.generate_text_to_image(settings.settings)
```

**ModÃ¨les recommandÃ©s** :
- `stabilityai/sd-turbo` (SD 1.5, 512x512)
- `stabilityai/sdxl-turbo` (SDXL, 1024x1024)
- `SimianLuo/LCM_Dreamshaper_v7`

### 2. LCM-LoRA

**Principe** : Adaptateurs LoRA permettant d'utiliser n'importe quel modÃ¨le Stable Diffusion avec la vitesse LCM.

**Avantages** :
- Compatible avec des milliers de modÃ¨les existants
- Personnalisation facile
- Supporte les fichiers `.safetensors` locaux

**Utilisation** :
```python
settings.settings.lcm_diffusion_setting.use_lcm_lora = True
settings.settings.lcm_diffusion_setting.lcm_lora.base_model_id = "Lykon/dreamshaper-8"
settings.settings.lcm_diffusion_setting.lcm_lora.lcm_lora_id = "latent-consistency/lcm-lora-sdv1-5"
```

**ModÃ¨les de base populaires** :
- `Lykon/dreamshaper-8`
- `runwayml/stable-diffusion-v1-5`
- `stabilityai/stable-diffusion-xl-base-1.0`

### 3. OpenVINO

**Principe** : Optimisations Intel utilisant le toolkit OpenVINO pour accÃ©lÃ©rer l'infÃ©rence sur CPU Intel et NPU.

**Avantages** :
- Optimisations spÃ©cifiques Intel (AVX-512, etc.)
- Support NPU (Neural Processing Unit)
- ModÃ¨les prÃ©-compilÃ©s pour rÃ©duire le temps de dÃ©marrage

**Utilisation** :
```python
settings.settings.lcm_diffusion_setting.use_openvino = True
settings.settings.lcm_diffusion_setting.openvino_lcm_model_id = "rupeshs/sd-turbo-openvino"
```

**Configuration NPU** :
```bash
export DEVICE=npu
python -m fastsdcpu.app --use_openvino --prompt "a cat"
```

**ModÃ¨les OpenVINO disponibles** :
- `rupeshs/sd-turbo-openvino`
- `rupeshs/sdxl-turbo-openvino`
- ModÃ¨les Flux optimisÃ©s

### 4. GGUF (via stable-diffusion.cpp)

**Principe** : ModÃ¨les quantifiÃ©s (Q4_0, Q8_0) pour rÃ©duire l'utilisation de la mÃ©moire.

**Avantages** :
- Empreinte mÃ©moire rÃ©duite (4-8 bits vs 16-32 bits)
- Pas de dÃ©pendance PyTorch lourde
- IdÃ©al pour machines limitÃ©es en RAM

**Utilisation** :
```python
settings.settings.lcm_diffusion_setting.use_gguf_model = True
settings.settings.lcm_diffusion_setting.gguf_model.diffusion_path = "models/gguf/diffusion/model.gguf"
settings.settings.lcm_diffusion_setting.gguf_model.clip_path = "models/gguf/clip/clip.gguf"
settings.settings.lcm_diffusion_setting.gguf_model.t5xxl_path = "models/gguf/t5xxl/t5xxl.gguf"
settings.settings.lcm_diffusion_setting.gguf_model.vae_path = "models/gguf/vae/vae.gguf"
```

**Configuration des threads** :
```bash
export GGUF_THREADS=8
```

**Note** : NÃ©cessite la bibliothÃ¨que `stable-diffusion.dll/.so/.dylib` dans le dossier `fastsdcpu/`.

---

## Utilisation

### Mode CLI (Command Line Interface)

#### GÃ©nÃ©ration simple

```bash
python -m fastsdcpu.app --prompt "a beautiful sunset over mountains" \
    --inference_steps 4 \
    --image_width 512 \
    --image_height 512
```

#### Avec seed fixe (reproductibilitÃ©)

```bash
python -m fastsdcpu.app --prompt "a cat wearing a hat" \
    --seed 42 \
    --number_of_images 4
```

#### Image-to-Image

```bash
python -m fastsdcpu.app --img2img \
    -f input.png \
    --prompt "transform into oil painting" \
    --strength 0.7 \
    --inference_steps 8
```

#### Avec OpenVINO

```bash
python -m fastsdcpu.app --use_openvino \
    --openvino_lcm_model_id "rupeshs/sd-turbo-openvino" \
    --prompt "a futuristic city"
```

#### Avec LCM-LoRA

```bash
python -m fastsdcpu.app --use_lcm_lora \
    --base_model_id "Lykon/dreamshaper-8" \
    --lcm_lora_id "latent-consistency/lcm-lora-sdv1-5" \
    --prompt "a fantasy castle"
```

#### Avec LoRA personnalisÃ©

```bash
python -m fastsdcpu.app --use_lcm_lora \
    --base_model_id "runwayml/stable-diffusion-v1-5" \
    --lora "/path/to/lora.safetensors" \
    --lora_weight 0.8 \
    --prompt "a character in anime style"
```

#### Upscaling

```bash
# EDSR upscaling
python -m fastsdcpu.app --upscale -f input.png

# Tiled SD upscaling (2x)
python -m fastsdcpu.app --sdupscale -f input.png --use_lcm_lora
```

#### Benchmark

```bash
python -m fastsdcpu.app --benchmark \
    --inference_steps 4 \
    --image_width 512 \
    --image_height 512
```

### Mode API Web

#### DÃ©marrer le serveur

```bash
python -m fastsdcpu.app --api --port 8000
```

#### Utilisation de l'API

**Documentation interactive** : `http://localhost:8000/api/docs`

**Endpoints disponibles** :

1. **GET /api/info** - Informations systÃ¨me
```bash
curl http://localhost:8000/api/info
```

2. **GET /api/models** - Liste des modÃ¨les disponibles
```bash
curl http://localhost:8000/api/models
```

3. **GET /api/config** - Configuration actuelle
```bash
curl http://localhost:8000/api/config
```

4. **POST /api/generate** - GÃ©nÃ©rer une image
```bash
curl -X POST http://localhost:8000/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a beautiful landscape",
    "negative_prompt": "blurry, low quality",
    "inference_steps": 4,
    "guidance_scale": 1.0,
    "image_width": 512,
    "image_height": 512,
    "number_of_images": 1,
    "use_openvino": false,
    "use_lcm_lora": false
  }'
```

**RÃ©ponse** :
```json
{
  "latency": 1.23,
  "images": ["base64_encoded_image..."],
  "error": ""
}
```

### Mode programmatique (Python)

#### Exemple basique

```python
from fastsdcpu.state import get_settings, get_context
from fastsdcpu.models.interface_types import InterfaceType
from fastsdcpu.constants import DEVICE

# Initialisation
settings = get_settings()
context = get_context(InterfaceType.CLI)

# Configuration
config = settings.settings
config.lcm_diffusion_setting.prompt = "a serene mountain landscape"
config.lcm_diffusion_setting.negative_prompt = "blurry, low quality"
config.lcm_diffusion_setting.inference_steps = 4
config.lcm_diffusion_setting.image_width = 512
config.lcm_diffusion_setting.image_height = 512
config.lcm_diffusion_setting.guidance_scale = 1.0
config.lcm_diffusion_setting.use_openvino = False

# GÃ©nÃ©ration
images = context.generate_text_to_image(
    settings=config,
    device=DEVICE
)

# Sauvegarde
if images:
    saved_paths = context.save_images(images, config)
    print(f"Images saved: {saved_paths}")
    print(f"Latency: {context.latency:.2f}s")
```

#### Exemple avec OpenVINO

```python
from fastsdcpu.state import get_settings, get_context
from fastsdcpu.models.interface_types import InterfaceType

settings = get_settings()
context = get_context(InterfaceType.CLI)

# Configuration OpenVINO
config = settings.settings
config.lcm_diffusion_setting.use_openvino = True
config.lcm_diffusion_setting.openvino_lcm_model_id = "rupeshs/sd-turbo-openvino"
config.lcm_diffusion_setting.prompt = "a futuristic robot"
config.lcm_diffusion_setting.inference_steps = 2
config.lcm_diffusion_setting.use_tiny_auto_encoder = True

# GÃ©nÃ©ration
images = context.generate_text_to_image(settings=config, device="cpu")
```

#### Exemple Image-to-Image

```python
from PIL import Image
from fastsdcpu.models.lcmdiffusion_setting import DiffusionTask

# Charger l'image d'entrÃ©e
init_image = Image.open("input.jpg")

# Configuration
config.lcm_diffusion_setting.diffusion_task = DiffusionTask.image_to_image.value
config.lcm_diffusion_setting.init_image = init_image
config.lcm_diffusion_setting.strength = 0.7  # 0.0 = pas de changement, 1.0 = complÃ¨tement diffÃ©rent
config.lcm_diffusion_setting.prompt = "transform into watercolor painting"
config.lcm_diffusion_setting.inference_steps = 8

# GÃ©nÃ©ration
images = context.generate_text_to_image(settings=config, device="cpu")
```

#### Exemple avec LoRA

```python
# Configuration LoRA
config.lcm_diffusion_setting.use_lcm_lora = True
config.lcm_diffusion_setting.lcm_lora.base_model_id = "Lykon/dreamshaper-8"
config.lcm_diffusion_setting.lcm_lora.lcm_lora_id = "latent-consistency/lcm-lora-sdv1-5"

# LoRA personnalisÃ© supplÃ©mentaire
config.lcm_diffusion_setting.lora.enabled = True
config.lcm_diffusion_setting.lora.path = "/path/to/custom_lora.safetensors"
config.lcm_diffusion_setting.lora.weight = 0.75

# GÃ©nÃ©ration
images = context.generate_text_to_image(settings=config, device="cpu")
```

#### GÃ©nÃ©ration en lot avec seeds

```python
# GÃ©nÃ©ration avec seed fixe pour reproductibilitÃ©
config.lcm_diffusion_setting.use_seed = True
config.lcm_diffusion_setting.seed = 42
config.lcm_diffusion_setting.number_of_images = 4

images = context.generate_text_to_image(settings=config, device="cpu")

# Chaque image aura un seed sÃ©quentiel : 42, 43, 44, 45
for img in images:
    print(f"Image seed: {img.info.get('image_seed')}")
```

---

## Configuration avancÃ©e

### Fichier de configuration YAML

Le module utilise un fichier `settings.yaml` automatiquement crÃ©Ã© dans `configs/`.

**Structure** :
```yaml
lcm_diffusion_setting:
  lcm_model_id: stabilityai/sd-turbo
  openvino_lcm_model_id: rupeshs/sd-turbo-openvino
  prompt: ""
  negative_prompt: ""
  image_height: 512
  image_width: 512
  inference_steps: 1
  guidance_scale: 1.0
  number_of_images: 1
  seed: 123123
  use_seed: false
  use_openvino: false
  use_lcm_lora: false
  use_tiny_auto_encoder: false
  use_safety_checker: false
  clip_skip: 1
  token_merging: 0.0
  
  lcm_lora:
    base_model_id: Lykon/dreamshaper-8
    lcm_lora_id: latent-consistency/lcm-lora-sdv1-5
  
  lora:
    enabled: false
    path: null
    weight: 0.5
    fuse: true

generated_images:
  path: results
  format: PNG
  save_image: true
  save_image_quality: 90
```

### ParamÃ¨tres JSON personnalisÃ©s

```bash
python -m fastsdcpu.app --custom_settings custom_config.json
```

**Exemple `custom_config.json`** :
```json
{
  "prompt": "a beautiful sunset",
  "negative_prompt": "blurry",
  "inference_steps": 6,
  "guidance_scale": 1.5,
  "image_width": 768,
  "image_height": 768,
  "controlnet": {
    "enabled": true,
    "adapter_path": "lllyasviel/control_v11p_sd15_canny",
    "conditioning_scale": 0.5
  }
}
```

### Optimisations disponibles

#### 1. Tiny AutoEncoder (TAESD)

RÃ©duit le temps de dÃ©codage VAE (~30% plus rapide).

```python
config.lcm_diffusion_setting.use_tiny_auto_encoder = True
```

**Compatible avec** : SD 1.5, SDXL, Flux

#### 2. Token Merging (ToMe)

RÃ©duit le nombre de tokens traitÃ©s pour accÃ©lÃ©rer l'infÃ©rence.

```python
config.lcm_diffusion_setting.token_merging = 0.4  # 0.0-1.0
```

**Note** : Valeurs Ã©levÃ©es (~0.5+) peuvent rÃ©duire la qualitÃ©.

#### 3. CLIP Skip

Ignore les derniÃ¨res couches CLIP pour des effets artistiques.

```python
config.lcm_diffusion_setting.clip_skip = 2  # 1-12
```

**Usage** : Certains modÃ¨les sont entraÃ®nÃ©s avec CLIP Skip (vÃ©rifier la fiche du modÃ¨le).

#### 4. FreeU

AmÃ©liore la qualitÃ© des dÃ©tails (activÃ© automatiquement avec LCM-LoRA).

AmÃ©liore les hautes et basses frÃ©quences dans le processus de diffusion.

#### 5. Safety Checker

Filtre les contenus NSFW.

```python
config.lcm_diffusion_setting.use_safety_checker = True
```

**Note** : Ralentit lÃ©gÃ¨rement la gÃ©nÃ©ration.

### Variables d'environnement

```bash
# Forcer un device spÃ©cifique
export DEVICE=cpu        # cpu, cuda, mps, npu

# Threads GGUF
export GGUF_THREADS=8    # Nombre de threads pour stable-diffusion.cpp
```

---

## API Reference

### Classes principales

#### `Context`

**Emplacement** : `fastsdcpu.context`

**MÃ©thodes** :
- `generate_text_to_image(settings, reshape, device, save_config)` â†’ `List[PIL.Image]`
  - GÃ©nÃ¨re des images selon la configuration
  - `settings` : Instance de `Settings`
  - `reshape` : Recompiler le pipeline OpenVINO (si dimensions changent)
  - `device` : Device cible ("cpu", "cuda", "npu")
  - `save_config` : Sauvegarder la config aprÃ¨s gÃ©nÃ©ration

- `save_images(images, settings)` â†’ `List[str]`
  - Sauvegarde les images gÃ©nÃ©rÃ©es
  - Retourne la liste des chemins de fichiers

**PropriÃ©tÃ©s** :
- `latency` : Temps de gÃ©nÃ©ration (secondes)
- `error` : Message d'erreur (vide si succÃ¨s)

#### `AppSettings`

**Emplacement** : `fastsdcpu.app_settings`

**MÃ©thodes** :
- `load(skip_file)` : Charger la configuration
- `save()` : Sauvegarder la configuration

**PropriÃ©tÃ©s** :
- `settings` : Instance de `Settings`
- `lcm_models` : Liste des modÃ¨les LCM disponibles
- `lcm_lora_models` : Liste des modÃ¨les LCM-LoRA
- `openvino_lcm_models` : Liste des modÃ¨les OpenVINO
- `stable_diffsuion_models` : Liste des modÃ¨les SD standards
- `gguf_diffusion_models` : Liste des modÃ¨les GGUF diffusion
- `gguf_clip_models` : Liste des modÃ¨les GGUF CLIP
- `gguf_vae_models` : Liste des modÃ¨les GGUF VAE

#### `LCMDiffusionSetting`

**Emplacement** : `fastsdcpu.models.lcmdiffusion_setting`

**Champs principaux** :
```python
class LCMDiffusionSetting(BaseModel):
    # ModÃ¨les
    lcm_model_id: str
    openvino_lcm_model_id: str
    
    # Prompts
    prompt: str
    negative_prompt: str
    
    # Dimensions
    image_width: int = 512
    image_height: int = 512
    
    # ParamÃ¨tres de gÃ©nÃ©ration
    inference_steps: int = 1
    guidance_scale: float = 1.0
    number_of_images: int = 1
    seed: int = 123123
    use_seed: bool = False
    
    # Modes
    use_openvino: bool = False
    use_lcm_lora: bool = False
    use_tiny_auto_encoder: bool = False
    use_gguf_model: bool = False
    
    # Image-to-Image
    init_image: Any = None
    strength: float = 0.6
    diffusion_task: str = "text_to_image"
    
    # Optimisations
    clip_skip: int = 1
    token_merging: float = 0.0
    use_safety_checker: bool = False
    
    # LoRA
    lcm_lora: LCMLora
    lora: Lora
    
    # ControlNet
    controlnet: Optional[ControlNetSetting] = None
    
    # GGUF
    gguf_model: GGUFModel
```

### Fonctions utilitaires

#### State Management

```python
from fastsdcpu.state import get_settings, get_context, get_safety_checker

# Obtenir les paramÃ¨tres (singleton)
settings = get_settings(skip_file=False)

# Obtenir le contexte
from fastsdcpu.models.interface_types import InterfaceType
context = get_context(InterfaceType.CLI)

# Obtenir le safety checker
checker = get_safety_checker()
is_safe = checker.is_safe(image)  # PIL.Image â†’ bool
```

#### Chemins

```python
from fastsdcpu.utils.paths import FastStableDiffusionPaths

# Chemins des modÃ¨les
lora_path = FastStableDiffusionPaths.get_lora_models_path()
controlnet_path = FastStableDiffusionPaths.get_controlnet_models_path()
gguf_path = FastStableDiffusionPaths.get_gguf_models_path()

# Chemin de rÃ©sultats
results_path = FastStableDiffusionPaths.get_results_path()

# Chemin pour upscale
upscale_path = FastStableDiffusionPaths.get_upscale_filepath(
    "input.png", scale_factor=2, format="PNG"
)
```

---

## Exemples pratiques

### Exemple 1 : Script de gÃ©nÃ©ration batch

```python
"""
GÃ©nÃ¨re plusieurs variations d'un prompt avec diffÃ©rents seeds
"""
from fastsdcpu.state import get_settings, get_context
from fastsdcpu.models.interface_types import InterfaceType
from fastsdcpu.constants import DEVICE

def generate_variations(prompt, num_variations=5):
    settings = get_settings()
    context = get_context(InterfaceType.CLI)
    
    config = settings.settings
    config.lcm_diffusion_setting.prompt = prompt
    config.lcm_diffusion_setting.use_seed = False  # Seeds alÃ©atoires
    config.lcm_diffusion_setting.inference_steps = 4
    
    all_images = []
    
    for i in range(num_variations):
        print(f"Generating variation {i+1}/{num_variations}...")
        images = context.generate_text_to_image(config, device=DEVICE)
        
        if images:
            all_images.extend(images)
            saved_paths = context.save_images(images, config)
            print(f"  Saved: {saved_paths[0]}")
            print(f"  Latency: {context.latency:.2f}s")
    
    return all_images

# Utilisation
variations = generate_variations("a cat in a garden", num_variations=5)
print(f"Total images generated: {len(variations)}")
```

### Exemple 2 : Serveur API personnalisÃ©

```python
"""
Serveur API Flask simple pour gÃ©nÃ©ration d'images
"""
from flask import Flask, request, jsonify, send_file
from fastsdcpu.state import get_settings, get_context
from fastsdcpu.models.interface_types import InterfaceType
from fastsdcpu.constants import DEVICE
from io import BytesIO
import base64

app = Flask(__name__)
settings = get_settings()
context = get_context(InterfaceType.API_SERVER)

@app.route('/generate', methods=['POST'])
def generate():
    data = request.json
    
    config = settings.settings
    config.lcm_diffusion_setting.prompt = data.get('prompt', '')
    config.lcm_diffusion_setting.negative_prompt = data.get('negative_prompt', '')
    config.lcm_diffusion_setting.inference_steps = data.get('steps', 4)
    config.lcm_diffusion_setting.image_width = data.get('width', 512)
    config.lcm_diffusion_setting.image_height = data.get('height', 512)
    
    images = context.generate_text_to_image(config, device=DEVICE)
    
    if not images:
        return jsonify({'error': context.error}), 500
    
    # Encoder en base64
    buffered = BytesIO()
    images[0].save(buffered, format="PNG")
    img_str = base64.b64encode(buffered.getvalue()).decode()
    
    return jsonify({
        'image': img_str,
        'latency': context.latency,
        'seed': images[0].info.get('image_seed', -1)
    })

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)
```

### Exemple 3 : Pipeline de traitement d'images

```python
"""
Pipeline : gÃ©nÃ©ration â†’ amÃ©lioration â†’ upscaling
"""
from fastsdcpu.state import get_settings, get_context
from fastsdcpu.models.interface_types import InterfaceType
from fastsdcpu.models.lcmdiffusion_setting import DiffusionTask
from fastsdcpu.upscaler import upscale_image
from fastsdcpu.utils.paths import FastStableDiffusionPaths

def image_pipeline(prompt, enhance_prompt=None, upscale_factor=2):
    settings = get_settings()
    context = get_context(InterfaceType.CLI)
    config = settings.settings
    
    # Ã‰tape 1 : GÃ©nÃ©ration initiale
    print("Step 1: Generating base image...")
    config.lcm_diffusion_setting.prompt = prompt
    config.lcm_diffusion_setting.inference_steps = 4
    config.lcm_diffusion_setting.image_width = 512
    config.lcm_diffusion_setting.image_height = 512
    
    images = context.generate_text_to_image(config)
    if not images:
        return None
    
    base_image = images[0]
    print(f"  Generated in {context.latency:.2f}s")
    
    # Ã‰tape 2 : AmÃ©lioration (si spÃ©cifiÃ©e)
    if enhance_prompt:
        print("Step 2: Enhancing image...")
        config.lcm_diffusion_setting.diffusion_task = DiffusionTask.image_to_image.value
        config.lcm_diffusion_setting.init_image = base_image
        config.lcm_diffusion_setting.prompt = enhance_prompt
        config.lcm_diffusion_setting.strength = 0.3
        config.lcm_diffusion_setting.inference_steps = 6
        
        enhanced_images = context.generate_text_to_image(config)
        if enhanced_images:
            base_image = enhanced_images[0]
            print(f"  Enhanced in {context.latency:.2f}s")
    
    # Ã‰tape 3 : Upscaling
    print(f"Step 3: Upscaling {upscale_factor}x...")
    temp_path = "temp_image.png"
    base_image.save(temp_path)
    
    output_path = FastStableDiffusionPaths.get_upscale_filepath(
        temp_path, upscale_factor, "PNG"
    )
    
    upscaled = upscale_image(context, temp_path, output_path, upscale_factor)
    print(f"  Upscaled and saved to: {output_path}")
    
    return upscaled

# Utilisation
result = image_pipeline(
    prompt="a mystical forest",
    enhance_prompt="add more details and vibrant colors",
    upscale_factor=2
)
```

### Exemple 4 : Comparaison de modÃ¨les

```python
"""
Compare plusieurs modÃ¨les/configurations pour le mÃªme prompt
"""
from fastsdcpu.state import get_settings, get_context
from fastsdcpu.models.interface_types import InterfaceType
from fastsdcpu.constants import DEVICE
import matplotlib.pyplot as plt

def compare_models(prompt, configurations):
    """
    configurations: liste de dicts avec les paramÃ¨tres Ã  tester
    """
    settings = get_settings()
    context = get_context(InterfaceType.CLI)
    
    results = []
    
    for i, config_params in enumerate(configurations):
        print(f"\nTesting configuration {i+1}/{len(configurations)}:")
        print(f"  {config_params['name']}")
        
        config = settings.settings
        config.lcm_diffusion_setting.prompt = prompt
        
        # Appliquer les paramÃ¨tres
        for key, value in config_params.items():
            if key != 'name':
                setattr(config.lcm_diffusion_setting, key, value)
        
        # GÃ©nÃ©rer
        images = context.generate_text_to_image(config, device=DEVICE)
        
        if images:
            results.append({
                'name': config_params['name'],
                'image': images[0],
                'latency': context.latency
            })
            print(f"  Latency: {context.latency:.2f}s")
    
    return results

# Configuration de test
test_configs = [
    {
        'name': 'LCM Standard',
        'lcm_model_id': 'stabilityai/sd-turbo',
        'use_lcm_lora': False,
        'use_openvino': False,
        'inference_steps': 1
    },
    {
        'name': 'LCM-LoRA Dreamshaper',
        'use_lcm_lora': True,
        'use_openvino': False,
        'inference_steps': 4
    },
    {
        'name': 'OpenVINO',
        'use_openvino': True,
        'use_lcm_lora': False,
        'inference_steps': 2
    }
]

# Comparer
results = compare_models("a serene lake at sunset", test_configs)

# Afficher les rÃ©sultats
fig, axes = plt.subplots(1, len(results), figsize=(15, 5))
for i, result in enumerate(results):
    axes[i].imshow(result['image'])
    axes[i].set_title(f"{result['name']}\n{result['latency']:.2f}s")
    axes[i].axis('off')
plt.tight_layout()
plt.show()
```

### Exemple 5 : ControlNet (Canny Edge)

```python
"""
Utilisation de ControlNet pour le contrÃ´le de la composition
"""
from fastsdcpu.state import get_settings, get_context
from fastsdcpu.models.interface_types import InterfaceType
from fastsdcpu.models.lcmdiffusion_setting import ControlNetSetting
from PIL import Image
import cv2
import numpy as np

def generate_with_controlnet(source_image_path, prompt):
    settings = get_settings()
    context = get_context(InterfaceType.CLI)
    config = settings.settings
    
    # Charger et traiter l'image source
    source_image = Image.open(source_image_path)
    
    # CrÃ©er une carte de contours Canny
    image_array = np.array(source_image)
    edges = cv2.Canny(image_array, 100, 200)
    edges_image = Image.fromarray(edges)
    
    # Configuration ControlNet
    controlnet = ControlNetSetting(
        enabled=True,
        adapter_path="lllyasviel/control_v11p_sd15_canny",
        conditioning_scale=0.5
    )
    controlnet._control_image = edges_image
    
    # Configuration de gÃ©nÃ©ration
    config.lcm_diffusion_setting.use_lcm_lora = True
    config.lcm_diffusion_setting.controlnet = controlnet
    config.lcm_diffusion_setting.prompt = prompt
    config.lcm_diffusion_setting.inference_steps = 6
    config.lcm_diffusion_setting.guidance_scale = 1.5
    
    # GÃ©nÃ©rer
    images = context.generate_text_to_image(config)
    
    return images[0] if images else None

# Utilisation
result = generate_with_controlnet(
    "reference_photo.jpg",
    "a fantasy castle in anime style"
)
if result:
    result.save("controlnet_result.png")
```

### Exemple 6 : GÃ©nÃ©ration par lots avec queue

```python
"""
SystÃ¨me de queue pour traiter plusieurs prompts
"""
from fastsdcpu.state import get_settings, get_context
from fastsdcpu.models.interface_types import InterfaceType
from fastsdcpu.constants import DEVICE
from queue import Queue
from threading import Thread
import time

class ImageGenerationQueue:
    def __init__(self, num_workers=1):
        self.queue = Queue()
        self.results = {}
        self.workers = []
        self.settings = get_settings()
        
        for _ in range(num_workers):
            worker = Thread(target=self._worker)
            worker.daemon = True
            worker.start()
            self.workers.append(worker)
    
    def _worker(self):
        context = get_context(InterfaceType.CLI)
        config = self.settings.settings
        
        while True:
            item = self.queue.get()
            if item is None:
                break
            
            job_id, params = item
            print(f"Processing job {job_id}...")
            
            # Configurer
            config.lcm_diffusion_setting.prompt = params['prompt']
            config.lcm_diffusion_setting.negative_prompt = params.get('negative_prompt', '')
            config.lcm_diffusion_setting.inference_steps = params.get('steps', 4)
            config.lcm_diffusion_setting.use_seed = True
            config.lcm_diffusion_setting.seed = params.get('seed', int(time.time()))
            
            # GÃ©nÃ©rer
            images = context.generate_text_to_image(config, device=DEVICE)
            
            # Sauvegarder rÃ©sultat
            if images:
                saved_paths = context.save_images(images, config)
                self.results[job_id] = {
                    'images': images,
                    'paths': saved_paths,
                    'latency': context.latency,
                    'status': 'completed'
                }
            else:
                self.results[job_id] = {
                    'error': context.error,
                    'status': 'failed'
                }
            
            self.queue.task_done()
            print(f"Job {job_id} completed in {context.latency:.2f}s")
    
    def add_job(self, job_id, params):
        self.queue.put((job_id, params))
    
    def wait_completion(self):
        self.queue.join()
    
    def shutdown(self):
        for _ in self.workers:
            self.queue.put(None)
        for worker in self.workers:
            worker.join()

# Utilisation
queue = ImageGenerationQueue(num_workers=2)

# Ajouter des jobs
prompts = [
    "a cyberpunk city at night",
    "a peaceful countryside",
    "an underwater scene with coral",
    "a space station orbiting earth",
    "a medieval market"
]

for i, prompt in enumerate(prompts):
    queue.add_job(f"job_{i}", {'prompt': prompt, 'steps': 4})

# Attendre la fin
print("Waiting for all jobs to complete...")
queue.wait_completion()
queue.shutdown()

# Afficher les rÃ©sultats
for job_id, result in queue.results.items():
    if result['status'] == 'completed':
        print(f"{job_id}: {result['paths'][0]} ({result['latency']:.2f}s)")
    else:
        print(f"{job_id}: Failed - {result.get('error', 'Unknown error')}")
```

### Exemple 7 : Interpolation entre prompts

```python
"""
CrÃ©er une transition fluide entre deux prompts
"""
from fastsdcpu.state import get_settings, get_context
from fastsdcpu.models.interface_types import InterfaceType
from fastsdcpu.constants import DEVICE
from PIL import Image

def interpolate_prompts(prompt_start, prompt_end, num_steps=5):
    """
    GÃ©nÃ¨re des images intermÃ©diaires entre deux prompts
    Note: Cette implÃ©mentation simple alterne les seeds
    Pour une vraie interpolation, utiliser des techniques avancÃ©es (CLIP embedding interpolation)
    """
    settings = get_settings()
    context = get_context(InterfaceType.CLI)
    config = settings.settings
    
    results = []
    
    # Image de dÃ©part
    print(f"Generating start: {prompt_start}")
    config.lcm_diffusion_setting.prompt = prompt_start
    config.lcm_diffusion_setting.use_seed = True
    config.lcm_diffusion_setting.seed = 42
    config.lcm_diffusion_setting.inference_steps = 6
    
    start_images = context.generate_text_to_image(config, device=DEVICE)
    if start_images:
        results.append(start_images[0])
    
    # Images intermÃ©diaires (combinaison de prompts)
    for i in range(1, num_steps - 1):
        ratio = i / (num_steps - 1)
        # Prompt hybride simple
        hybrid_prompt = f"({prompt_start}:0.{int((1-ratio)*10)}) and ({prompt_end}:0.{int(ratio*10)})"
        
        print(f"Generating step {i}/{num_steps-2}: ratio={ratio:.2f}")
        config.lcm_diffusion_setting.prompt = hybrid_prompt
        config.lcm_diffusion_setting.seed = 42 + i
        
        images = context.generate_text_to_image(config, device=DEVICE)
        if images:
            results.append(images[0])
    
    # Image de fin
    print(f"Generating end: {prompt_end}")
    config.lcm_diffusion_setting.prompt = prompt_end
    config.lcm_diffusion_setting.seed = 42 + num_steps
    
    end_images = context.generate_text_to_image(config, device=DEVICE)
    if end_images:
        results.append(end_images[0])
    
    return results

# Utilisation
frames = interpolate_prompts(
    "a sunny day in the park",
    "a starry night in the same park",
    num_steps=5
)

# CrÃ©er un GIF
if frames:
    frames[0].save(
        'interpolation.gif',
        save_all=True,
        append_images=frames[1:],
        duration=500,
        loop=0
    )
    print("Animation saved as interpolation.gif")
```

---

## Troubleshooting

### ProblÃ¨mes courants

#### 1. "Model not found" ou erreurs de tÃ©lÃ©chargement

**Solution** :
```python
# Utiliser un modÃ¨le local
config.lcm_diffusion_setting.use_offline_model = True
config.lcm_diffusion_setting.lcm_model_id = "/path/to/local/model"
```

Ou tÃ©lÃ©charger manuellement depuis Hugging Face :
```bash
huggingface-cli download stabilityai/sd-turbo --local-dir ./models/sd-turbo
```

#### 2. Out of Memory (OOM)

**Solutions** :
- RÃ©duire la rÃ©solution : `image_width=256, image_height=256`
- Utiliser GGUF (quantification) : `use_gguf_model=True`
- Utiliser Tiny AutoEncoder : `use_tiny_auto_encoder=True`
- RÃ©duire batch size : `number_of_images=1`

#### 3. OpenVINO : "Device not found"

**VÃ©rifications** :
```bash
# VÃ©rifier les devices disponibles
python -c "from openvino.runtime import Core; print(Core().available_devices)"
```

**Solutions** :
- Installer OpenVINO correctement
- Utiliser `export DEVICE=cpu` au lieu de `npu`
- VÃ©rifier les drivers Intel

#### 4. GGUF : "Failed to load library"

**Causes** :
- BibliothÃ¨que `stable-diffusion.dll/.so/.dylib` manquante
- Architecture incompatible (ARM vs x86)

**Solutions** :
- TÃ©lÃ©charger la bibliothÃ¨que compilÃ©e pour votre systÃ¨me
- Placer dans le dossier `fastsdcpu/`
- VÃ©rifier les permissions d'exÃ©cution (Linux/macOS)

```bash
# Linux/macOS
chmod +x libstable-diffusion.so
```

#### 5. Images floues ou de mauvaise qualitÃ©

**Solutions** :
- Augmenter `inference_steps` (4-8 pour LCM)
- Ajuster `guidance_scale` (essayer 1.5-2.0 avec LCM-LoRA)
- Utiliser un meilleur modÃ¨le de base (Dreamshaper, etc.)
- DÃ©sactiver `use_tiny_auto_encoder`
- AmÃ©liorer le prompt (plus de dÃ©tails)

#### 6. GÃ©nÃ©ration trÃ¨s lente

**Diagnostic** :
```python
# Benchmark pour identifier le goulot d'Ã©tranglement
python -m fastsdcpu.app --benchmark
```

**Optimisations** :
- Activer OpenVINO sur processeurs Intel
- Utiliser GGUF pour rÃ©duire l'utilisation mÃ©moire
- Activer `use_tiny_auto_encoder=True`
- Activer `token_merging` (0.3-0.5)
- RÃ©duire la rÃ©solution
- Augmenter `GGUF_THREADS`

#### 7. Safety Checker bloque tout

**Solution temporaire** :
```python
config.lcm_diffusion_setting.use_safety_checker = False
```

**Note** : Utilisez avec prÃ©caution selon votre cas d'usage.

### Logs et debugging

#### Activer les logs dÃ©taillÃ©s

```python
import logging
logging.basicConfig(level=logging.DEBUG)
```

#### VÃ©rifier la configuration chargÃ©e

```python
from fastsdcpu.state import get_settings
settings = get_settings()
from pprint import pprint
pprint(settings.settings.lcm_diffusion_setting.model_dump())
```

#### Tester les composants individuellement

```python
# Tester le chargement du pipeline
from fastsdcpu.pipelines.lcm.text_to_image import LCMTextToImage
from fastsdcpu.models.lcmdiffusion_setting import LCMDiffusionSetting

pipeline = LCMTextToImage(device="cpu")
config = LCMDiffusionSetting()
pipeline.init("cpu", config)
print(f"Pipeline loaded: {pipeline.pipeline}")
```

---

## Performance et Benchmarks

### Temps de gÃ©nÃ©ration typiques

**Configuration test** : Intel i7-12700K, 32GB RAM, 512x512, 4 steps

| Mode | ModÃ¨le | Latence moyenne |
|------|--------|-----------------|
| LCM Standard | sd-turbo | ~1.5s |
| LCM-LoRA | dreamshaper-8 | ~2.0s |
| OpenVINO | sd-turbo-openvino | ~1.2s |
| OpenVINO + TAESD | sd-turbo-openvino | ~0.9s |
| GGUF Q4_0 | flux-schnell | ~3.5s |

### Conseils d'optimisation

1. **Pour la vitesse maximale** :
   - OpenVINO + TAESD sur Intel
   - 1-2 inference steps
   - RÃ©solution 512x512
   - Token merging 0.4

2. **Pour la meilleure qualitÃ©** :
   - LCM-LoRA avec modÃ¨le de qualitÃ© (Dreamshaper)
   - 6-8 inference steps
   - Guidance scale 1.5-2.0
   - Pas de TAESD
   - RÃ©solution native du modÃ¨le

3. **Pour Ã©conomiser la RAM** :
   - GGUF Q4_0/Q8_0
   - TAESD activÃ©
   - Batch size 1
   - RÃ©solution rÃ©duite

---

## Roadmap et limitations

### Limitations actuelles

- **GGUF** : Pas de support img2img natif (work in progress)
- **OpenVINO** : LoRA personnalisÃ©s non supportÃ©s
- **Safety Checker** : Peut avoir des faux positifs
- **ControlNet** : Support partiel selon le pipeline

### FonctionnalitÃ©s prÃ©vues

- Support Flux complet avec GGUF
- AmÃ©lioration de l'interface MCP
- Support des adaptateurs IP-Adapter
- Pipeline vidÃ©o (frame-by-frame)
- Cache de modÃ¨les optimisÃ©
- Support AMD ROCm

---

## Contribution

Le projet est open-source. Contributions bienvenues sur :
- GitHub : https://github.com/Flyns157/fastsdcpu
- PyPI : https://pypi.org/project/fastsdcpu-pip/

### Structure de dÃ©veloppement

```bash
# Clone
git clone https://github.com/Flyns157/fastsdcpu.git
cd fastsdcpu/pip

# Installation en mode dÃ©veloppement
pip install -e .

# Tests
python -m pytest tests/
```

---

## Licence

Le projet utilise une double licence :
- **MIT** pour le code du projet
- **MIT AND (Apache-2.0 OR BSD-2-Clause)** incluant les dÃ©pendances tierces

Voir `LICENSE` et `THIRD-PARTY-LICENSES` pour les dÃ©tails.

---

## Ressources

### Documentation officielle
- Diffusers : https://huggingface.co/docs/diffusers
- OpenVINO : https://docs.openvino.ai
- stable-diffusion.cpp : https://github.com/leejet/stable-diffusion.cpp

### ModÃ¨les recommandÃ©s
- Hugging Face : https://huggingface.co/models?pipeline_tag=text-to-image
- Civitai : https://civitai.com/

### CommunautÃ©
- Issues GitHub : https://github.com/Flyns157/fastsdcpu/issues
- Discussions : https://github.com/Flyns157/fastsdcpu/discussions

---

## Changelog

### v0.1.5 (Actuel)
- Support initial pip
- Pipelines LCM, OpenVINO, GGUF
- API Web et MCP
- Support ControlNet basique

### Ã€ venir (v0.2.0)
- AmÃ©lioration GGUF img2img
- Cache de pipeline intelligent
- Interface Web amÃ©liorÃ©e
