blokjutsu 1.0.0rc1__tar.gz

blokjutsu-1.0.0rc1/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

blokjutsu-1.0.0rc1/NOTICE

@@ -0,0 +1,27 @@
+Blokjutsu
+Copyright 2026 Bob Carpenter
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+
+This product is a desktop front end for MOSS-Image, developed by the OpenMOSS Team / MOSI.AI:
+  https://github.com/OpenMOSS/MOSS-Image
+  MOSS-Image Technical Report, https://arxiv.org/abs/2610.23374
+MOSS-Image's pipeline code and model weights are licensed under the Apache License, Version 2.0.
+
+blokjutsu/moss_image.py is MOSS-Image's pipeline code (pipeline_moss_image.py from OpenMOSS-Team/MOSS-Image-SFT),
+copied unchanged; Copyright the OpenMOSS Team / MOSI.AI. The model weights are not included; the app downloads
+them from Hugging Face when the user asks it to.
+
+The captioning instructions in blokjutsu/describe.py are adapted from MOSS-Image's USERGUIDE.md (Apache License,
+Version 2.0); the changes are described in that file.
+
+blokjutsu/moss_forward.py is adapted from the MOSS-Image transformer's forward pass (Apache License, Version
+2.0); the changes are described at the top of that file.
+
+Models used at run time (downloaded on request, not included):
+  MOSS-Image-SFT and MOSS-Image-Base, OpenMOSS Team (Apache-2.0)
+  Qwen3.5-9B, Qwen Team, Alibaba Cloud (Apache-2.0): MOSS-Image's text encoder; Blokjutsu also downloads its
+    output layer (lm_head) from Qwen/Qwen3.5-9B for Describe image and Enhance prompt
+  FLUX.2 VAE, Black Forest Labs (Apache-2.0)
+
+Third-party Python libraries are installed separately and keep their own licenses; see README.md.

blokjutsu-1.0.0rc1/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: blokjutsu
+Version: 1.0.0rc1
+Summary: A local, permissively licensed, open-source Mac app for generating and editing images from text prompts with the open-weight MOSS-Image model
+Author: Bob Carpenter
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://formdo.github.io/blokjutsu/
+Project-URL: Source, https://github.com/formdo/blokjutsu
+Project-URL: Issues, https://github.com/formdo/blokjutsu/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: MacOS X
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: PySide6-Essentials>=6.6
+Requires-Dist: torch>=2.9
+Requires-Dist: torchvision
+Requires-Dist: diffusers>=0.38
+Requires-Dist: transformers>=5.3
+Requires-Dist: accelerate>=1.10
+Requires-Dist: huggingface_hub>=1.0
+Requires-Dist: httpx
+Requires-Dist: safetensors>=0.6
+Requires-Dist: Pillow>=10
+Requires-Dist: numpy
+Requires-Dist: pyobjc-framework-Cocoa; sys_platform == "darwin"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+<p align="center"><img src="blokjutsu/resources/icon.png" width="128" alt="Blokjutsu icon"></p>
+
+# Blokjutsu
+
+**A local, permissively licensed, open-source Mac app for generating and editing images from text prompts with
+the open-weight [MOSS-Image](https://github.com/OpenMOSS/MOSS-Image) model.**
+
+- **Local.** The model runs locally on your Mac. Prompts and images never leave your machine.
+- **Permissive open source ([Apache 2.0](https://en.wikipedia.org/wiki/Apache_License)).** The app, MOSS-Image's
+  code, and MOSS-Image's model weights are all under the Apache License 2.0. Use them for anything, commercial or
+  not, and change and share them, with no restrictions on what you make.
+- **Download once.** The image model (about 30 GB) and the optional captioning model (2 GB) are downloaded once,
+  when you ask. After that, everyday use doesn't go online at all.
+
+**Simple on purpose:** a small set of controls designed to work together and to be quick to learn.
+
+**Using Blokjutsu?** Start with the [User's Guide](https://formdo.github.io/blokjutsu/): installing, a tour of the
+window, writing prompts, and every control explained.
+
+![The Blokjutsu window: controls on the left; on the right, an image of three bowls of ice cream on a diner counter with handwritten cards reading CHOCOLATE, CHERRY, and PLAIN](docs/assets/screenshots/main-window.webp)
+
+## What Blokjutsu does
+
+- Text to image, image to image, variations, inpainting, outpainting, cropping, and upscaling
+- Describe image and Enhance prompt, written by MOSS-Image's own text encoder
+- Live previews, a scrolling history, and each image's settings saved beside it
+
+## Open source all the way down
+
+With Blokjutsu, the model, the code that runs it, and the app around it are all yours to run, keep, and adapt.
+
+Every part of Blokjutsu is released under the [Apache License 2.0](LICENSE), a
+[permissive](https://en.wikipedia.org/wiki/Comparison_of_free_and_open-source_software_licenses) open-source
+license:
+
+- **Blokjutsu's source code**, in this repository
+- **MOSS-Image's code**, the pipeline that turns a prompt into an image
+- **MOSS-Image's model weights**, including the Qwen3.5-9B text encoder and FLUX.2 image decoder they contain
+
+Apache 2.0 lets anyone use, study, change, and share all of it, for any purpose, commercial or not, at no cost,
+and with no sign-up. The conditions are light: keep the license and copyright notices, and say what you changed.
+It also grants the patent rights needed to use the code. The libraries Blokjutsu builds on are open source too
+(see [What it uses](#what-it-uses)).
+
+## Requirements
+
+- A Mac with Apple silicon (M1 or later) and macOS 12.3 or later
+- 32 GB of memory or more; 48 GB or more is comfortable, and smaller Macs work slowly, if at all
+- About 40 GB of free disk space, mostly for the model
+
+## Install
+
+**Mac users:** open Terminal and paste
+
+```sh
+curl -LsSf https://formdo.github.io/blokjutsu/install.sh | sh
+```
+
+This installs Python and Blokjutsu into `~/Library/Application Support/Blokjutsu.noindex/` and puts
+**Blokjutsu** in your Applications folder. Nothing else on your Mac is changed. See the
+[User's Guide](https://formdo.github.io/blokjutsu/install.html) for details and uninstalling.
+
+**Python developers:** Blokjutsu needs Python 3.10 or later. We strongly suggest installing it in its own virtual
+environment. The exact library versions it was tested with are in [constraints.txt](constraints.txt), which pip
+can use with `-c constraints.txt`.
+
+```sh
+python3 -m venv .venv
+source .venv/bin/activate
+pip install blokjutsu
+blokjutsu
+```
+
+## Built on MOSS-Image
+
+Blokjutsu is an independent desktop front end for **MOSS-Image**, the text-to-image model and pipeline by the
+[OpenMOSS Team](https://github.com/OpenMOSS) and [MOSI.AI](https://mosi.cn/). Blokjutsu is not affiliated with or
+endorsed by them. All of the image-making is theirs.
+
+- Repository: https://github.com/OpenMOSS/MOSS-Image
+- Technical report: https://arxiv.org/abs/2610.23374
+- User guide: https://github.com/OpenMOSS/MOSS-Image/blob/main/USERGUIDE.md
+
+If you use images or results from Blokjutsu in research, please cite MOSS-Image:
+
+```bibtex
+@misc{mossimage2026,
+  title        = {MOSS-Image},
+  author       = {{OpenMOSS Team}},
+  year         = {2026},
+  howpublished = {\url{https://github.com/OpenMOSS/MOSS-Image}}
+}
+@misc{mossimage2026report,
+  title         = {MOSS-Image Technical Report},
+  author        = {{MOSI.AI}},
+  year          = {2026},
+  eprint        = {2610.23374},
+  archivePrefix = {arXiv},
+  url           = {https://arxiv.org/abs/2610.23374}
+}
+```
+
+## What it uses
+
+The models are downloaded from [Hugging Face](https://huggingface.co), a site that hosts open AI models, and
+only when you ask. MOSS-Image's model is published there as MOSS-Image-SFT; its text encoder and image decoder
+come from Qwen and FLUX.2 and are included in that download.
+
+| model | by | license | role |
+|---|---|---|---|
+| [MOSS-Image-SFT](https://huggingface.co/OpenMOSS-Team/MOSS-Image-SFT) | OpenMOSS Team | Apache-2.0 | MOSS-Image's model, used by default |
+| [MOSS-Image-Base](https://huggingface.co/OpenMOSS-Team/MOSS-Image-Base) | OpenMOSS Team | Apache-2.0 | the untuned model, for people training their own versions (optional) |
+| [Qwen3.5-9B](https://huggingface.co/Qwen/Qwen3.5-9B) | Qwen Team, Alibaba Cloud | Apache-2.0 | reads prompts (part of MOSS-Image); with its output layer, downloaded separately, writes descriptions |
+| [FLUX.2 VAE](https://github.com/black-forest-labs/flux2) | Black Forest Labs | Apache-2.0 | turns the model's output into pixels (part of MOSS-Image) |
+
+Python libraries, installed alongside:
+
+| library | license | role |
+|---|---|---|
+| [PyTorch](https://pytorch.org), torchvision | BSD-3-Clause | numerical engine on the Apple GPU |
+| [Diffusers](https://github.com/huggingface/diffusers) | Apache-2.0 | runs the MOSS-Image pipeline |
+| [Transformers](https://github.com/huggingface/transformers), Accelerate | Apache-2.0 | text encoder, describing |
+| [huggingface_hub](https://github.com/huggingface/huggingface_hub), safetensors | Apache-2.0 | model files and downloads |
+| [httpx](https://www.python-httpx.org) | BSD-3-Clause | the confirmed downloads |
+| [PySide6 / Qt](https://www.qt.io/qt-for-python) | LGPL-3.0 | the window and controls |
+| [Pillow](https://python-pillow.org) | MIT-CMU | image files |
+| [NumPy](https://numpy.org) | BSD-3-Clause | arrays |
+| [PyObjC](https://github.com/ronaldoussoren/pyobjc) | MIT | macOS system icons and app name |
+
+## Local by design
+
+Blokjutsu runs the model on your Mac's own processor and memory. It uses the internet only once to initially
+download the models, and then, only after a confirmation dialog. After the models are downloaded once, Blokjutsu
+works completely offline. It does not go online to generate, edit, or store images. It does not go online to
+check for updates to itself.
+
+Images are saved as plain PNG files that hold only the image. If you want, a setting in Advanced options also
+writes each image's prompt and settings into the PNG.
+
+### What Blokjutsu keeps on your Mac
+
+| what | where | Delete all history |
+|---|---|---|
+| your images, each with its settings and any image you started from | the Output folder you choose (by default `~/Library/Application Support/Blokjutsu.noindex/images/`) | deleted, in every Output folder used |
+| the log, for troubleshooting | `~/Library/Application Support/Blokjutsu.noindex/logs/` | emptied |
+| working copies from Select area to change | `…/Blokjutsu.noindex/work/` | deleted |
+| a small file the live preview needs, built from your images | `…/Blokjutsu.noindex/preview/` | deleted |
+| your settings, including the last prompt | `…/Blokjutsu.noindex/settings.json` | prompt reset, preferences kept |
+| the captioning model | `…/Blokjutsu.noindex/caption/` | kept |
+| the image model | `…/Blokjutsu.noindex/models/` | kept |
+| the app and the Python it runs on | `~/Applications/Blokjutsu.app`, `…/Blokjutsu.noindex/tools/`, and `…/Blokjutsu.noindex/runtime/` | kept |
+
+The whole `…/Blokjutsu.noindex` folder is kept out of Time Machine backups and Spotlight. To back up your images,
+choose an Output folder elsewhere, such as `~/Pictures/Blokjutsu`.
+
+**Delete all history** (in the File menu) removes everything made from your prompts and images and keeps your
+preferences and the models. The [User's Guide](https://formdo.github.io/blokjutsu/local.html) has the details, including what macOS itself
+remembers.
+
+## Contributing
+
+[CONTRIBUTING.md](CONTRIBUTING.md) explains how to set up a development environment, run the tests, and build the
+Mac app. Architecture and technical notes are in the [developer pages](https://formdo.github.io/blokjutsu/developers.html).
+
+## Roadmap
+
+What comes next is in [ROADMAP.md](ROADMAP.md).
+
+## Bug reports and feature requests
+
+Please report bugs and request features as [GitHub issues](https://github.com/formdo/blokjutsu/issues). For help
+using Blokjutsu, see the [User's Guide](https://formdo.github.io/blokjutsu/) and its
+[Troubleshooting](https://formdo.github.io/blokjutsu/troubleshooting.html) page.
+
+## Etymology
+
+**Blokjutsu** (BLOK-joot-soo, /ˈblɒk.dʒuː.tsuː/), *noun*. The art of the block.
+
+From Danish *blok*, "block," and Japanese *jutsu* (術, じゅつ), "art" or "technique." The name comes from how
+MOSS-Image works: it treats an image as blocks of pixels, each 16 × 16 square one unit for the model, and
+transforms them step by step from noise into the finished image.
+
+## Design inspiration
+
+The block designs in the icon and the app draw on
+
+- the [Kohs block design test](https://en.wikipedia.org/wiki/Kohs_block_design_test), introduced by Samuel C.
+  Kohs in 1920: colored cubes, some faces split diagonally, arranged to match a pattern
+- [Froebel's gifts](https://en.wikipedia.org/wiki/Froebel_gifts), the wooden building blocks of Friedrich
+  Fröbel's first kindergartens
+- the primary colors and simple geometry of the [Bauhaus](https://en.wikipedia.org/wiki/Bauhaus)
+
+## Authors
+
+Blokjutsu was written by Bob Carpenter together with Claude, Anthropic's AI model.
+
+## License
+
+Copyright 2026 Bob Carpenter. Apache License 2.0; see [LICENSE](LICENSE) and [NOTICE](NOTICE).
+`blokjutsu/moss_image.py` is MOSS-Image's pipeline code, copied unchanged, and `blokjutsu/moss_forward.py` is
+adapted from it (both Apache-2.0). "MOSS-Image" is the OpenMOSS Team's name and is used here only to say what
+this app runs.

blokjutsu-1.0.0rc1/README.md

@@ -0,0 +1,202 @@
+<p align="center"><img src="blokjutsu/resources/icon.png" width="128" alt="Blokjutsu icon"></p>
+
+# Blokjutsu
+
+**A local, permissively licensed, open-source Mac app for generating and editing images from text prompts with
+the open-weight [MOSS-Image](https://github.com/OpenMOSS/MOSS-Image) model.**
+
+- **Local.** The model runs locally on your Mac. Prompts and images never leave your machine.
+- **Permissive open source ([Apache 2.0](https://en.wikipedia.org/wiki/Apache_License)).** The app, MOSS-Image's
+  code, and MOSS-Image's model weights are all under the Apache License 2.0. Use them for anything, commercial or
+  not, and change and share them, with no restrictions on what you make.
+- **Download once.** The image model (about 30 GB) and the optional captioning model (2 GB) are downloaded once,
+  when you ask. After that, everyday use doesn't go online at all.
+
+**Simple on purpose:** a small set of controls designed to work together and to be quick to learn.
+
+**Using Blokjutsu?** Start with the [User's Guide](https://formdo.github.io/blokjutsu/): installing, a tour of the
+window, writing prompts, and every control explained.
+
+![The Blokjutsu window: controls on the left; on the right, an image of three bowls of ice cream on a diner counter with handwritten cards reading CHOCOLATE, CHERRY, and PLAIN](docs/assets/screenshots/main-window.webp)
+
+## What Blokjutsu does
+
+- Text to image, image to image, variations, inpainting, outpainting, cropping, and upscaling
+- Describe image and Enhance prompt, written by MOSS-Image's own text encoder
+- Live previews, a scrolling history, and each image's settings saved beside it
+
+## Open source all the way down
+
+With Blokjutsu, the model, the code that runs it, and the app around it are all yours to run, keep, and adapt.
+
+Every part of Blokjutsu is released under the [Apache License 2.0](LICENSE), a
+[permissive](https://en.wikipedia.org/wiki/Comparison_of_free_and_open-source_software_licenses) open-source
+license:
+
+- **Blokjutsu's source code**, in this repository
+- **MOSS-Image's code**, the pipeline that turns a prompt into an image
+- **MOSS-Image's model weights**, including the Qwen3.5-9B text encoder and FLUX.2 image decoder they contain
+
+Apache 2.0 lets anyone use, study, change, and share all of it, for any purpose, commercial or not, at no cost,
+and with no sign-up. The conditions are light: keep the license and copyright notices, and say what you changed.
+It also grants the patent rights needed to use the code. The libraries Blokjutsu builds on are open source too
+(see [What it uses](#what-it-uses)).
+
+## Requirements
+
+- A Mac with Apple silicon (M1 or later) and macOS 12.3 or later
+- 32 GB of memory or more; 48 GB or more is comfortable, and smaller Macs work slowly, if at all
+- About 40 GB of free disk space, mostly for the model
+
+## Install
+
+**Mac users:** open Terminal and paste
+
+```sh
+curl -LsSf https://formdo.github.io/blokjutsu/install.sh | sh
+```
+
+This installs Python and Blokjutsu into `~/Library/Application Support/Blokjutsu.noindex/` and puts
+**Blokjutsu** in your Applications folder. Nothing else on your Mac is changed. See the
+[User's Guide](https://formdo.github.io/blokjutsu/install.html) for details and uninstalling.
+
+**Python developers:** Blokjutsu needs Python 3.10 or later. We strongly suggest installing it in its own virtual
+environment. The exact library versions it was tested with are in [constraints.txt](constraints.txt), which pip
+can use with `-c constraints.txt`.
+
+```sh
+python3 -m venv .venv
+source .venv/bin/activate
+pip install blokjutsu
+blokjutsu
+```
+
+## Built on MOSS-Image
+
+Blokjutsu is an independent desktop front end for **MOSS-Image**, the text-to-image model and pipeline by the
+[OpenMOSS Team](https://github.com/OpenMOSS) and [MOSI.AI](https://mosi.cn/). Blokjutsu is not affiliated with or
+endorsed by them. All of the image-making is theirs.
+
+- Repository: https://github.com/OpenMOSS/MOSS-Image
+- Technical report: https://arxiv.org/abs/2610.23374
+- User guide: https://github.com/OpenMOSS/MOSS-Image/blob/main/USERGUIDE.md
+
+If you use images or results from Blokjutsu in research, please cite MOSS-Image:
+
+```bibtex
+@misc{mossimage2026,
+  title        = {MOSS-Image},
+  author       = {{OpenMOSS Team}},
+  year         = {2026},
+  howpublished = {\url{https://github.com/OpenMOSS/MOSS-Image}}
+}
+@misc{mossimage2026report,
+  title         = {MOSS-Image Technical Report},
+  author        = {{MOSI.AI}},
+  year          = {2026},
+  eprint        = {2610.23374},
+  archivePrefix = {arXiv},
+  url           = {https://arxiv.org/abs/2610.23374}
+}
+```
+
+## What it uses
+
+The models are downloaded from [Hugging Face](https://huggingface.co), a site that hosts open AI models, and
+only when you ask. MOSS-Image's model is published there as MOSS-Image-SFT; its text encoder and image decoder
+come from Qwen and FLUX.2 and are included in that download.
+
+| model | by | license | role |
+|---|---|---|---|
+| [MOSS-Image-SFT](https://huggingface.co/OpenMOSS-Team/MOSS-Image-SFT) | OpenMOSS Team | Apache-2.0 | MOSS-Image's model, used by default |
+| [MOSS-Image-Base](https://huggingface.co/OpenMOSS-Team/MOSS-Image-Base) | OpenMOSS Team | Apache-2.0 | the untuned model, for people training their own versions (optional) |
+| [Qwen3.5-9B](https://huggingface.co/Qwen/Qwen3.5-9B) | Qwen Team, Alibaba Cloud | Apache-2.0 | reads prompts (part of MOSS-Image); with its output layer, downloaded separately, writes descriptions |
+| [FLUX.2 VAE](https://github.com/black-forest-labs/flux2) | Black Forest Labs | Apache-2.0 | turns the model's output into pixels (part of MOSS-Image) |
+
+Python libraries, installed alongside:
+
+| library | license | role |
+|---|---|---|
+| [PyTorch](https://pytorch.org), torchvision | BSD-3-Clause | numerical engine on the Apple GPU |
+| [Diffusers](https://github.com/huggingface/diffusers) | Apache-2.0 | runs the MOSS-Image pipeline |
+| [Transformers](https://github.com/huggingface/transformers), Accelerate | Apache-2.0 | text encoder, describing |
+| [huggingface_hub](https://github.com/huggingface/huggingface_hub), safetensors | Apache-2.0 | model files and downloads |
+| [httpx](https://www.python-httpx.org) | BSD-3-Clause | the confirmed downloads |
+| [PySide6 / Qt](https://www.qt.io/qt-for-python) | LGPL-3.0 | the window and controls |
+| [Pillow](https://python-pillow.org) | MIT-CMU | image files |
+| [NumPy](https://numpy.org) | BSD-3-Clause | arrays |
+| [PyObjC](https://github.com/ronaldoussoren/pyobjc) | MIT | macOS system icons and app name |
+
+## Local by design
+
+Blokjutsu runs the model on your Mac's own processor and memory. It uses the internet only once to initially
+download the models, and then, only after a confirmation dialog. After the models are downloaded once, Blokjutsu
+works completely offline. It does not go online to generate, edit, or store images. It does not go online to
+check for updates to itself.
+
+Images are saved as plain PNG files that hold only the image. If you want, a setting in Advanced options also
+writes each image's prompt and settings into the PNG.
+
+### What Blokjutsu keeps on your Mac
+
+| what | where | Delete all history |
+|---|---|---|
+| your images, each with its settings and any image you started from | the Output folder you choose (by default `~/Library/Application Support/Blokjutsu.noindex/images/`) | deleted, in every Output folder used |
+| the log, for troubleshooting | `~/Library/Application Support/Blokjutsu.noindex/logs/` | emptied |
+| working copies from Select area to change | `…/Blokjutsu.noindex/work/` | deleted |
+| a small file the live preview needs, built from your images | `…/Blokjutsu.noindex/preview/` | deleted |
+| your settings, including the last prompt | `…/Blokjutsu.noindex/settings.json` | prompt reset, preferences kept |
+| the captioning model | `…/Blokjutsu.noindex/caption/` | kept |
+| the image model | `…/Blokjutsu.noindex/models/` | kept |
+| the app and the Python it runs on | `~/Applications/Blokjutsu.app`, `…/Blokjutsu.noindex/tools/`, and `…/Blokjutsu.noindex/runtime/` | kept |
+
+The whole `…/Blokjutsu.noindex` folder is kept out of Time Machine backups and Spotlight. To back up your images,
+choose an Output folder elsewhere, such as `~/Pictures/Blokjutsu`.
+
+**Delete all history** (in the File menu) removes everything made from your prompts and images and keeps your
+preferences and the models. The [User's Guide](https://formdo.github.io/blokjutsu/local.html) has the details, including what macOS itself
+remembers.
+
+## Contributing
+
+[CONTRIBUTING.md](CONTRIBUTING.md) explains how to set up a development environment, run the tests, and build the
+Mac app. Architecture and technical notes are in the [developer pages](https://formdo.github.io/blokjutsu/developers.html).
+
+## Roadmap
+
+What comes next is in [ROADMAP.md](ROADMAP.md).
+
+## Bug reports and feature requests
+
+Please report bugs and request features as [GitHub issues](https://github.com/formdo/blokjutsu/issues). For help
+using Blokjutsu, see the [User's Guide](https://formdo.github.io/blokjutsu/) and its
+[Troubleshooting](https://formdo.github.io/blokjutsu/troubleshooting.html) page.
+
+## Etymology
+
+**Blokjutsu** (BLOK-joot-soo, /ˈblɒk.dʒuː.tsuː/), *noun*. The art of the block.
+
+From Danish *blok*, "block," and Japanese *jutsu* (術, じゅつ), "art" or "technique." The name comes from how
+MOSS-Image works: it treats an image as blocks of pixels, each 16 × 16 square one unit for the model, and
+transforms them step by step from noise into the finished image.
+
+## Design inspiration
+
+The block designs in the icon and the app draw on
+
+- the [Kohs block design test](https://en.wikipedia.org/wiki/Kohs_block_design_test), introduced by Samuel C.
+  Kohs in 1920: colored cubes, some faces split diagonally, arranged to match a pattern
+- [Froebel's gifts](https://en.wikipedia.org/wiki/Froebel_gifts), the wooden building blocks of Friedrich
+  Fröbel's first kindergartens
+- the primary colors and simple geometry of the [Bauhaus](https://en.wikipedia.org/wiki/Bauhaus)
+
+## Authors
+
+Blokjutsu was written by Bob Carpenter together with Claude, Anthropic's AI model.
+
+## License
+
+Copyright 2026 Bob Carpenter. Apache License 2.0; see [LICENSE](LICENSE) and [NOTICE](NOTICE).
+`blokjutsu/moss_image.py` is MOSS-Image's pipeline code, copied unchanged, and `blokjutsu/moss_forward.py` is
+adapted from it (both Apache-2.0). "MOSS-Image" is the OpenMOSS Team's name and is used here only to say what
+this app runs.