# 4o-ghibli-at-home **Repository Path**: github-rocks/4o-ghibli-at-home ## Basic Information - **Project Name**: 4o-ghibli-at-home - **Description**: The GPT-4o image generation we have at home. A powerful, self-hosted AI photo stylizer built for performance and privacy. - **Primary Language**: Unknown - **License**: AGPL-3.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-04-02 - **Last Updated**: 2026-04-07 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # GPT-4o Ghibli At Home: Your Private & Local AI Photo Stylizer **Welcome to 4o-ghibli-at-home! Your own local and private, high-performance AI photo stylizer, powered by an enhanced `FLUX.1-Kontext-dev` and `DFloat11` model pipeline.** This is not just a Ghibli-fier! The app has dozens of style profiles and advanced controls, you can transform your photos into everything from oil paintings and comic book art to cyberpunk cityscapes and vintage film stills. **Save your own custom styles, tweak the defaults, and use the app with _no login required_. Your images stay on your machine, always.** ![Application screenshot](screenshot.png) ## Major Features - **Advanced Frontend**: A sophisticated, single-page application with: - Dozens of built-in **Style Profiles** organized by category (e.g., Animation, Artistic, Vintage). - **Custom Profile Management**: Save, load, and delete your own favorite settings. - **Undo/Redo** history for iterative editing. - Advanced controls for prompts, inference steps, guidance scales, and seeds. - **Enhanced Model Pipeline**: Utilizes `black-forest-labs/FLUX.1-Kontext-dev` augmented with `DFloat11` for high-quality, efficient image generation. - **Efficient VRAM Usage**: Automatically enables model CPU offloading on NVIDIA GPUs to run on consumer cards with less VRAM. - **Environment-based Configuration**: Easily manage settings like queue size, file storage, and device selection using a `.env` file. - **Persistent Storage & Cleanup**: Generated images are saved to disk, with an automatic background worker to clean up old job data and files to save space. - **Intelligent Logging**: Uses `Loguru` for clean, readable logs and automatically filters out noisy status checks to keep the console tidy. - **Simplified Architecture**: No external dependencies like Redis or Celery. Just Python and the required ML libraries. - **Asynchronous Task Queue**: Uses a simple, thread-safe, in-memory queue to handle image generation jobs one by one, preventing server overload. - **GPU/CPU Agnostic**: Automatically uses an available NVIDIA GPU and gracefully falls back to the CPU (note: CPU is significantly slower). ## Quick Start ### Requirements - **Python 3.11+** - `pip` or `uv` (Python package installer; `uv` is recommended for speed) - **NVIDIA GPU** (recommended for speed; CPU fallback supported) - **~21GB VRAM** is preferred for the best performance. - Modern web browser (Chrome, Firefox, Edge, etc.) - Some images to Ghiblify! ## Setup & Installation ### 1. Clone the Project ```bash git clone https://github.com/TheAhmadOsman/4o-ghibli-at-home.git cd 4o-ghibli-at-home ``` ### 2. Create and Activate a Python Virtual Environment A virtual environment is crucial for isolating project dependencies. I recommend using `uv`. If you don't have `uv`, install it with `curl -LsSf https://astral.sh/uv/install.sh | sh` (macOS/Linux) or `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"` (Windows). You may need to restart your terminal. ```bash # Using uv (Recommended) uv venv # Or using Python's built-in venv python3.11 -m venv .venv ``` After creating the environment, activate it: ```bash # Activate (Windows) .venv\Scripts\activate # Activate (macOS/Linux) source .venv/bin/activate ``` ### 3. Install Dependencies Install the Python dependencies from `requirements.txt`. #### Option A: Using `uv` ```bash # Install dependencies into your activated environment uv pip install -r requirements.txt ``` #### Option B: Using `pip` ```bash pip install --upgrade pip pip install -r requirements.txt ``` ### 4. Configure Your Environment The application is now configured using an environment file. 1. Rename `.env_template` to `.env` in the project's root directory. 2. Edit the contents of the example below into your new `.env` file and adjust the values as needed. ```ini # .env.example - Copy this to a new file named .env # --- Server Configuration --- # Maximum number of jobs to hold in the queue. MAX_QUEUE_SIZE=10 # Maximum upload size in Megabytes (MB). MAX_UPLOAD_MB=25 # Folder to store generated images. Will be created automatically. RESULTS_FOLDER="generated_images" # --- Job & Resource Management --- # Device to run the model on ('cuda', 'cpu'). Defaults to 'cuda' if available. PYTORCH_DEVICE="cuda" # How long to keep job results in memory and on disk (in seconds). Default is 600 (10 minutes). JOB_RESULT_TTL=600 # How often the cleanup worker runs (in seconds). Default is 300 (5 minutes). CLEANUP_INTERVAL=300 ``` ## How to Run The application runs with a single command, which starts the web server and the background processing worker. **I usually run local sessions with the development command.** - **For Development (Recommended & Tested):** ```bash python3.11 app.py ``` - **For Production:** Use a production-grade WSGI server like Gunicorn. **It is critical to use only ONE worker** because the job queue is in-memory and cannot be shared across multiple processes. ```bash # The `--workers 1` flag is essential for this application's design. # Increase --threads for more concurrent I/O, and --timeout for long-running jobs. gunicorn --workers 1 --threads 4 --timeout 600 -b 0.0.0.0:5000 app:app ``` ## Open the App Once the server is running, open your web browser and navigate to: **** You can now upload an image and start stylizing! ## API Endpoints - `POST /process-image` — Submits an image processing job. Returns a `job_id`. - `GET /status/` — Checks the status of a job (`queued`, `processing`, `completed`, `failed`). Returns `queue_position` if queued. - `GET /result/` — If the job is `completed`, returns the generated PNG image from the disk. ## Project Structure - `app.py` — The all-in-one Flask server, API endpoints, and background image processing workers. - `static/*` — The complete, dynamic frontend application. - `requirements.txt` — All Python dependencies. - `generated_images/` — (Default directory) Where generated images are stored. - `.env` — (User-created from `.env_template`) File for all your local configuration. ## Deployment / Production Checklist - [ ] Create and configure your `.env` file on the production server. - [ ] Update `CORS(app)` in `app.py` to a specific origin for your frontend domain if it's hosted separately. - [ ] **Crucially, run with a single worker process (e.g., `gunicorn --workers 1`)** due to the in-memory queue design. - [ ] Use a reverse proxy like Nginx or Apache in front of the application for SSL/TLS, caching, and rate limiting. - [ ] Set up log rotation for the output from your WSGI server. - [ ] Set up monitoring to watch server health and resource usage (CPU, GPU, RAM). - [ ] (Optional) Add an authentication layer for private deployments. ## License This project is licensed under the **GNU Affero General Public License v3.0 (AGPLv3)**. - **Non-Commercial Use Only:** Commercial use of this software is **not permitted** without an explicit, written license from the author. You are free to use, modify, and distribute this software for personal, research, or non-commercial purposes under the terms of the AGPLv3. If you make changes and deploy the software for public use (including as a service), you must make the complete source code of your modified version available under the same license. For more details, see the [LICENSE](./LICENSE) file or visit: [https://www.gnu.org/licenses/agpl-3.0.html](https://www.gnu.org/licenses/agpl-3.0.html) ## Support Open issues on GitHub for bugs, help, or feature requests. **Enjoy creating stunning images with your private AI!**