saggamer/horizon-1

Horizon 1 — MLX

Horizon 1 is an experimental image generator and instruction-grounded editor for Apple Silicon. Version 0.2 adds the existing trained creativity expert for source-free text-to-image generation, alongside the editing adapter, semantic bridge, instruction grounder, and spatial controls. It runs with a separately downloaded 4-bit FLUX.2 Klein base 4B checkpoint through MFLUX.

This repository is a roughly 84 MB adapter and runtime bundle, not a standalone 4B foundation checkpoint. The first run downloads approximately 4.6 GB of base weights. Do not load this repository with mlx_lm.load, Transformers AutoModel, or a standard Diffusers pipeline. Use the runtime below.

Real-photo instruction adherence remains limited. This is a research release, not a production-ready editor or a claim of state-of-the-art performance. It does not include a text chat model or PPT/PDF generation.

Generate a new image

After installing the bundle below, omit --source to generate directly from text:

horizon-image --bundle ./horizon-1 --mode generate \
  --prompt "A blue ceramic whale teapot with one orange cup to its right, on a stone table." \
  --output generated.png --steps 20 --guidance 4 --seed 42

This loads Horizon’s trained creativity LoRA and creativity-mode semantic bridge. It starts from random noise and text only: no blank source image, reference-image tokens, instruction-grounding head, or edit mask is used. The editing expert is kept separate. This is a port of an existing checkpoint, not additional training. The original creativity run completed 1,024 optimizer updates on 2026-10-20. Its 1,024 training rows (1,023 groups) combine COCO image captions and DiffusionDB image/prompt pairs. COCO examples were restricted to license IDs 4, 7, and 8 (CC BY 2.0, Flickr no known copyright restrictions, and US government work); DiffusionDB is distributed under CC0 1.0. Five positive supervised replay examples replaced five synthetic rows without increasing the total. Those coached examples were excluded from novel tests. This is supervised flow-matching replay, not autonomous online learning or a human creativity-preference benchmark.

Sources: COCO-Caption2017, revision 3bdd5827e243cc3084ac69a1111e69c3ab9193ff, and DiffusionDB, revision fb620fbe49fa4420e0734bd9c0df11f51176b61f.

Default generation is 512 × 512. --width and --height accept multiples of 16 from 256 to 1024; full image tests in this release use 512 × 512 only. Large sizes need more memory. The complete native prompt budget remains 256 tokens, with explicit overflow rejection. horizon-edit remains a compatible command name; horizon-image is the general generation/editing entry point.

Generation writes a PNG and JSON provenance. Edit-only region flags are rejected in generation mode. Output files are never overwritten. Counts, spatial placement, and functional object design remain experimental; two examples are not a broad benchmark.

Actual source-free generation tests

Two new prompts completed on an Apple M4 using the trained creativity adapter and bridge, 20 steps, guidance 4, and a 512 × 512 canvas. Both used text and random noise only. Runtime validation is in evaluation/generation_test.json; conversion parity and exact trained-value preservation are in evaluation/creativity_conversion.json. The edit components also retain their prior numerical parity.

Whale teapot and orange cup	Paper boats and lemon

The whale/cup composition is recognizable, but the specified functional handle and spout are not clearly established. The boats/bowl/lemon composition is present, but exactly three distinct boats is not unambiguous because a red form may be a reflection. Neither complete instruction is marked as a verified semantic success. See evaluation/generation_review.json. These are generation capability tests, not evidence of production readiness or superior creativity.

Run locally

Requirements: an Apple Silicon Mac with Metal access, Python 3.12 or later, and enough disk space for the base checkpoint and dependencies. A 24 GB M4 Mac is the local test machine. Smaller-memory Macs have not been validated.

python3.12 -m venv .venv-horizon
source .venv-horizon/bin/activate
python -m pip install 'huggingface_hub>=1,<2'
hf download saggamer/horizon-1 --local-dir horizon-1
python -m pip install ./horizon-1

horizon-edit --bundle ./horizon-1 \
  --source source.png \
  --prompt "Put a butterfly on the dog." \
  --output edited.png \
  --steps 20 --guidance 4 --seed 42 \
  --constrain-predicted-region

The output files are:

• edited.png: model-rendered output, optionally with the latent region constraint.
• edited.predicted-mask.png: the region predicted from the source and instruction.
• edited.probability.png: grounding probabilities, enlarged from the 32 × 32 grid.
• edited.json: prompt, seed, weight provenance, hashes, and runtime settings.

--protect-predicted-region additionally saves edited.protected.png, a pixel-copy composite that copies source pixels outside the predicted mask. This composite is separate from the model's raw output. It cannot repair an incorrect predicted region and is not evidence that the requested edit succeeded.

The source is converted to RGB and resized to 512 × 512. Only the source and original instruction are inference inputs; no reference target or human mask is provided. Instructions exceeding the complete 256-token native template budget are rejected instead of silently truncated. Outputs are never overwritten.

The default base is pinned to AITRADER/FLUX2-klein-base-4B-mlx-4bit, revision e04a5bc9307320a601ebb0047e3f47ec7dc4d432. This community conversion declares the correct BFL base model; its conversion has not been independently reproduced here. --base-path accepts a compatible local 4-bit MFLUX saved checkpoint; the runtime records an override but does not independently establish that checkpoint's identity. Do not substitute the distilled Klein 4B model for the base model.

What was ported

1. Native FLUX.2 joint text/image diffusion transformer with all 120 trained rank-16 LoRA tensors, loaded without baking into the quantized base.
2. Mode-gated semantic bridge: full 7,680-dimensional native Qwen context, rank-32 attention, trained editing-mode residual.
3. Instruction grounder: source-only 3,072-dimensional transformer features and RGB patches, cross-attention to the complete separately encoded instruction, spatial transformer, and a 32 × 32 edit-probability grid.
4. Learned region embedding applied to aligned source/target image tokens.
5. Optional denoising constraint preserving the source/noise trajectory outside the predicted edit region.

The full native Qwen encoder and hidden layers 9/18/27 are retained. Grounding source features use the fixed generic prompt Describe the visible scene.; the original instruction enters the separate cross-attention head. The inference context is 256 tokens, empty negative conditioning is encoded natively, and the flow schedule uses the native empirical shift. Reference-image position time is 10; source-only features use 0. The validation-selected mask threshold is 0.4.

The backbone and text encoder use the community MLX 4-bit checkpoint. LoRA remains an unbaked residual; the custom grounding head and semantic bridge remain FP32. Attention/feed-forward compute uses MFLUX's float16 mode; residual streams and other sensitive operations retain the backend's native precision.

This is a bridge into an existing joint diffusion transformer. It is not a reimplementation of BAGEL's full mixture-of-transformers architecture, nor a new unified language model pretrained from scratch.

Validation and limits

The MLX auxiliary networks passed comparisons against the original trained PyTorch weights on an Apple M4. FP32 tests used 1,024 source tokens, batches of one and two, and 29/64 text tokens with padding masks. Maximum absolute errors:

Component	Maximum error
Instruction-grounder logits	0.00003911
Semantic bridge	0.000000238

The region-constraint arithmetic also passed. See evaluation/component_parity.json. All 120 LoRA tensors mapped to the expected 60 native transformer layers. Instruction-template IDs and padding masks matched exactly, including native empty negative conditioning, and oversized instructions were rejected before encoding. These checks are recorded in evaluation/lora_mapping.json and evaluation/instruction_handling.json. The real native 4-bit Qwen encoder also ran on the M4 GPU for two nonempty instructions and empty negative conditioning, producing finite [1, 256, 7680] embeddings. See evaluation/native_encoder_test.json. The community tokenizer differs from the training file in offset-trimming and decoder metadata. Its encoding vocabulary, merges, regex, normalization, added tokens, and native chat template match. Token IDs matched on 518 test strings; see evaluation/tokenizer_provenance.json. These are component conversion checks, not proof of full-model parity or image-editing accuracy after base quantization. Random seeds are not pixel-equivalent between PyTorch/CUDA and MLX. The 84-row CUDA evaluation has not been rerun in MLX.

Two complete 512 × 512 MLX edits were also executed with 20 steps, guidance 4, and seed 42. Both produced nonblank images and finite intermediate tensors, but both failed single-object count adherence: the dog edit produced several butterflies and the spatial example produced two black dots instead of one. These were reused evaluation examples, not a fresh benchmark. Passing runtime checks does not mean the instructions were satisfied. See evaluation/mlx_smoke_test.json and the separate visual review.

The final runtime uses MFLUX's native predictor (compiled on the tested M4). A third full 20-step execution validated this path; it also produced two dots. See evaluation/mlx_compiled_test.json and evaluation/visual_review.json. These local runs took approximately 6–7.5 minutes per image. Peak MLX allocation was approximately 6.8 GB; this excludes other process/system memory and is not a minimum-memory guarantee. No final pixel-copy compositing was used in these tests.

Actual native-predictor output for the instruction “Add a small black dot directly above the right orange square. Keep everything else unchanged.”:

Owned procedural source	Actual MLX output — count/placement failure

The eager output and learned mask are also provided in examples/. This simple case exposes a remaining failure; it must not be presented as a successful edit.

Prior CUDA grounding evaluation, before this port:

Evaluation	Previous head IoU	Repaired head IoU	Repaired peak inside annotation
48 unique real-photo groups	0.1144	0.1609	14/48
32 controlled rows from 8 scenes	0.2262	0.8074	32/32
4 no-edit examples	—	—	4/4 empty masks

Controlled rows reuse eight scenes and instruction templates; they are not 32 independent natural-image groups. The 0.4 threshold was selected on separate validation groups. Real-photo localization is only modestly above a center prior (IoU 0.1425), and peak localization succeeds on fewer than one-third of examples. Detailed CUDA results are in evaluation/cuda_quality_decision.json.

Prior CUDA visual review found successful butterfly placement on a dog and improved scene preservation in one catcher-to-bucket edit. It also found failures: blanket extension can redraw the bed or do nothing, frisbee replacement can occur at the wrong person, a flag edit can paint the car instead, and a requested lobster can be absent. Controlled dot placement already worked in the base editor. Mask accuracy and pixel preservation do not establish semantic edit success.

Training lineage and data

This MLX release is a port; it does not claim additional training or experience. The latest instruction grounder received 2,048 optimizer updates on 640 examples: 448 real MagicBrush source/instruction/human edit-area rows, 128 procedural rows (four instructions per 32 scenes), and 64 no-edit examples. Its backbone features were frozen. The earlier editing LoRA, bridge, and region embedding received 1,024 joint grounding/rendering updates.

Public source: MagicBrush, revision 6c254560879df7851233ea0fd2ae2a62764d0ef2, distributed under CC BY 4.0. Credit the MagicBrush authors and original dataset/image contributors. Human freeform edit-area annotations are coarse edit regions, not precise object segmentations. Underlying image rights still apply. Training images and human targets are not included in this release.

Credits and license

Horizon components and this runtime are released under Apache 2.0; see LICENSE. The base model is Black Forest Labs FLUX.2 Klein base 4B, Apache 2.0. Original training base revision: a3b4f4849157f664bdbc776fd7453c2783562f4d. Apple's MLX and MFLUX supply the native Apple Silicon backend. The community 4-bit conversion is credited to AITRADER. Dependencies retain their own licenses. No upstream endorsement is implied.

Use manifest.json to check release file hashes. Weight files are safe tensor containers; loading this runtime does not require trust_remote_code=True.