Skip to content

About

Native, local-first Ideogram 4 image generation studio for Apple Silicon, built with Swift and MLX.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Cyclonminigen app icon

Cyclonminigen

A native, local-first Ideogram 4 image studio for Apple Silicon, built with Swift and MLX.

CI passing Build passing Version 1.1 Build 19 MIT License macOS 14 or later Apple Silicon Built with MLX and Swift Swift 6.0 or later Pull requests welcome

Cyclonminigen main workspace with the navigation hidden

Cyclonminigen is a full native macOS workspace for generating, organizing, and iterating on Ideogram 4 images without sending prompts or source images to an application server. It combines a faithful MLX-Swift inference pipeline with a persistent Gallery and Library, a session render queue, image-to-image workflows, optional LoRA adapters, structured layout controls, and selectable local assistants for Magic Prompt and image description.

Version 1.1 (build 19) is a maintenance source release with corrected Region composition, direct Photo-to-image handling, local-assistant model integrity checks, and generation-safety regressions. The GitHub release contains source archives only: model weights and a prebuilt .app are deliberately excluded. A locally built app is ad-hoc signed for development and must not be redistributed as a notarized release.

Cyclonminigen is an independent project and is not affiliated with or endorsed by Ideogram.

Product tour

1. Main workspace

Main generation workspace

Compose a prompt, choose an aspect ratio and 1 MP, 2 MP, or 4 MP canvas tier, select Turbo, Default, or Quality, and queue one or more deterministic renders. The workspace keeps generation, the current result, live status, seed controls, and common creative actions together.

2. More settings

More generation settings

The fine-tuning panel exposes manual guidance and step controls, deterministic seed handling, negative prompts, image-to-image strength, batch options, dual-CFG behavior, and experiment controls that remain off unless explicitly selected.

3. Queue

Render queue

Every queued task receives an immutable snapshot of its prompt, model settings, image input, LoRA selection, and seed. Tasks can be reordered or cancelled, while the active render owns MLX resources until it finishes or reaches a bounded cancellation point. Queue data is session-only.

4. Gallery

Gallery browser

This historical documentation screenshot shows the project owner's populated Gallery only to demonstrate the grid. It is not seed content: the app bundle contains no saved Gallery images or generation index, and every new user starts with an empty Gallery. Only the 176 curated Library previews are bundled. Saved generations appear in a searchable grid with multi-selection, favorites, compare and detail views, recipe-aware iteration, export, and repair tools. Gallery files are persistent user documents; clearing Gallery does not touch linked model directories.

5. Library

Built-in prompt Library

The Library contains 176 built-in Library cards across architecture, characters, design, illustration, interiors, photography, products, typography, and other categories. Cards can seed a new render, and user-saved Library entries remain separate from the bundled collection.

6. Models

Model management

Models handles the gated Ideogram components and optional local assistant models. It can download into Cyclonminigen-managed storage or link an existing compatible directory read-only. Downloads are resumable and integrity-checked; external linked folders are never deleted by the app.

7. LoRA adapters

LoRA adapter management

Import local .safetensors LoRA adapters into app-managed storage, enable several adapters, and set their strengths per render. Imports are size-bounded and transactional, and removal is limited to files proven to be inside the managed LoRA directory.

8. Gallery details

Completed image in Gallery details

The detail view keeps the generated image beside its prompt, seed, preset, dimensions, timestamps, favorite state, technical recipe, and iteration actions. Default export and drag-out sanitize embedded recipe text; exporting the original metadata is an explicit opt-in action.

Additional screenshots
Help — Creative tools Expanded generation panel
Help reference — Creative tools Expanded generation panel
Interior Library Typography preview
Interior Library Typography preview
Character sheet control Direct Photo → image Structured caption
Character sheet control Direct Photo to image with a loaded reference Structured caption editor
Normal render speed Fast render speed Faster render speed
Normal render speed Fast render speed Faster render speed
Quality Default Turbo
Quality portrait Default portrait Turbo portrait
Architecture Interior Manufacturing
Architecture example Interior example Manufacturing example
Samurai character sheet Cyberpunk character sheet
Samurai character sheet Cyberpunk character sheet
Assistant model selector
Local assistant model selector
Regions: continuous result
Continuous living-room result produced with Regions

What is included

Native Ideogram 4 generation

  • MLX-Swift execution on Apple Silicon with no Python runtime in the application.
  • Ideogram presets V4_TURBO_12, V4_DEFAULT_20, and V4_QUALITY_48.
  • Native canvas tiers up to 4 MP, with dimensions constrained to multiples of 16 and a 2048-pixel maximum on each side.
  • Deterministic seeds, batch generation, custom steps and guidance, negative prompts, live preview, dual-CFG execution, cancellation, and memory-pressure safeguards.
  • Image-to-image input with adjustable strength and lifecycle-safe temporary storage.

Creative controls

  • Magic Prompt enrichment through a selectable local text or vision-language assistant.
  • Describe and photo-to-prompt workflows for local images.
  • Structured character-sheet and region/bounding-box composition controls.
  • Typography-oriented prompting with on-device OCR feedback for saved results.
  • Aspect-ratio, style, batch, remix, and seed-iteration workflows.
  • Multiple LoRA adapters with per-adapter strength and immutable queue snapshots.

Workflow and storage

  • Sequential render queue with reorder, cancel, retry, and quit protection.
  • Persistent Gallery with search, selection, favorites, collections, comparison, detail, remix, sanitized export, and recovery tooling.
  • 176 built-in first-party Library cards plus separately stored user entries.
  • Managed or read-only linked model storage, resumable downloads, integrity validation, recovery of interrupted mutations, and strict ownership boundaries for destructive operations.
  • System view for local memory, process state, storage use, and maintenance actions.

Local assistants

Magic Prompt and Describe share a selectable assistant profile. Supported choices include Qwen3-VL 4B, Gemma 3 4B/12B, and Qwen3.6 27B variants in reviewed MLX quantizations. Assistant downloads are pinned to immutable revisions. Text-only Magic Prompt runs in a separate bounded helper process; photo understanding uses the vision-language path in the app.

Requirements

  • Apple Silicon Mac (arm64).
  • macOS 14 or later.
  • Xcode with a Swift 6 toolchain for source builds.
  • 32 GB unified memory is the current tested baseline for Ideogram rendering. Lower-memory Macs are not a qualified configuration for the renderer.
  • Approximately 25.8 GB for the complete dual-CFG Ideogram checkpoint; keep at least 40 GB free before the first download for staging and safety headroom.
  • Additional disk and memory for optional assistant models. Their enforced inference thresholds range from 16 GB to 48 GB for Magic Prompt. Photo understanding with Qwen3.6 27B requires 48 GB for the 4-bit variant or 64 GB for the 8-bit variant.

A model-backed visual gate has been verified locally on a 32 GB Apple Silicon Mac. It is not part of public GitHub Actions because the separately licensed model weights are not included. Hardware support is not implied beyond configurations that have completed the release test matrix.

Code license and model license

The Cyclonminigen source code and first-party project assets are available under the MIT License.

The Ideogram 4 model weights are not included in this repository, are not covered by the MIT License, and are never bundled by Cyclonminigen. They are gated by the publisher and subject to a separate Non-Commercial license. To download them, use your own Hugging Face account, accept the model terms, and provide a Hugging Face Read token. Your use of the weights and generated outputs must follow those separate terms.

See NOTICE, THIRD_PARTY_NOTICES.md, and THIRD_PARTY_LICENSES.md for upstream attributions and dependency terms.

Build from source

Clone the public repository and run the reviewed fast gates before packaging:

git clone https://github.com/abgitdev/Cyclonminigen.git
cd Cyclonminigen
swift package --package-path app resolve
tools/verify-golden-fixtures.sh
tools/check_licenses.sh
tools/gate.sh --fast
tools/package-desktop-app.sh /private/tmp/Cyclonminigen.app 19 1.1
open /private/tmp/Cyclonminigen.app

Xcode is required because the app and command-line targets need MLX Metal resources that a plain SwiftPM application build does not assemble correctly. Without SIGN_IDENTITY, the packager creates an ad-hoc signed application for local use only.

First run and model setup

  1. Open Models in Cyclonminigen.
  2. Sign in to Hugging Face, accept the license on the Ideogram 4 FP8 model page, and create a Read token.
  3. Paste the token and download the required components, or link an existing compatible weights directory. A linked directory is treated as read-only.
  4. Return to Generate, enter a prompt, choose a preset, and add the render to Queue.

Privacy and network behavior

  • Prompts, source images, and generated images are processed locally and are not uploaded by Cyclonminigen.
  • The Hugging Face token is stored in macOS Keychain and is sent only to huggingface.co to authenticate model downloads.
  • Network access is used for explicitly requested model downloads and Swift package resolution. Once required models are present, image generation and Magic Prompt run locally.
  • Queue contents, refusal diagnostics, and application logs remain in current-session memory.
  • Gallery images and explicitly saved Library entries are persistent user documents.
  • Default PNG export and drag-out remove embedded recipe text. Original metadata export requires an explicit user choice.
  • Project source builds contain no telemetry SDK and collect no analytics.

The System screen reports local process, memory, and storage information only.

Build and test

The canonical CI and release verification lane is:

tools/ci.sh

It verifies exact Package.resolved graphs, public-source privacy policy, asset hashes and rights, licenses and notices, golden fixtures, the app test suite, UI automation harness, and every engine package through Xcode. The Xcode lane assembles MLX default.metallib; a missing Metal resource is a failure, not a passing skip.

The full visual gate requires separately licensed local weights and more time. It creates an isolated environment from the exact pins in tools/requirements-gate.txt:

GATE_PYTHON=/absolute/path/to/python3 \
IDEOGRAM_WEIGHTS_ROOT=/absolute/path/to/ideogram-weights \
tools/gate.sh

For a focused Metal-capable package run:

tools/test-with-metal.sh app Cyclonminigen-Package
tools/test-with-metal.sh engine/IdeogramVAE IdeogramVAE-Package

Plain swift test remains useful for focused CPU-only development, but it is not an acceptance lane because SwiftPM does not assemble every MLX Metal test resource.

Repository layout

Path Purpose
app/ Native SwiftUI application, helper process, resources, unit tests, and UI automation
engine/IdeogramScheduler/ Ideogram schedule and preset implementation
engine/IdeogramDiT/ Transformer, attention, quantized layers, and weight loading
engine/IdeogramTextEncoder/ Qwen3-VL text-conditioning stack and validation
engine/IdeogramVAE/ VAE encode/decode, tiling, and preview components
engine/IdeogramPipeline/ Public generation pipeline, CLI tools, and integration tests
tools/ Hermetic gates, packaging, license collection, privacy checks, and golden verification
docs/screenshots/ Sanitized first-party application screenshots used by this README

Troubleshooting

Model download reports access denied. Confirm that the token belongs to the same Hugging Face account that accepted the Ideogram model license and that it has Read access.

Weights are missing or damaged. Reopen Models and resume the affected component. Cyclonminigen checks required files and safetensors structure before rendering.

A render stops because of memory pressure. Quit other memory-intensive applications, select a smaller canvas, and retry. Do not raise watchdog limits outside a controlled development run.

A source build reports a missing Metal library. Build through tools/package-desktop-app.sh or run the canonical Xcode-backed gate. Plain SwiftPM does not assemble every MLX Metal resource for the app bundle.

Gallery needs repair. Use System → Repair Gallery. Back up persistent user documents before manual filesystem intervention.

Contributing and project policy

Focused pull requests are welcome. Please read CONTRIBUTING.md, run the smallest relevant tests followed by tools/ci.sh, and never commit model weights, credentials, personal paths, logs, build products, or user documents. Report vulnerabilities privately according to SECURITY.md.

Copyright © 2026 abgitdev. Released under the MIT License.

About

Native, local-first Ideogram 4 image generation studio for Apple Silicon, built with Swift and MLX.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages