Files changed (14) hide show
  1. .env.example +48 -0
  2. README.md +340 -10
  3. config.py +64 -0
  4. job_store.py +99 -0
  5. main.py +131 -0
  6. pipeline_manager.py +199 -0
  7. requirements.txt +20 -0
  8. routes/__init__.py +0 -0
  9. routes/generate.py +81 -0
  10. routes/health.py +111 -0
  11. routes/jobs.py +160 -0
  12. schemas.py +132 -0
  13. start.sh +44 -0
  14. worker.py +179 -0
.env.example ADDED
@@ -0,0 +1,48 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # ── HF CPU Image Generation API — environment configuration ──────────────────
2
+ # Copy this file to .env and edit as needed.
3
+ # All values shown here are the defaults.
4
+
5
+ # ── Server ────────────────────────────────────────────────────────────────────
6
+ HOST=0.0.0.0
7
+ PORT=8000
8
+ DEBUG=false
9
+
10
+ # ── Model ─────────────────────────────────────────────────────────────────────
11
+ # Recommended CPU models (smallest to largest):
12
+ #
13
+ # nota-ai/bk-sdm-small ~500 MB — fastest on CPU (default)
14
+ # runwayml/stable-diffusion-v1-5 ~4 GB — best quality/compat balance
15
+ # stabilityai/stable-diffusion-2-1-base ~5 GB — highest quality
16
+ #
17
+ MODEL_ID=nota-ai/bk-sdm-small
18
+ MODEL_CACHE_DIR=./model_cache
19
+
20
+ # Load the model at startup so the first job doesn't pay cold-start cost.
21
+ # Set to false if you want to control loading manually via POST /models/load
22
+ AUTO_LOAD_MODEL=true
23
+
24
+ # ── CPU Tuning ─────────────────────────────────────────────────────────────────
25
+ # 0 = use all logical CPU cores (recommended)
26
+ CPU_THREADS=0
27
+
28
+ # Slice attention into smaller chunks — lowers peak RAM, minimal speed cost
29
+ ENABLE_ATTENTION_SLICING=true
30
+
31
+ # ── Generation defaults ────────────────────────────────────────────────────────
32
+ # DPM++ scheduler converges well at 20 steps — good CPU/quality balance
33
+ DEFAULT_STEPS=20
34
+ MAX_STEPS=50
35
+
36
+ # 512×512 is ideal for SD v1.x — larger sizes increase RAM and time significantly
37
+ DEFAULT_WIDTH=512
38
+ DEFAULT_HEIGHT=512
39
+ MAX_WIDTH=768
40
+ MAX_HEIGHT=768
41
+
42
+ DEFAULT_GUIDANCE_SCALE=7.5
43
+
44
+ # ── Storage ────────────────────────────────────────────────────────────────────
45
+ OUTPUTS_DIR=./outputs
46
+
47
+ # Auto-delete jobs after N seconds (0 = keep forever)
48
+ JOB_TTL_SECONDS=0
README.md CHANGED
@@ -1,13 +1,343 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
  ---
2
- title: Hf Image Api
3
- emoji: ⚡
4
- colorFrom: purple
5
- colorTo: green
6
- sdk: gradio
7
- sdk_version: 6.19.0
8
- python_version: '3.13'
9
- app_file: app.py
10
- pinned: false
 
 
 
 
 
 
 
 
 
11
  ---
12
 
13
- Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # HF CPU Image Generation API
2
+
3
+ A production-ready REST API for **Stable Diffusion image generation on CPU** using Hugging Face Diffusers. Built on top of the architecture patterns from [Local AI Image Generator](https://github.com/techjarves/Local-AI-Image-Generator) and redesigned as a stateless, job-queue-based HTTP API.
4
+
5
+ ---
6
+
7
+ ## Architecture Overview
8
+
9
+ ```
10
+ Client
11
+ │
12
+ │ POST /generate → { job_id, status: "queued" }
13
+ │
14
+ │ GET /jobs/{id} → { status: "processing", progress: 45 }
15
+ │ GET /jobs/{id} → { status: "completed", download_url: "..." }
16
+ │
17
+ │ GET /jobs/{id}/download → image.png
18
+ │
19
+ │ DELETE /jobs/{id} → { ok: true }
20
+ │
21
+ ▼
22
+
23
+ ┌─────────────────────────────────────────────────────────────┐
24
+ │ FastAPI (main.py) │
25
+ │ ├── POST /generate → enqueue job, return job_id │
26
+ │ ├── GET /jobs → list / filter jobs │
27
+ │ ├── GET /jobs/{id} → status + progress │
28
+ │ ├── GET /jobs/{id}/download → FileResponse (PNG) │
29
+ │ ├── DELETE /jobs/{id} → delete job + image │
30
+ │ ├── GET /health → pipeline & queue status │
31
+ │ └── POST /models/load → hot-swap model │
32
+ │ │
33
+ │ job_store.py — thread-safe in-memory job registry │
34
+ │ worker.py — background daemon thread + FIFO queue │
35
+ │ pipeline_manager.py — HF Diffusers pipeline (CPU-tuned) │
36
+ └─────────────────────────────────────────────────────────────┘
37
+ │
38
+ ┌────────▼────────┐
39
+ │ outputs/ │
40
+ │ (PNG files) │
41
+ └─────────────────┘
42
+ ```
43
+
44
+ ---
45
+
46
+ ## Quick Start
47
+
48
+ ### Prerequisites
49
+ - Python 3.9 or higher
50
+ - 4 GB+ RAM (8 GB recommended for SD v1.5)
51
+ - Internet connection on first run (to download model weights)
52
+
53
+ ### 1. Install
54
+
55
+ ```bash
56
+ git clone <this-repo>
57
+ cd hf-image-api
58
+
59
+ # Linux / macOS — one command setup:
60
+ bash start.sh
61
+
62
+ # Windows:
63
+ python -m venv .venv
64
+ .venv\Scripts\activate
65
+ pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
66
+ pip install -r requirements.txt
67
+ copy .env.example .env
68
+ python -m uvicorn main:app --host 0.0.0.0 --port 8000 --workers 1
69
+ ```
70
+
71
+ ### 2. Open the interactive docs
72
+
73
+ ```
74
+ http://localhost:8000/docs
75
+ ```
76
+
77
+ ---
78
+
79
+ ## CPU Performance Guide
80
+
81
+ | Model | Size | 512×512 @ 20 steps | Notes |
82
+ |---|---|---|---|
83
+ | `nota-ai/bk-sdm-small` | ~500 MB | **~60–120 s** | Best for CPU — default |
84
+ | `runwayml/stable-diffusion-v1-5` | ~4 GB | ~150–300 s | Standard quality |
85
+ | `stabilityai/stable-diffusion-2-1-base` | ~5 GB | ~200–400 s | Highest quality |
86
+
87
+ ### Optimisations applied automatically
88
+
89
+ | Optimisation | Effect |
90
+ |---|---|
91
+ | `torch.float32` | Mandatory for CPU (float16 causes NaN) |
92
+ | `low_cpu_mem_usage=True` | Streams weights into RAM — avoids double-buffering |
93
+ | `enable_attention_slicing(1)` | Lowers peak RAM ~30 %, minimal speed cost |
94
+ | `DPMSolverMultistepScheduler` + Karras sigmas | Converges well at 15–20 steps |
95
+ | `safety_checker=None` | Skips NSFW classifier, saves ~300 MB RAM |
96
+ | `torch.set_num_threads(N)` | Saturates all logical CPU cores |
97
+ | `torch.inference_mode()` | Disables autograd, reduces overhead |
98
+
99
+ ### Tips to speed up CPU generation
100
+ - Use **`nota-ai/bk-sdm-small`** — it is specifically distilled for speed
101
+ - Keep images at **512×512** (larger = much slower on SD v1.x)
102
+ - Use **20 steps with DPM++** (better than 50 steps with PNDM)
103
+ - Set `CPU_THREADS=0` in `.env` to use all logical cores
104
+ - Avoid running other CPU-heavy workloads during generation
105
+
106
+ ---
107
+
108
+ ## API Reference
109
+
110
+ ### Submit a generation job
111
+
112
+ ```
113
+ POST /generate
114
+ ```
115
+
116
+ **Request body:**
117
+ ```json
118
+ {
119
+ "prompt": "a photorealistic mountain landscape at golden hour",
120
+ "negative_prompt": "blurry, low quality, watermark",
121
+ "width": 512,
122
+ "height": 512,
123
+ "num_inference_steps": 20,
124
+ "guidance_scale": 7.5,
125
+ "seed": -1,
126
+ "scheduler": "dpm++"
127
+ }
128
+ ```
129
+
130
+ **Schedulers:** `dpm++` (best), `euler_a`, `euler`, `pndm`
131
+
132
+ **Response `202 Accepted`:**
133
+ ```json
134
+ {
135
+ "job_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
136
+ "status": "queued",
137
+ "created_at": "2024-06-01T12:00:00Z",
138
+ "queue_position": 1,
139
+ "message": "Job is next in queue and will start immediately."
140
+ }
141
+ ```
142
+
143
+ ---
144
+
145
+ ### Check job status
146
+
147
+ ```
148
+ GET /jobs/{job_id}
149
+ ```
150
+
151
+ **While processing:**
152
+ ```json
153
+ {
154
+ "job_id": "3fa85f64-...",
155
+ "status": "processing",
156
+ "progress": 45,
157
+ "current_step": 9,
158
+ "total_steps": 20,
159
+ "started_at": "2024-06-01T12:00:01Z"
160
+ }
161
+ ```
162
+
163
+ **When completed:**
164
+ ```json
165
+ {
166
+ "job_id": "3fa85f64-...",
167
+ "status": "completed",
168
+ "progress": 100,
169
+ "download_url": "/jobs/3fa85f64-.../download",
170
+ "image_filename": "20240601_120045_3fa85f64_42.png",
171
+ "duration_seconds": 87.3,
172
+ "completed_at": "2024-06-01T12:01:28Z"
173
+ }
174
+ ```
175
+
176
+ ---
177
+
178
+ ### Download the image
179
+
180
+ ```
181
+ GET /jobs/{job_id}/download
182
+ ```
183
+
184
+ Returns the PNG as a file attachment. Returns `202` if still processing.
185
+
186
  ---
187
+
188
+ ### Delete a job and its image
189
+
190
+ ```
191
+ DELETE /jobs/{job_id}
192
+ ```
193
+
194
+ Removes the job record and deletes the PNG from disk.
195
+
196
+ ```json
197
+ {
198
+ "ok": true,
199
+ "job_id": "3fa85f64-...",
200
+ "image_deleted": true,
201
+ "message": "Job deleted. Image file removed from disk."
202
+ }
203
+ ```
204
+
205
  ---
206
 
207
+ ### List all jobs
208
+
209
+ ```
210
+ GET /jobs?status=completed&limit=50&offset=0
211
+ ```
212
+
213
+ Status filter options: `queued`, `processing`, `completed`, `failed`
214
+
215
+ ---
216
+
217
+ ### Health check
218
+
219
+ ```
220
+ GET /health
221
+ ```
222
+
223
+ ```json
224
+ {
225
+ "status": "ok",
226
+ "model_id": "nota-ai/bk-sdm-small",
227
+ "pipeline_loaded": true,
228
+ "loading": false,
229
+ "queue_size": 2,
230
+ "jobs_total": 15,
231
+ "jobs_by_status": {
232
+ "queued": 2,
233
+ "processing": 1,
234
+ "completed": 11,
235
+ "failed": 1
236
+ },
237
+ "cpu_threads": 8
238
+ }
239
+ ```
240
+
241
+ ---
242
+
243
+ ### Hot-swap model
244
+
245
+ ```
246
+ POST /models/load
247
+ Content-Type: application/json
248
+
249
+ { "model_id": "runwayml/stable-diffusion-v1-5" }
250
+ ```
251
+
252
+ Loads the new model in the background. Poll `GET /health` to confirm `pipeline_loaded: true`.
253
+
254
+ ---
255
+
256
+ ## Example: Full workflow with curl
257
+
258
+ ```bash
259
+ # 1. Check service is ready
260
+ curl http://localhost:8000/health | jq .pipeline_loaded
261
+
262
+ # 2. Submit a generation job
263
+ JOB=$(curl -s -X POST http://localhost:8000/generate \
264
+ -H "Content-Type: application/json" \
265
+ -d '{
266
+ "prompt": "a serene Japanese garden with koi pond, watercolor style",
267
+ "negative_prompt": "low quality, blurry, cartoon",
268
+ "width": 512,
269
+ "height": 512,
270
+ "num_inference_steps": 20,
271
+ "guidance_scale": 7.5,
272
+ "seed": 42,
273
+ "scheduler": "dpm++"
274
+ }')
275
+ echo $JOB | jq .
276
+
277
+ JOB_ID=$(echo $JOB | jq -r .job_id)
278
+
279
+ # 3. Poll until completed
280
+ while true; do
281
+ STATUS=$(curl -s http://localhost:8000/jobs/$JOB_ID | jq -r .status)
282
+ PROGRESS=$(curl -s http://localhost:8000/jobs/$JOB_ID | jq -r .progress)
283
+ echo "Status: $STATUS Progress: $PROGRESS%"
284
+ [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] && break
285
+ sleep 5
286
+ done
287
+
288
+ # 4. Download the image
289
+ curl -s http://localhost:8000/jobs/$JOB_ID/download -o output.png
290
+ echo "Saved to output.png"
291
+
292
+ # 5. Delete the job + image
293
+ curl -s -X DELETE http://localhost:8000/jobs/$JOB_ID | jq .
294
+ ```
295
+
296
+ ---
297
+
298
+ ## Configuration (`.env`)
299
+
300
+ | Variable | Default | Description |
301
+ |---|---|---|
302
+ | `MODEL_ID` | `nota-ai/bk-sdm-small` | Hugging Face model repo ID |
303
+ | `MODEL_CACHE_DIR` | `./model_cache` | Where weights are cached |
304
+ | `AUTO_LOAD_MODEL` | `true` | Load model at startup |
305
+ | `CPU_THREADS` | `0` (all cores) | PyTorch thread count |
306
+ | `ENABLE_ATTENTION_SLICING` | `true` | Lower peak RAM usage |
307
+ | `DEFAULT_STEPS` | `20` | Default inference steps |
308
+ | `MAX_STEPS` | `50` | Request cap |
309
+ | `DEFAULT_WIDTH/HEIGHT` | `512` | Default image dimensions |
310
+ | `MAX_WIDTH/HEIGHT` | `768` | Request cap |
311
+ | `OUTPUTS_DIR` | `./outputs` | Where PNGs are saved |
312
+ | `PORT` | `8000` | HTTP port |
313
+ | `DEBUG` | `false` | Verbose logging + auto-reload |
314
+
315
+ ---
316
+
317
+ ## File Structure
318
+
319
+ ```
320
+ hf-image-api/
321
+ ├── main.py # FastAPI app + lifespan (startup/shutdown)
322
+ ├── config.py # Settings from environment / .env
323
+ ├── schemas.py # All Pydantic request & response models
324
+ ├── job_store.py # Thread-safe in-memory job registry
325
+ ├── pipeline_manager.py # HuggingFace Diffusers pipeline (CPU-tuned)
326
+ ├── worker.py # Background worker thread + FIFO job queue
327
+ ├── routes/
328
+ │ ├── generate.py # POST /generate
329
+ │ ├── jobs.py # GET/DELETE /jobs and /jobs/{id}/download
330
+ │ └── health.py # GET /health, GET /models, POST /models/load
331
+ ├── outputs/ # Generated PNG files (auto-created)
332
+ ├── model_cache/ # HuggingFace model weights cache (auto-created)
333
+ ├── requirements.txt
334
+ ├── .env.example
335
+ ├── start.sh
336
+ └── README.md
337
+ ```
338
+
339
+ ---
340
+
341
+ ## License
342
+
343
+ MIT — free to use and modify.
config.py ADDED
@@ -0,0 +1,64 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ config.py — All runtime settings loaded from environment / .env file.
3
+ """
4
+ from pydantic_settings import BaseSettings
5
+ from pydantic import Field
6
+ import os
7
+
8
+
9
+ class Settings(BaseSettings):
10
+ # ── Server ────────────────────────────────────────────────────────────────
11
+ host: str = Field("0.0.0.0", env="HOST")
12
+ port: int = Field(8000, env="PORT")
13
+ debug: bool = Field(False, env="DEBUG")
14
+
15
+ # ── Model ─────────────────────────────────────────────────────────────────
16
+ # Best CPU models (small → fast):
17
+ # "nota-ai/bk-sdm-small" (~500 MB, very fast on CPU)
18
+ # "runwayml/stable-diffusion-v1-5" (~4 GB, standard quality)
19
+ # "stabilityai/stable-diffusion-2-1-base" (~5 GB, higher quality)
20
+ model_id: str = Field(
21
+ "nota-ai/bk-sdm-small",
22
+ env="MODEL_ID",
23
+ )
24
+ model_cache_dir: str = Field("./model_cache", env="MODEL_CACHE_DIR")
25
+
26
+ # Load the pipeline at startup (recommended — avoids cold-start on first job)
27
+ auto_load_model: bool = Field(True, env="AUTO_LOAD_MODEL")
28
+
29
+ # ── CPU Optimisation ──────────────────────────────────────────────────────
30
+ # Number of CPU threads for PyTorch inference (0 = use all logical cores)
31
+ cpu_threads: int = Field(0, env="CPU_THREADS")
32
+
33
+ # Enable attention slicing (reduces peak RAM at slight speed cost)
34
+ enable_attention_slicing: bool = Field(True, env="ENABLE_ATTENTION_SLICING")
35
+
36
+ # Default inference steps (DPM++ scheduler works well at 20 steps on CPU)
37
+ default_steps: int = Field(20, env="DEFAULT_STEPS")
38
+ max_steps: int = Field(50, env="MAX_STEPS")
39
+
40
+ # Default image dimensions (512×512 is ideal for SD v1.x on CPU)
41
+ default_width: int = Field(512, env="DEFAULT_WIDTH")
42
+ default_height: int = Field(512, env="DEFAULT_HEIGHT")
43
+ max_width: int = Field(768, env="MAX_WIDTH")
44
+ max_height: int = Field(768, env="MAX_HEIGHT")
45
+
46
+ # Default guidance scale
47
+ default_guidance_scale: float = Field(7.5, env="DEFAULT_GUIDANCE_SCALE")
48
+
49
+ # ── Storage ───────────────────────────────────────────────────────────────
50
+ outputs_dir: str = Field("./outputs", env="OUTPUTS_DIR")
51
+
52
+ # Auto-delete completed jobs after N seconds (0 = never)
53
+ job_ttl_seconds: int = Field(0, env="JOB_TTL_SECONDS")
54
+
55
+ class Config:
56
+ env_file = ".env"
57
+ env_file_encoding = "utf-8"
58
+
59
+
60
+ settings = Settings()
61
+
62
+ # Resolve absolute output path
63
+ os.makedirs(settings.outputs_dir, exist_ok=True)
64
+ os.makedirs(settings.model_cache_dir, exist_ok=True)
job_store.py ADDED
@@ -0,0 +1,99 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ job_store.py — Thread-safe in-memory store for generation jobs.
3
+
4
+ Uses a plain threading.Lock so it is safe to call from both the FastAPI
5
+ async event-loop (via run_in_executor) and from the background worker thread.
6
+ """
7
+ from __future__ import annotations
8
+
9
+ import threading
10
+ import uuid
11
+ from datetime import datetime, timezone
12
+ from typing import Dict, List, Optional
13
+
14
+ from schemas import Job, JobStatus
15
+
16
+
17
+ class JobStore:
18
+ """Central store for all generation jobs."""
19
+
20
+ def __init__(self) -> None:
21
+ self._jobs: Dict[str, Job] = {}
22
+ self._lock = threading.Lock()
23
+
24
+ # ── Write operations ───────────────────────────────────────────────────────
25
+
26
+ def create(
27
+ self,
28
+ prompt: str,
29
+ negative_prompt: str,
30
+ params: dict,
31
+ model_id: Optional[str] = None,
32
+ ) -> Job:
33
+ job_id = str(uuid.uuid4())
34
+ job = Job(
35
+ job_id=job_id,
36
+ status=JobStatus.QUEUED,
37
+ prompt=prompt,
38
+ negative_prompt=negative_prompt,
39
+ params=params,
40
+ created_at=datetime.now(timezone.utc),
41
+ total_steps=params.get("num_inference_steps", 20),
42
+ model_id=model_id,
43
+ )
44
+ with self._lock:
45
+ self._jobs[job_id] = job
46
+ return job
47
+
48
+ def update(self, job_id: str, **kwargs) -> Optional[Job]:
49
+ with self._lock:
50
+ job = self._jobs.get(job_id)
51
+ if not job:
52
+ return None
53
+ for key, val in kwargs.items():
54
+ if hasattr(job, key):
55
+ setattr(job, key, val)
56
+ return job
57
+
58
+ def delete(self, job_id: str) -> Optional[Job]:
59
+ with self._lock:
60
+ return self._jobs.pop(job_id, None)
61
+
62
+ # ── Read operations ────────────────────────────────────────────────────────
63
+
64
+ def get(self, job_id: str) -> Optional[Job]:
65
+ with self._lock:
66
+ return self._jobs.get(job_id)
67
+
68
+ def list_all(
69
+ self,
70
+ status_filter: Optional[JobStatus] = None,
71
+ limit: int = 100,
72
+ offset: int = 0,
73
+ ) -> List[Job]:
74
+ with self._lock:
75
+ jobs = list(self._jobs.values())
76
+
77
+ # Apply optional status filter
78
+ if status_filter is not None:
79
+ jobs = [j for j in jobs if j.status == status_filter]
80
+
81
+ # Sort newest first
82
+ jobs.sort(key=lambda j: j.created_at, reverse=True)
83
+ return jobs[offset : offset + limit]
84
+
85
+ def counts_by_status(self) -> Dict[str, int]:
86
+ with self._lock:
87
+ result: Dict[str, int] = {s.value: 0 for s in JobStatus}
88
+ for job in self._jobs.values():
89
+ result[job.status.value] += 1
90
+ return result
91
+
92
+ @property
93
+ def total(self) -> int:
94
+ with self._lock:
95
+ return len(self._jobs)
96
+
97
+
98
+ # Singleton used throughout the application
99
+ job_store = JobStore()
main.py ADDED
@@ -0,0 +1,131 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ main.py — FastAPI application entry point.
3
+
4
+ Startup sequence
5
+ ────────────────
6
+ 1. Worker thread is started (daemon thread — auto-stops with the process).
7
+ 2. If AUTO_LOAD_MODEL=true, the HuggingFace pipeline is loaded in the
8
+ background so the first job doesn't include cold-start download time.
9
+ 3. The HTTP server starts accepting requests.
10
+
11
+ Run with:
12
+ uvicorn main:app --host 0.0.0.0 --port 8000 --reload
13
+ """
14
+ from __future__ import annotations
15
+
16
+ import logging
17
+ import os
18
+ import threading
19
+ from contextlib import asynccontextmanager
20
+
21
+ import uvicorn
22
+ from fastapi import FastAPI, Request
23
+ from fastapi.middleware.cors import CORSMiddleware
24
+ from fastapi.responses import JSONResponse
25
+
26
+ from config import settings
27
+ from routes import generate, health, jobs
28
+ from worker import start_worker
29
+
30
+ # ── Logging ───────────────────────────────────────────────────────────────────
31
+ logging.basicConfig(
32
+ level=logging.DEBUG if settings.debug else logging.INFO,
33
+ format="%(asctime)s %(levelname)-8s %(name)s %(message)s",
34
+ datefmt="%H:%M:%S",
35
+ )
36
+ logger = logging.getLogger("main")
37
+
38
+
39
+ # ── Lifespan (startup / shutdown) ─────────────────────────────────────────────
40
+
41
+ @asynccontextmanager
42
+ async def lifespan(app: FastAPI):
43
+ logger.info("═" * 60)
44
+ logger.info(" HF Image Generation API — starting up")
45
+ logger.info(" Model ID : %s", settings.model_id)
46
+ logger.info(" Outputs dir: %s", settings.outputs_dir)
47
+ logger.info(" CPU threads: %s", settings.cpu_threads or os.cpu_count())
48
+ logger.info("═" * 60)
49
+
50
+ # 1. Start background worker thread
51
+ start_worker()
52
+ logger.info("Background worker started.")
53
+
54
+ # 2. Optionally pre-load the pipeline
55
+ if settings.auto_load_model:
56
+ def _preload():
57
+ from pipeline_manager import pipeline_mgr
58
+ try:
59
+ pipeline_mgr.load()
60
+ except Exception as exc:
61
+ logger.exception("Pre-load failed: %s", exc)
62
+
63
+ t = threading.Thread(target=_preload, name="preload", daemon=True)
64
+ t.start()
65
+ logger.info("Pipeline pre-load started in background (AUTO_LOAD_MODEL=true).")
66
+ else:
67
+ logger.info("AUTO_LOAD_MODEL=false — pipeline will load on first job.")
68
+
69
+ yield # ← application runs here
70
+
71
+ logger.info("Shutting down.")
72
+
73
+
74
+ # ── App ───────────────────────────────────────────────────────────────────────
75
+
76
+ app = FastAPI(
77
+ title="HF CPU Image Generation API",
78
+ description=(
79
+ "Job-based REST API for Stable Diffusion image generation on CPU "
80
+ "using Hugging Face Diffusers. "
81
+ "Submit a job → poll status → download image → optionally delete."
82
+ ),
83
+ version="1.0.0",
84
+ lifespan=lifespan,
85
+ docs_url="/docs",
86
+ redoc_url="/redoc",
87
+ )
88
+
89
+ # CORS — allow everything by default (restrict in production)
90
+ app.add_middleware(
91
+ CORSMiddleware,
92
+ allow_origins=["*"],
93
+ allow_credentials=True,
94
+ allow_methods=["*"],
95
+ allow_headers=["*"],
96
+ )
97
+
98
+ # ── Global exception handler ───────────────────────────────────────────────────
99
+
100
+ @app.exception_handler(Exception)
101
+ async def global_exception_handler(request: Request, exc: Exception):
102
+ logger.exception("Unhandled error on %s %s: %s", request.method, request.url.path, exc)
103
+ return JSONResponse(
104
+ status_code=500,
105
+ content={"detail": "An internal server error occurred.", "error": str(exc)},
106
+ )
107
+
108
+ # ── Root redirect to docs ──────────────────────────────────────────────────────
109
+
110
+ @app.get("/", include_in_schema=False)
111
+ async def root():
112
+ from fastapi.responses import RedirectResponse
113
+ return RedirectResponse(url="/docs")
114
+
115
+ # ── Mount routers ──────────────────────────────────────────────────────────────
116
+
117
+ app.include_router(health.router)
118
+ app.include_router(generate.router)
119
+ app.include_router(jobs.router)
120
+
121
+
122
+ # ── Dev entrypoint ─────────────────────────────────────────────────────────────
123
+
124
+ if __name__ == "__main__":
125
+ uvicorn.run(
126
+ "main:app",
127
+ host=settings.host,
128
+ port=settings.port,
129
+ reload=settings.debug,
130
+ log_level="debug" if settings.debug else "info",
131
+ )
pipeline_manager.py ADDED
@@ -0,0 +1,199 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ pipeline_manager.py — Singleton that owns the Diffusers pipeline.
3
+
4
+ CPU optimisations applied:
5
+ • torch.float32 (float16 is GPU-only and causes NaN on CPU)
6
+ • enable_attention_slicing() — lower peak RAM usage
7
+ • DPMSolverMultistepScheduler — fast convergence in 15-20 steps
8
+ • torch.set_num_threads() — saturate all logical cores
9
+ • low_cpu_mem_usage=True — stream weights into RAM, don't double-buffer
10
+ • safety_checker=None — skip the NSFW binary classifier (saves ~300 MB RAM)
11
+
12
+ Loading is thread-safe; only one thread can load at a time.
13
+ """
14
+ from __future__ import annotations
15
+
16
+ import logging
17
+ import os
18
+ import threading
19
+ from typing import Callable, Optional, Tuple
20
+
21
+ logger = logging.getLogger("pipeline_manager")
22
+
23
+
24
+ class PipelineManager:
25
+
26
+ def __init__(self) -> None:
27
+ self._pipe = None
28
+ self._model_id: Optional[str] = None
29
+ self._loading = False
30
+ self._lock = threading.Lock()
31
+
32
+ # ── Public API ─────────────────────────────────────────────────────────────
33
+
34
+ @property
35
+ def is_loaded(self) -> bool:
36
+ return self._pipe is not None
37
+
38
+ @property
39
+ def is_loading(self) -> bool:
40
+ return self._loading
41
+
42
+ @property
43
+ def current_model_id(self) -> Optional[str]:
44
+ return self._model_id
45
+
46
+ def load(self, model_id: Optional[str] = None) -> None:
47
+ """Load (or hot-swap) the pipeline. Blocks the calling thread until done."""
48
+ from config import settings
49
+ import torch
50
+ from diffusers import (
51
+ StableDiffusionPipeline,
52
+ DPMSolverMultistepScheduler,
53
+ )
54
+
55
+ target_model = model_id or settings.model_id
56
+
57
+ with self._lock:
58
+ if self._loading:
59
+ logger.warning("Pipeline is already loading — skipping duplicate load request.")
60
+ return
61
+ self._loading = True
62
+
63
+ try:
64
+ logger.info("Loading pipeline: %s", target_model)
65
+
66
+ # ── CPU thread tuning ──────────────────────────────────────────────
67
+ n_threads = settings.cpu_threads or os.cpu_count() or 4
68
+ torch.set_num_threads(n_threads)
69
+ logger.info("PyTorch CPU threads set to %d", n_threads)
70
+
71
+ # ── Load the pipeline ──────────────────────────────────────────────
72
+ pipe = StableDiffusionPipeline.from_pretrained(
73
+ target_model,
74
+ torch_dtype=torch.float32, # mandatory for CPU
75
+ low_cpu_mem_usage=True, # stream tensors, avoid double RAM
76
+ safety_checker=None, # skip NSFW checker (~300 MB RAM saved)
77
+ requires_safety_checker=False,
78
+ cache_dir=settings.model_cache_dir,
79
+ )
80
+
81
+ # ── Move to CPU explicitly ─────────────────────────────────────────
82
+ pipe = pipe.to("cpu")
83
+
84
+ # ── Swap scheduler: DPM++ 2M — best quality/speed on CPU ──────────
85
+ pipe.scheduler = DPMSolverMultistepScheduler.from_config(
86
+ pipe.scheduler.config,
87
+ use_karras_sigmas=True, # smoother sampling curve
88
+ )
89
+
90
+ # ── Memory optimisations ───────────────────────────────────────────
91
+ if settings.enable_attention_slicing:
92
+ pipe.enable_attention_slicing(slice_size=1)
93
+
94
+ # ── Optional: torch.compile (PyTorch ≥ 2.0 only) ─────────────────
95
+ # Disabled by default: first-run compilation takes minutes on CPU
96
+ # and saves ~5-10 % on subsequent calls. Enable manually if needed:
97
+ # pipe.unet = torch.compile(pipe.unet, backend="inductor")
98
+
99
+ with self._lock:
100
+ self._pipe = pipe
101
+ self._model_id = target_model
102
+ self._loading = False
103
+
104
+ logger.info("Pipeline ready: %s", target_model)
105
+
106
+ except Exception as exc:
107
+ with self._lock:
108
+ self._loading = False
109
+ logger.exception("Failed to load pipeline: %s", exc)
110
+ raise
111
+
112
+ def generate(
113
+ self,
114
+ prompt: str,
115
+ negative_prompt: str,
116
+ width: int,
117
+ height: int,
118
+ num_inference_steps: int,
119
+ guidance_scale: float,
120
+ seed: int,
121
+ scheduler_name: str,
122
+ step_callback: Optional[Callable] = None,
123
+ ) -> Tuple["PIL.Image.Image", int]:
124
+ """
125
+ Run inference and return (PIL image, seed_used).
126
+ Blocks the calling thread — always call from the worker thread.
127
+ """
128
+ import torch
129
+ from diffusers import (
130
+ DPMSolverMultistepScheduler,
131
+ EulerAncestralDiscreteScheduler,
132
+ EulerDiscreteScheduler,
133
+ PNDMScheduler,
134
+ )
135
+
136
+ if not self._pipe:
137
+ raise RuntimeError("Pipeline is not loaded. Call load() first.")
138
+
139
+ pipe = self._pipe
140
+
141
+ # ── Swap scheduler if requested ────────────────────────────────────────
142
+ scheduler_map = {
143
+ "dpm++": DPMSolverMultistepScheduler,
144
+ "euler_a": EulerAncestralDiscreteScheduler,
145
+ "euler": EulerDiscreteScheduler,
146
+ "pndm": PNDMScheduler,
147
+ }
148
+ SchedulerClass = scheduler_map.get(scheduler_name, DPMSolverMultistepScheduler)
149
+ pipe.scheduler = SchedulerClass.from_config(pipe.scheduler.config)
150
+
151
+ # ── Seed handling ──────────────────────────────────────────────────────
152
+ import random
153
+ used_seed = seed if seed != -1 else random.randint(0, 2**32 - 1)
154
+ generator = torch.Generator(device="cpu").manual_seed(used_seed)
155
+
156
+ # ── Step progress callback ─────────────────────────────────────────────
157
+ # Build a callback compatible with both old and new diffusers APIs
158
+ total_steps = num_inference_steps
159
+
160
+ def _legacy_callback(step: int, timestep, latents):
161
+ if step_callback:
162
+ step_callback(step + 1, total_steps)
163
+
164
+ def _new_callback(pipeline, step: int, timestep, callback_kwargs: dict):
165
+ if step_callback:
166
+ step_callback(step + 1, total_steps)
167
+ return callback_kwargs
168
+
169
+ import diffusers
170
+ diffusers_version = tuple(int(x) for x in diffusers.__version__.split(".")[:2])
171
+
172
+ call_kwargs = dict(
173
+ prompt=prompt,
174
+ negative_prompt=negative_prompt,
175
+ width=width,
176
+ height=height,
177
+ num_inference_steps=num_inference_steps,
178
+ guidance_scale=guidance_scale,
179
+ generator=generator,
180
+ )
181
+
182
+ if diffusers_version >= (0, 25):
183
+ # New API: callback_on_step_end
184
+ call_kwargs["callback_on_step_end"] = _new_callback
185
+ else:
186
+ # Legacy API
187
+ call_kwargs["callback"] = _legacy_callback
188
+ call_kwargs["callback_steps"] = 1
189
+
190
+ # ── Run inference ──────────────────────────────────────────────────────
191
+ with torch.inference_mode():
192
+ result = pipe(**call_kwargs)
193
+
194
+ image = result.images[0]
195
+ return image, used_seed
196
+
197
+
198
+ # Singleton used throughout the application
199
+ pipeline_mgr = PipelineManager()
requirements.txt ADDED
@@ -0,0 +1,20 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Core API
2
+ fastapi>=0.111.0
3
+ uvicorn[standard]>=0.29.0
4
+ python-multipart>=0.0.9
5
+
6
+ # Hugging Face / Diffusers (CPU-optimised)
7
+ diffusers>=0.27.0
8
+ transformers>=4.40.0
9
+ accelerate>=0.30.0
10
+ safetensors>=0.4.3
11
+
12
+ # PyTorch CPU-only (install via pip before running this file — see README)
13
+ # pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
14
+
15
+ # Utilities
16
+ Pillow>=10.3.0
17
+ python-dotenv>=1.0.1
18
+ pydantic>=2.7.0
19
+ pydantic-settings>=2.2.1
20
+ aiofiles>=23.2.1
routes/__init__.py ADDED
File without changes
routes/generate.py ADDED
@@ -0,0 +1,81 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ routes/generate.py — Image generation job submission.
3
+
4
+ POST /generate
5
+ → Validates the request, creates a queued job, enqueues it for the
6
+ background worker, and immediately returns the job_id.
7
+ The caller then polls GET /jobs/{job_id} for progress/status.
8
+ """
9
+ from __future__ import annotations
10
+
11
+ import logging
12
+
13
+ from fastapi import APIRouter, HTTPException
14
+
15
+ from config import settings
16
+ from job_store import job_store
17
+ from pipeline_manager import pipeline_mgr
18
+ from schemas import GenerateRequest, JobSubmittedResponse, JobStatus
19
+ from worker import enqueue, queue_position, queue_size
20
+
21
+ logger = logging.getLogger("routes.generate")
22
+ router = APIRouter(tags=["Generation"])
23
+
24
+
25
+ @router.post(
26
+ "/generate",
27
+ response_model=JobSubmittedResponse,
28
+ status_code=202, # 202 Accepted — work is deferred
29
+ summary="Submit an image generation job",
30
+ description=(
31
+ "Validates the prompt and parameters, creates a queued job, "
32
+ "and returns a `job_id` immediately. "
33
+ "Poll `GET /jobs/{job_id}` to track progress. "
34
+ "Download the result with `GET /jobs/{job_id}/download` once `status == 'completed'`."
35
+ ),
36
+ )
37
+ async def submit_generate(body: GenerateRequest) -> JobSubmittedResponse:
38
+ # Guard: pipeline must exist (or be auto-loaded at startup)
39
+ if not pipeline_mgr.is_loaded and not pipeline_mgr.is_loading:
40
+ # Try to trigger a load if the operator hasn't done so
41
+ logger.warning(
42
+ "Pipeline not loaded — prompting load of default model '%s'.",
43
+ settings.model_id,
44
+ )
45
+ # We don't block here; the worker will call load() itself before processing
46
+ # But we warn the user so they know latency is higher for the first job.
47
+
48
+ params = {
49
+ "width": body.width,
50
+ "height": body.height,
51
+ "num_inference_steps": body.num_inference_steps,
52
+ "guidance_scale": body.guidance_scale,
53
+ "seed": body.seed,
54
+ "scheduler": body.scheduler.value,
55
+ }
56
+
57
+ # Create and enqueue
58
+ job = job_store.create(
59
+ prompt=body.prompt,
60
+ negative_prompt=body.negative_prompt,
61
+ params=params,
62
+ model_id=pipeline_mgr.current_model_id or settings.model_id,
63
+ )
64
+ enqueue(job.job_id)
65
+
66
+ position = queue_position(job.job_id)
67
+ msg = (
68
+ f"Job queued at position {position}."
69
+ if position > 1
70
+ else "Job is next in queue and will start immediately."
71
+ )
72
+ if not pipeline_mgr.is_loaded:
73
+ msg += " Note: the model pipeline is not yet loaded — first job will include model load time."
74
+
75
+ return JobSubmittedResponse(
76
+ job_id=job.job_id,
77
+ status=JobStatus.QUEUED,
78
+ created_at=job.created_at,
79
+ queue_position=position,
80
+ message=msg,
81
+ )
routes/health.py ADDED
@@ -0,0 +1,111 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ routes/health.py — Health check and model management endpoints.
3
+
4
+ GET /health → system status and pipeline info
5
+ GET /models → list of well-known CPU-friendly model IDs
6
+ POST /models/load → hot-swap the loaded pipeline
7
+ """
8
+ from __future__ import annotations
9
+
10
+ import logging
11
+ import threading
12
+
13
+ from fastapi import APIRouter, BackgroundTasks, HTTPException
14
+
15
+ from config import settings
16
+ from job_store import job_store
17
+ from pipeline_manager import pipeline_mgr
18
+ from schemas import HealthResponse, LoadModelRequest, LoadModelResponse
19
+ from worker import queue_size
20
+
21
+ logger = logging.getLogger("routes.health")
22
+ router = APIRouter(tags=["System"])
23
+
24
+
25
+ # ── Health ────────────────────────────────────────────────────────────────────
26
+
27
+ @router.get(
28
+ "/health",
29
+ response_model=HealthResponse,
30
+ summary="Service health and pipeline status",
31
+ )
32
+ async def health() -> HealthResponse:
33
+ counts = job_store.counts_by_status()
34
+ return HealthResponse(
35
+ status="ok" if pipeline_mgr.is_loaded else ("loading" if pipeline_mgr.is_loading else "idle"),
36
+ model_id=pipeline_mgr.current_model_id,
37
+ pipeline_loaded=pipeline_mgr.is_loaded,
38
+ loading=pipeline_mgr.is_loading,
39
+ queue_size=queue_size(),
40
+ jobs_total=job_store.total,
41
+ jobs_by_status=counts,
42
+ cpu_threads=settings.cpu_threads or (__import__("os").cpu_count() or 4),
43
+ outputs_dir=settings.outputs_dir,
44
+ )
45
+
46
+
47
+ # ── Model catalogue ────────────────────────────────────────────────────────────
48
+
49
+ _KNOWN_MODELS = [
50
+ {
51
+ "model_id": "nota-ai/bk-sdm-small",
52
+ "label": "BK-SDM Small (recommended for CPU)",
53
+ "size_gb": 0.5,
54
+ "notes": "Very fast on CPU. ~60-120s per 512×512 image at 20 steps.",
55
+ },
56
+ {
57
+ "model_id": "runwayml/stable-diffusion-v1-5",
58
+ "label": "Stable Diffusion v1.5",
59
+ "size_gb": 4.0,
60
+ "notes": "Standard quality. ~150-300s per 512×512 on CPU.",
61
+ },
62
+ {
63
+ "model_id": "stabilityai/stable-diffusion-2-1-base",
64
+ "label": "Stable Diffusion 2.1 Base",
65
+ "size_gb": 5.2,
66
+ "notes": "Higher quality. ~200-400s per 512×512 on CPU.",
67
+ },
68
+ {
69
+ "model_id": "CompVis/stable-diffusion-v1-4",
70
+ "label": "Stable Diffusion v1.4 (original)",
71
+ "size_gb": 4.0,
72
+ "notes": "Historical baseline. SD v1.5 is preferred.",
73
+ },
74
+ ]
75
+
76
+
77
+ @router.get(
78
+ "/models",
79
+ summary="List supported CPU-friendly model IDs",
80
+ )
81
+ async def list_models() -> dict:
82
+ return {
83
+ "current_model": pipeline_mgr.current_model_id,
84
+ "models": _KNOWN_MODELS,
85
+ }
86
+
87
+
88
+ # ── Hot-swap model ─────────────────────────────────────────────────────────────
89
+
90
+ @router.post(
91
+ "/models/load",
92
+ response_model=LoadModelResponse,
93
+ summary="Load (or hot-swap) a Hugging Face model",
94
+ )
95
+ async def load_model(body: LoadModelRequest, background_tasks: BackgroundTasks) -> LoadModelResponse:
96
+ if pipeline_mgr.is_loading:
97
+ raise HTTPException(status_code=409, detail="A model is already loading. Try again shortly.")
98
+
99
+ def _load():
100
+ try:
101
+ pipeline_mgr.load(body.model_id)
102
+ except Exception as exc:
103
+ logger.exception("Background model load failed: %s", exc)
104
+
105
+ background_tasks.add_task(_load)
106
+
107
+ return LoadModelResponse(
108
+ ok=True,
109
+ model_id=body.model_id,
110
+ message=f"Loading '{body.model_id}' in the background. Poll GET /health to check status.",
111
+ )
routes/jobs.py ADDED
@@ -0,0 +1,160 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ routes/jobs.py — Job lifecycle management.
3
+
4
+ GET /jobs → list all jobs (filterable)
5
+ GET /jobs/{job_id} → single job status / progress
6
+ GET /jobs/{job_id}/download → download the generated PNG
7
+ DELETE /jobs/{job_id} → cancel or delete a job and its image
8
+ """
9
+ from __future__ import annotations
10
+
11
+ import logging
12
+ import mimetypes
13
+ import os
14
+ from typing import Optional
15
+
16
+ from fastapi import APIRouter, HTTPException, Query
17
+ from fastapi.responses import FileResponse
18
+
19
+ from config import settings
20
+ from job_store import job_store
21
+ from schemas import DeleteJobResponse, Job, JobListResponse, JobStatus
22
+
23
+ logger = logging.getLogger("routes.jobs")
24
+ router = APIRouter(prefix="/jobs", tags=["Jobs"])
25
+
26
+
27
+ # ── List jobs ─────────────────────────────────────────────────────────────────
28
+
29
+ @router.get(
30
+ "",
31
+ response_model=JobListResponse,
32
+ summary="List all jobs",
33
+ )
34
+ async def list_jobs(
35
+ status: Optional[JobStatus] = Query(None, description="Filter by job status."),
36
+ limit: int = Query(50, ge=1, le=200),
37
+ offset: int = Query(0, ge=0),
38
+ ) -> JobListResponse:
39
+ jobs = job_store.list_all(status_filter=status, limit=limit, offset=offset)
40
+ counts = job_store.counts_by_status()
41
+ return JobListResponse(
42
+ jobs=jobs,
43
+ total=job_store.total,
44
+ queued=counts.get("queued", 0),
45
+ processing=counts.get("processing", 0),
46
+ completed=counts.get("completed", 0),
47
+ failed=counts.get("failed", 0),
48
+ )
49
+
50
+
51
+ # ── Single job status ─────────────────────────────────────────────────────────
52
+
53
+ @router.get(
54
+ "/{job_id}",
55
+ response_model=Job,
56
+ summary="Get job status and progress",
57
+ description=(
58
+ "Poll this endpoint to track a generation job. "
59
+ "When `status == 'completed'` the `download_url` field is populated."
60
+ ),
61
+ )
62
+ async def get_job(job_id: str) -> Job:
63
+ job = job_store.get(job_id)
64
+ if not job:
65
+ raise HTTPException(status_code=404, detail=f"Job '{job_id}' not found.")
66
+ return job
67
+
68
+
69
+ # ── Download generated image ──────────────────────────────────────────────────
70
+
71
+ @router.get(
72
+ "/{job_id}/download",
73
+ summary="Download the generated image",
74
+ description=(
75
+ "Returns the PNG image as a file attachment. "
76
+ "Only available when `status == 'completed'`."
77
+ ),
78
+ responses={
79
+ 200: {"content": {"image/png": {}}},
80
+ 202: {"description": "Job is still processing."},
81
+ 404: {"description": "Job not found or image missing."},
82
+ },
83
+ )
84
+ async def download_image(job_id: str):
85
+ job = job_store.get(job_id)
86
+ if not job:
87
+ raise HTTPException(status_code=404, detail=f"Job '{job_id}' not found.")
88
+
89
+ if job.status == JobStatus.QUEUED:
90
+ raise HTTPException(status_code=202, detail="Job is queued and has not started yet.")
91
+
92
+ if job.status == JobStatus.PROCESSING:
93
+ raise HTTPException(
94
+ status_code=202,
95
+ detail=f"Job is still processing ({job.progress}% complete).",
96
+ )
97
+
98
+ if job.status == JobStatus.FAILED:
99
+ raise HTTPException(status_code=422, detail=f"Job failed: {job.error}")
100
+
101
+ if not job.image_filename:
102
+ raise HTTPException(status_code=500, detail="Job completed but image filename is missing.")
103
+
104
+ image_path = os.path.join(settings.outputs_dir, job.image_filename)
105
+ if not os.path.isfile(image_path):
106
+ raise HTTPException(
107
+ status_code=404,
108
+ detail=f"Image file '{job.image_filename}' not found on disk. It may have been deleted.",
109
+ )
110
+
111
+ return FileResponse(
112
+ path=image_path,
113
+ media_type="image/png",
114
+ filename=job.image_filename,
115
+ headers={"Content-Disposition": f'attachment; filename="{job.image_filename}"'},
116
+ )
117
+
118
+
119
+ # ── Delete job ─────────────────────────────────────────────────────────────────
120
+
121
+ @router.delete(
122
+ "/{job_id}",
123
+ response_model=DeleteJobResponse,
124
+ summary="Delete a job and its generated image",
125
+ description=(
126
+ "Removes the job record from memory and deletes the PNG from disk "
127
+ "(if it exists). Queued or processing jobs are also removed — "
128
+ "the worker will skip orphaned job IDs gracefully."
129
+ ),
130
+ )
131
+ async def delete_job(job_id: str) -> DeleteJobResponse:
132
+ job = job_store.get(job_id)
133
+ if not job:
134
+ raise HTTPException(status_code=404, detail=f"Job '{job_id}' not found.")
135
+
136
+ # Delete image file from disk
137
+ image_deleted = False
138
+ if job.image_filename:
139
+ image_path = os.path.join(settings.outputs_dir, job.image_filename)
140
+ if os.path.isfile(image_path):
141
+ try:
142
+ os.remove(image_path)
143
+ image_deleted = True
144
+ logger.info("Deleted image: %s", image_path)
145
+ except OSError as exc:
146
+ logger.warning("Could not delete image %s: %s", image_path, exc)
147
+
148
+ # Remove job record
149
+ job_store.delete(job_id)
150
+ logger.info("Deleted job record: %s", job_id)
151
+
152
+ return DeleteJobResponse(
153
+ ok=True,
154
+ job_id=job_id,
155
+ image_deleted=image_deleted,
156
+ message=(
157
+ f"Job {job_id} deleted."
158
+ + (" Image file removed from disk." if image_deleted else "")
159
+ ),
160
+ )
schemas.py ADDED
@@ -0,0 +1,132 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ schemas.py — All Pydantic models for request bodies and API responses.
3
+ """
4
+ from __future__ import annotations
5
+ from enum import Enum
6
+ from typing import Any, Dict, Optional
7
+ from datetime import datetime
8
+ from pydantic import BaseModel, Field, model_validator
9
+
10
+
11
+ # ── Enums ─────────────────────────────────────────────────────────────────────
12
+
13
+ class JobStatus(str, Enum):
14
+ QUEUED = "queued"
15
+ PROCESSING = "processing"
16
+ COMPLETED = "completed"
17
+ FAILED = "failed"
18
+
19
+
20
+ class Scheduler(str, Enum):
21
+ DPM_PLUS_PLUS = "dpm++" # DPMSolverMultistepScheduler — best for CPU (fast convergence)
22
+ EULER_A = "euler_a" # EulerAncestralDiscreteScheduler
23
+ EULER = "euler" # EulerDiscreteScheduler
24
+ PNDM = "pndm" # PNDMScheduler
25
+
26
+
27
+ # ── Request bodies ─────────────────────────────────────────────────────────────
28
+
29
+ class GenerateRequest(BaseModel):
30
+ prompt: str = Field(
31
+ ...,
32
+ min_length=1,
33
+ max_length=1500,
34
+ description="Text prompt describing the image to generate.",
35
+ examples=["a photorealistic cat sitting on a wooden table, soft light"],
36
+ )
37
+ negative_prompt: str = Field(
38
+ "blurry, ugly, low quality, distorted, watermark, text, nsfw",
39
+ max_length=1000,
40
+ description="Things to exclude from the image.",
41
+ )
42
+ width: int = Field(512, ge=256, le=768, multiple_of=8, description="Image width (pixels, multiple of 8).")
43
+ height: int = Field(512, ge=256, le=768, multiple_of=8, description="Image height (pixels, multiple of 8).")
44
+ num_inference_steps: int = Field(20, ge=1, le=50, description="Denoising steps. 15–20 is optimal on CPU.")
45
+ guidance_scale: float = Field(7.5, ge=1.0, le=20.0, description="Classifier-free guidance scale.")
46
+ seed: int = Field(-1, ge=-1, description="RNG seed. -1 = random each time.")
47
+ scheduler: Scheduler = Field(Scheduler.DPM_PLUS_PLUS, description="Noise scheduler algorithm.")
48
+
49
+ @model_validator(mode="after")
50
+ def clamp_to_config(self) -> "GenerateRequest":
51
+ from config import settings
52
+ self.width = min(self.width, settings.max_width)
53
+ self.height = min(self.height, settings.max_height)
54
+ self.num_inference_steps = min(self.num_inference_steps, settings.max_steps)
55
+ return self
56
+
57
+
58
+ class LoadModelRequest(BaseModel):
59
+ model_id: str = Field(
60
+ ...,
61
+ description="Hugging Face model repo ID, e.g. 'runwayml/stable-diffusion-v1-5'.",
62
+ )
63
+
64
+
65
+ # ── Job model ─────────────────────────────────────────────────────────────────
66
+
67
+ class Job(BaseModel):
68
+ job_id: str
69
+ status: JobStatus
70
+ prompt: str
71
+ negative_prompt: str
72
+ params: Dict[str, Any]
73
+
74
+ created_at: datetime
75
+ started_at: Optional[datetime] = None
76
+ completed_at: Optional[datetime] = None
77
+
78
+ progress: int = 0 # 0–100
79
+ current_step: int = 0
80
+ total_steps: int = 0
81
+
82
+ image_filename: Optional[str] = None # filename inside outputs/
83
+ download_url: Optional[str] = None # relative URL
84
+ duration_seconds: Optional[float] = None
85
+
86
+ error: Optional[str] = None
87
+
88
+ model_id: Optional[str] = None # model used for this job
89
+
90
+
91
+ # ── Response wrappers ─────────────────────────────────────────────────────────
92
+
93
+ class JobSubmittedResponse(BaseModel):
94
+ job_id: str
95
+ status: JobStatus
96
+ created_at: datetime
97
+ queue_position: int
98
+ message: str
99
+
100
+
101
+ class JobListResponse(BaseModel):
102
+ jobs: list[Job]
103
+ total: int
104
+ queued: int
105
+ processing: int
106
+ completed: int
107
+ failed: int
108
+
109
+
110
+ class DeleteJobResponse(BaseModel):
111
+ ok: bool
112
+ job_id: str
113
+ image_deleted: bool
114
+ message: str
115
+
116
+
117
+ class HealthResponse(BaseModel):
118
+ status: str
119
+ model_id: Optional[str]
120
+ pipeline_loaded: bool
121
+ loading: bool
122
+ queue_size: int
123
+ jobs_total: int
124
+ jobs_by_status: Dict[str, int]
125
+ cpu_threads: int
126
+ outputs_dir: str
127
+
128
+
129
+ class LoadModelResponse(BaseModel):
130
+ ok: bool
131
+ model_id: str
132
+ message: str
start.sh ADDED
@@ -0,0 +1,44 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env bash
2
+ # start.sh — Quick-start script for the HF CPU Image Generation API
3
+ set -e
4
+
5
+ VENV_DIR=".venv"
6
+
7
+ echo ""
8
+ echo "═══════════════════════════════════════════════════════════════"
9
+ echo " HF CPU Image Generation API — Setup & Start"
10
+ echo "═══════════════════════════════════════════════════════════════"
11
+ echo ""
12
+
13
+ # ── 1. Create virtualenv if needed ────────────────────────────────────────────
14
+ if [ ! -d "$VENV_DIR" ]; then
15
+ echo "→ Creating Python virtualenv in $VENV_DIR ..."
16
+ python3 -m venv "$VENV_DIR"
17
+ fi
18
+
19
+ source "$VENV_DIR/bin/activate"
20
+
21
+ # ── 2. Install PyTorch (CPU-only wheel) ───────────────────────────────────────
22
+ if ! python -c "import torch" 2>/dev/null; then
23
+ echo "→ Installing PyTorch (CPU-only) ..."
24
+ pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu -q
25
+ fi
26
+
27
+ # ── 3. Install other dependencies ─────────────────────────────────────────────
28
+ echo "→ Installing dependencies from requirements.txt ..."
29
+ pip install -r requirements.txt -q
30
+
31
+ # ── 4. Copy .env if not present ───────────────────────────────────────────────
32
+ if [ ! -f ".env" ]; then
33
+ echo "→ Creating .env from .env.example ..."
34
+ cp .env.example .env
35
+ fi
36
+
37
+ # ── 5. Start the API ──────────────────────────────────────────────────────────
38
+ echo ""
39
+ echo "→ Starting API on http://0.0.0.0:8000"
40
+ echo " Swagger UI: http://localhost:8000/docs"
41
+ echo " API health: http://localhost:8000/health"
42
+ echo ""
43
+
44
+ python -m uvicorn main:app --host 0.0.0.0 --port 8000 --workers 1
worker.py ADDED
@@ -0,0 +1,179 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ worker.py — Single background thread that processes generation jobs one at a time.
3
+
4
+ Architecture:
5
+ ┌────────────────────┐ queue.put(job_id) ┌──────────────────────┐
6
+ │ FastAPI endpoint │ ────────────────────────────► │ _job_queue (Queue) │
7
+ │ POST /generate │ └──────────┬───────────┘
8
+ └────────────────────┘ │ .get()
9
+ ▼
10
+ ┌──────────────────────┐
11
+ │ worker_loop() │
12
+ │ (daemon thread) │
13
+ │ runs _process_job() │
14
+ └──────────────────────┘
15
+
16
+ Only one job runs at a time — CPU inference is single-threaded anyway.
17
+ """
18
+ from __future__ import annotations
19
+
20
+ import logging
21
+ import os
22
+ import queue
23
+ import threading
24
+ from datetime import datetime, timezone
25
+ from typing import List
26
+
27
+ logger = logging.getLogger("worker")
28
+
29
+ # Internal FIFO queue — contains job_ids as strings
30
+ _job_queue: queue.Queue[str] = queue.Queue()
31
+
32
+ # Lock used to inspect queue contents safely
33
+ _queue_lock = threading.Lock()
34
+
35
+ # Ordered list of pending job IDs (mirrors the queue for position lookups)
36
+ _pending: List[str] = []
37
+ _pending_lock = threading.Lock()
38
+
39
+
40
+ # ── Public helpers (called from FastAPI routes) ────────────────────────────────
41
+
42
+ def enqueue(job_id: str) -> None:
43
+ """Add a job to the processing queue."""
44
+ with _pending_lock:
45
+ _pending.append(job_id)
46
+ _job_queue.put(job_id)
47
+ logger.info("Enqueued job %s (queue size: %d)", job_id, _job_queue.qsize())
48
+
49
+
50
+ def queue_position(job_id: str) -> int:
51
+ """Return the 1-based position of job_id in the pending queue (0 if not found)."""
52
+ with _pending_lock:
53
+ try:
54
+ return _pending.index(job_id) + 1
55
+ except ValueError:
56
+ return 0
57
+
58
+
59
+ def queue_size() -> int:
60
+ """Number of jobs still waiting (does not include the currently running job)."""
61
+ return _job_queue.qsize()
62
+
63
+
64
+ # ── Core processing ────────────────────────────────────────────────────────────
65
+
66
+ def _process_job(job_id: str) -> None:
67
+ """Generate an image for one job. All state mutations go through job_store."""
68
+ from config import settings
69
+ from job_store import job_store
70
+ from pipeline_manager import pipeline_mgr
71
+ from schemas import JobStatus
72
+
73
+ job = job_store.get(job_id)
74
+ if not job:
75
+ logger.warning("Job %s not found in store — skipping.", job_id)
76
+ return
77
+
78
+ # Mark as processing
79
+ job_store.update(
80
+ job_id,
81
+ status=JobStatus.PROCESSING,
82
+ started_at=datetime.now(timezone.utc),
83
+ progress=0,
84
+ )
85
+ logger.info("Processing job %s prompt=%r", job_id, job.prompt[:60])
86
+
87
+ try:
88
+ # ── Ensure pipeline is loaded ──────────────────────────────────────────
89
+ if not pipeline_mgr.is_loaded:
90
+ logger.info("Pipeline not loaded — loading now (job %s will wait).", job_id)
91
+ pipeline_mgr.load()
92
+
93
+ p = job.params
94
+
95
+ # ── Step-progress callback ─────────────────────────────────────────────
96
+ def on_step(step: int, total: int) -> None:
97
+ pct = int(step / total * 95) # reserve last 5 % for save
98
+ job_store.update(job_id, progress=pct, current_step=step, total_steps=total)
99
+
100
+ # ── Inference ─────────────────────────────────────────────────────────
101
+ image, used_seed = pipeline_mgr.generate(
102
+ prompt=job.prompt,
103
+ negative_prompt=job.negative_prompt,
104
+ width=p.get("width", settings.default_width),
105
+ height=p.get("height", settings.default_height),
106
+ num_inference_steps=p.get("num_inference_steps", settings.default_steps),
107
+ guidance_scale=p.get("guidance_scale", settings.default_guidance_scale),
108
+ seed=p.get("seed", -1),
109
+ scheduler_name=p.get("scheduler", "dpm++"),
110
+ step_callback=on_step,
111
+ )
112
+
113
+ # ── Save image ────────────────────────────────────────────────────────
114
+ job_store.update(job_id, progress=97)
115
+
116
+ timestamp = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
117
+ filename = f"{timestamp}_{job_id[:8]}_{used_seed}.png"
118
+ abs_path = os.path.join(settings.outputs_dir, filename)
119
+ image.save(abs_path, format="PNG", optimize=False)
120
+
121
+ # ── Compute duration ───────────────────────────────────────────────────
122
+ now = datetime.now(timezone.utc)
123
+ started = job_store.get(job_id).started_at
124
+ duration = (now - started).total_seconds() if started else None
125
+
126
+ job_store.update(
127
+ job_id,
128
+ status=JobStatus.COMPLETED,
129
+ completed_at=now,
130
+ progress=100,
131
+ image_filename=filename,
132
+ download_url=f"/jobs/{job_id}/download",
133
+ duration_seconds=round(duration, 2) if duration else None,
134
+ )
135
+
136
+ logger.info(
137
+ "Job %s completed in %.1f s → %s",
138
+ job_id,
139
+ duration or 0,
140
+ filename,
141
+ )
142
+
143
+ except Exception as exc:
144
+ logger.exception("Job %s failed: %s", job_id, exc)
145
+ job_store.update(
146
+ job_id,
147
+ status=JobStatus.FAILED,
148
+ completed_at=datetime.now(timezone.utc),
149
+ error=str(exc),
150
+ progress=0,
151
+ )
152
+
153
+
154
+ # ── Worker loop (runs in its own daemon thread) ────────────────────────────────
155
+
156
+ def worker_loop() -> None:
157
+ """Infinite loop: pull job IDs from the queue and process them."""
158
+ logger.info("Worker thread started.")
159
+ while True:
160
+ job_id = _job_queue.get() # blocks until a job arrives
161
+ with _pending_lock:
162
+ try:
163
+ _pending.remove(job_id)
164
+ except ValueError:
165
+ pass
166
+ try:
167
+ _process_job(job_id)
168
+ except Exception as exc:
169
+ # Catch-all safety net — the loop must never crash
170
+ logger.exception("Unhandled error in worker for job %s: %s", job_id, exc)
171
+ finally:
172
+ _job_queue.task_done()
173
+
174
+
175
+ def start_worker() -> threading.Thread:
176
+ """Spawn and return the daemon worker thread. Call once at application startup."""
177
+ t = threading.Thread(target=worker_loop, name="image-worker", daemon=True)
178
+ t.start()
179
+ return t