mlx-dfloat 0.1.0__tar.gz

mlx_dfloat-0.1.0/.coveragerc-integration

@@ -0,0 +1,5 @@
+[run]
+branch = true
+
+[report]
+show_missing = true

mlx_dfloat-0.1.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: IonDen

mlx_dfloat-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+name: CI
+on:
+  push:
+    branches: [main, "feature/**"]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: macos-15
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # hatch-vcs needs tags/history
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --locked --group dev
+      - run: uv run python -c "import mlx.core; print('mlx import OK')"
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy
+      - name: Metal capability probe (informational)
+        continue-on-error: true
+        run: uv run python scripts/ci_metal_probe.py
+      - name: Test (required)
+        run: uv run pytest --cov=mlx_dfloat --cov=scripts --cov-report=term-missing --cov-fail-under=85
+  integration:
+    # The mflux lane: installs the optional extra from the lock (torch and transformers come with
+    # mflux, pinned there too) and runs only the tests that need it.
+    runs-on: macos-15
+    strategy:
+      matrix:
+        # The lock pins mflux 0.20.0. A second row (another mflux release) would need the unlocked
+        # form instead of `uv sync --extra mflux`: `uv pip install "mflux==<version>"` after the
+        # sync, then `uv run --no-sync` for the steps below.
+        mflux: ["0.20.0"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --locked --group dev --extra mflux
+      - run: uv run --extra mflux --group dev python -c "import mflux, mlx.core, importlib.metadata as m; print('mflux', m.version('mflux'))"
+      # No combined threshold: init.py's tests run in the default lane (its live ones skip without a token); the next step gates model.py on its own.
+      - name: Integration tests (mflux lane)
+        env:
+          # Every FLUX.1 base repository is gated on the Hub (schnell auto-approved), so the three
+          # live tokenizer tests skip without a token; this is the variable huggingface_hub reads first.
+          # Only this step gets it: the actions, the sync and the collection and coverage steps have
+          # no use for it. The secret is a read-only Hub token; the default lane runs without one.
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: uv run --extra mflux --group dev pytest -m mflux --run-network --cov=mlx_dfloat.mflux.flux1.model --cov=mlx_dfloat.mflux.flux1.init --cov-config=.coveragerc-integration --cov-report=term-missing -q -p no:cacheprovider -rs
+      - name: model.py coverage on its own (mflux lane)
+        run: uv run --extra mflux --group dev coverage report --include='*/mflux/flux1/model.py' --fail-under=80
+      - name: The lane collected mflux tests
+        run: test "$(uv run --extra mflux --group dev pytest -m mflux --co -q -p no:cacheprovider | grep -c '::')" -ge 2
+  build:
+    # Same action the release workflow uses, so a distribution that would fail at tag time
+    # (e.g. a build-backend metadata version newer than the bundled twine) fails on the PR.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: hynek/build-and-inspect-python-package@v3.0.1

mlx_dfloat-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,47 @@
+name: release
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    # ubuntu, not macOS: the package is a pure-Python (py3-none-any) wheel, so the
+    # build is platform-independent, and pypa/gh-action-pypi-publish is Linux-only.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0  # hatch-vcs derives the version from the tag
+      - uses: hynek/build-and-inspect-python-package@v3.0.1
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: Packages
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: Packages
+          path: dist
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v3
+        with:
+          files: dist/*
+          generate_release_notes: true
+          draft: false
+          # Tags containing a hyphen (e.g. v0.2.0-alpha) are marked prerelease.
+          prerelease: ${{ contains(github.ref_name, '-') }}

mlx_dfloat-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+.DS_Store
+.codegraph/
+.hypothesis/
+docs/superpowers/
+docs/backlog/
+/.superpowers/
+/CLAUDE.md
+/AGENTS.md
+/_spike/
+/_artifacts/scratch/
+.coverage
+coverage.json
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+__pycache__/
+build/
+dist/
+*.egg-info/
+src/mlx_dfloat/_version.py
+
+bench/results/**/embeds*.safetensors
+bench/results/**/*.png
+*.png

mlx_dfloat-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

mlx_dfloat-0.1.0/CHANGELOG.md

@@ -0,0 +1,158 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-01
+
+The first release.
+
+### Added
+
+- Project skeleton: package layout, MLX memory caps derived from the device's working-set size, test gates for
+  slow and networked tests, and CI.
+- Reading and decoding DFloat11 (DF11) checkpoints. A safetensors header reader and a DF11 format reader check the
+  `dfloat11_config` block and each compressed group, and raise `DFloatFormatError` on malformed or unsafe input.
+  Legacy pickle-format repos are refused and never unpickled. A pure NumPy reference decoder turns a group back into
+  its BF16 bit patterns, bit for bit, and raises `DFloatResourceError` when a decode would exceed its memory budget.
+  Two scripts in the repository check a conversion against the original BF16 weights: one decodes a whole local
+  checkpoint, the other samples a few groups of a Hugging Face repo over range requests. They exit 0 when every
+  compared value matches, 1 on a real mismatch, 2 on any other error, and 70 or 71 when the memory or wall-clock
+  watchdog aborts the run.
+- A Metal decode kernel for DFloat11 groups, behind `mlx_dfloat.decode`. `decode_group(group, backend="metal")`
+  returns the BF16 bit patterns and a per-block status word, `check` refuses a group whose status reports an invalid
+  code, a count mismatch or a broken thread chain, and `available_backends` says whether the kernel compiles and runs
+  on this machine; nothing falls back silently. Every decode path is tested bit for bit against the NumPy reference:
+  hand-built codebooks, encoder round-trips, a real Qwen3-4B slice, and corrupt inputs that must end with an error
+  instead of a hang. On an M1 Max the kernel decodes 50 to 54 GB/s of BF16 output when a block's output is staged
+  through threadgroup memory and 19 to 24 GB/s when it writes straight to device memory
+  (`scripts/bench_decode_kernel.py`, median of 5 repetitions after a warm-up); staged is the default, and the direct
+  path is the fallback for blocks larger than the staging buffer. `verify_checkpoint.py --decoder metal` checks a
+  whole checkpoint through the kernel, against the BF16 original when one is given and against the reference
+  otherwise: Qwen3-4B decodes bit-identically in 12.8 s where the reference took 223 s, and all 57 groups of
+  FLUX.1-schnell match the reference.
+- A measurement rig for the question the project hinges on: how much a FLUX.1 denoise step slows down when every
+  transformer block's weights are decoded just in time. `scripts/bench_flux_step.py` runs one mode per process, either
+  decoding per block or a control that swaps pre-decoded weights into the same graph, and reports the paired overhead;
+  `scripts/bench_control_validation.py` checks that control against a run whose BF16 weights are all resident, on a
+  reduced-depth transformer and through the same per-block path; `scripts/encode_prompt.py` encodes the prompt once,
+  so the timed process holds no text encoder. Measured on an M1 Max (32 GB, macOS 27.0, mlx 0.32.2, mflux 0.20.0) at
+  1024², five timed steps in each of three rounds: FLUX.1-schnell costs 6.1 % more per step with a one-block
+  evaluation run-ahead and 8.5 % with a per-block evaluation; FLUX.1-dev costs 5.0 % either way (the dev prompt was
+  encoded with the schnell text encoders at 512 tokens, the same T5 and CLIP architecture, because the dev base
+  repository is gated). The control agrees with that run within 0.13 %; the per-block evaluation itself costs 0.21 s
+  (schnell) to 0.26 s (dev) per step, measured against a control that evaluates only at the end of the step. In the
+  step, decoding costs 2.1 to 3.4 times what the isolated kernel benchmark predicts from its throughput. A follow-up
+  measurement on schnell (one round of five timed steps per mode, with the bench's new `--trace` and `--cache-limit`
+  options) attributes most of that difference to memory allocation: at the bench's 1.4 GB cache limit the activation
+  buffers each block frees already fill MLX's buffer cache, so every block's decoded output is released instead of
+  kept and allocated fresh for the next block: about 30 ms for a double block and 14 ms for a single one on the
+  per-block stamps, and 1.29 s of a step as the difference between two cache limits. With a 2.5 GB limit, large enough
+  that a decoded buffer survives in the cache next to those activations, the
+  per-block overhead on schnell is 4.0 % for one more GiB of memory, and the in-step decode time is 1.5 times the
+  isolated prediction. Decoding the next block on a second GPU stream (`df11-prefetch`, submitted after the previous
+  block's evaluation returns) hides about a fifth of the kernel's time and, at that submission point, none of the
+  allocation; since the cache limit removes that cost anyway, the integration will evaluate per block and size the
+  cache limit instead. A timed process peaks at about 19 GiB of memory, 20.3 GiB with the look-ahead.
+- The scripts' memory watchdog now enforces its ceiling on the process footprint the OS reports rather than on RSS
+  plus MLX memory, which counted loaded arrays twice.
+- A block-boundary integration layer, `mlx_dfloat.integrate`: zero-size placeholders for a module's matrices, weight
+  providers that decode a DFloat11 group just in time, reuse one already decoded, or hand back a resident BF16
+  weight, and a seam that assigns one block's weights, runs the block, evaluates by policy and restores the
+  placeholders afterward. The seam and the providers raise when a matrix name falls outside the map or a weight
+  comes back the wrong shape, instead of leaving the layer at its placeholder value; a separate coverage check makes
+  sure every other parameter (biases, norm scales, embedders) gets exactly one tensor from the checkpoint. The FLUX.1
+  adapter, `mlx_dfloat.mflux.flux1`, reads mflux's own weight mapping to name each block's matrices and builds mflux's
+  transformer directly from a DFloat11 checkpoint; it needs the optional `mlx-dfloat[mflux]` extra and is tested with
+  mflux 0.20.0. Three new errors mark
+  this boundary: `DFloatIntegrationError` for a seam or name-map invariant that failed, `DFloatUnsupportedError` for
+  an option this path does not implement, and `DFloatDependencyError` for a missing optional dependency. The step
+  bench and the control validation now run through this integration code instead of a separate rig.
+
+- `DFloatFlux1` and the `mlx-dfloat generate` command: FLUX.1 schnell, dev and Krea-dev images from a DFloat11
+  transformer through mflux, decoded one block at a time. The VAE and the text encoders come from the base
+  repository; its BF16 transformer is never downloaded. The text encoders and the compressed transformer are never
+  in memory together: a prompt is encoded first, then the encoders are dropped and the compressed weights loaded;
+  a new prompt after that reloads both (`encode()` pre-encodes several prompts at once). Each call derives an MLX
+  buffer-cache limit from the checkpoint and the resolution, estimates the peak memory per phase against the
+  device's budget, and restores the process's cache limit afterwards. A call that would not fit is refused, and so
+  is any size above 1024², the largest measured so far (`fit_check=False` overrides both; above 1024² the estimate
+  is an extrapolation). On a 32 GB Mac every call drops the compressed set before the VAE decode, because at 1024²
+  the decode next to the resident set measured 23.29 GiB, over the budget, and smaller sizes have not been measured;
+  the next call reloads the set in about 26 s. A Mac with a larger budget keeps it. All three base repositories are
+  gated on the Hub and need `hf auth login`: FLUX.1-schnell's with automatic approval once its Apache-2.0 license is
+  accepted, FLUX.1-dev's and FLUX.1-Krea-dev's with manual approval under Black Forest Labs' non-commercial license.
+  Their encoders and VAE are byte-identical, so the schnell base also serves dev and Krea-dev. The command installs the memory caps and the footprint watchdog; the Python API does
+  neither. Measured on an M1 Max (32 GB, macOS 27.0, mlx 0.32.2, mflux 0.20.0) at 1024²: FLUX.1-schnell (4 steps)
+  peaked at 19.94 GiB (19.95 GiB with depth-2 evaluation) in 1 minute 54 seconds including imports, with per-phase
+  MLX peaks of 10.09 GiB encoding the prompt, 15.20 GiB loading the compressed set, 17.44 GiB denoising and 9.55 GiB
+  decoding the VAE; FLUX.1-dev (20 steps, guidance 3.5) peaked at 20.10 GiB in 7 minutes 6 seconds; FLUX.1-Krea-dev
+  (20 steps, guidance 3.5) peaked at 20.09 GiB in 7 minutes 2 seconds. All three stay under the machine's measured
+  22.96 GiB budget. `scripts/verify_image.py` compares the final latents with those of the same transformer
+  streaming the BF16 shards block by block: FLUX.1-schnell's latents match bit for bit and are not degenerate, and
+  the two images match pixel for pixel; FLUX.1-dev and FLUX.1-Krea-dev were not checked this way, because their BF16
+  transformers are gated and were not on disk to compare against. Quantisation, LoRA, img2img, ControlNet and the
+  PiD decoder are refused with a reason; `negative_prompt` is accepted and ignored, as mflux does for FLUX.1.
+- A reproducible FLUX.1 benchmark driven by scenario files. A scenario (`bench/scenarios/*.toml`, one each for
+  FLUX.1-schnell and FLUX.1-dev) pins the DFloat11 and base snapshot revisions, the prompt, the seed, the size, the
+  step counts, the rounds, the MLX cache limit and the conditions. The loader refuses unknown or malformed fields,
+  and every result file carries the scenario's hash. `scripts/bench_flux1.py` runs a scenario end to end. It first
+  checks the machine (power, charging, battery, CPU speed limit, lid, disk, free memory, other heavy processes) and
+  stops unless `--skip-preflight` is given, and it checks again before each condition's process: a failed check
+  stops the run there, `report.json` records which checks failed, and the same command resumes later. It reads the
+  pinned snapshots from the local cache only, encodes the prompt once, and runs every condition and round as its own
+  process, interleaved, resuming from the files already written and refusing ones from another scenario or another
+  version of the code. The step bench gains a
+  `q8` condition: mflux's own transformer quantised to 8 bits at load from the pinned base, with one evaluation per
+  step, under the scenario's cache limit like the other conditions (mflux's own generate sets none). Its record
+  carries the bits, group size and mode read from a built block.
+- The numbers from that benchmark, measured on an M1 Max (32 GB, macOS 27.0.1, mlx 0.32.2, mflux 0.20.0) at 1024²
+  under a 2.5 GB cache limit, five timed steps after two warm-up steps in each of three rounds. On FLUX.1-dev a step
+  costs 3.52 % more with per-block evaluation (19.24 s against 18.59 s) and 4.61 % more with a one-block run-ahead;
+  on FLUX.1-schnell, 4.05 % (19.28 s against 18.53 s) and 4.24 %. The run-ahead did not help on either model.
+  Evaluating after every block, measured on the control alone, cost 0.41 s per step on schnell and nothing
+  measurable on dev (the per-block control was 0.07 s faster); both sides of the overhead comparison pay it. A DF11
+  step with per-block evaluation takes 1.26 times as long as the q8 step on dev (15.26 s) and 1.35
+  times on schnell (14.25 s). These ratios are rough, because the q8 step's median moved by about 2 s between rounds
+  in both scenarios while the DF11 step's moved by 0.7 s at most. The dev depth-2 figure pools rounds that read
+  −1.6 %, +5.9 % and +6.5 % one at a time (each round's DF11 median over its control's), because round 1's depth-2
+  control ran slow; rounds 2 and 3 alone give +6.2 %. The q8 step also peaked lower, at 14.8–14.9 GiB
+  against DF11's 19.7–20.0 GiB; what DF11 keeps and q8 gives up is the exact BF16 output. The dev run used
+  `--skip-preflight`: the only failed gate was "not charging", because macOS held the battery at 80 % for optimised
+  charging, and its `report.json` records both. The check now lets a battery at 50 % or more run on a charger that
+  is not charging it. The results are in `bench/results/flux1-schnell-1024/` and
+  `bench/results/flux1-dev-1024/`; `uv run --group bench python -m scripts.bench_flux1 <scenario file>
+  --results-root <a fresh directory>` reproduces them.
+- `mlx_dfloat.bench`, the pure side of the benchmark: the scenario loader, a smaller Mac's MLX limits and watchdog
+  ceiling, the launch check, the reader and summary of per-condition results, and the README renderers. It does not
+  import mflux or touch the GPU.
+- `mlx-dfloat generate --tier GB` runs under a smaller Mac's MLX memory and cache limits, watchdog ceiling and fit
+  budget, and labels its report CAPPED; the host's own size keeps the host's limits and gives a MEASURED report.
+  `--memory-ceiling BYTES` lowers the watchdog ceiling alone, under the host's limits, and labels the report PROOF.
+  Every report now records the limits in force, its label, the image size and the watched peak, and writes the home
+  directory as `~`.
+- The measured 32 GB rows for FLUX.1-schnell, FLUX.1-dev and FLUX.1-Krea-dev at 1024² (`bench/results/tiers/`):
+  watched peaks of 19.78, 19.96 and 20.04 GiB, all under the M1 Max's 22.96 GiB fit budget.
+- A harness proof (`bench/results/harness-proof/`): under one 19.25 GiB watchdog ceiling, a 512² FLUX.1-schnell run
+  finished at 18.64 GiB, and a 1024² run was stopped by the watchdog at 19.32 GiB with exit 70. The watchdog's abort
+  file now names the model, size, seed and steps of the run it stopped, and the proof reads the stopped run's size
+  from it.
+- `scripts/bench_table.py` writes the README's measured-numbers blocks from `bench/results/`, and a test fails when the
+  README and the result files disagree.
+
+### Changed
+
+- CI runs the whole test suite, Metal tests included, on the macOS runner, which reports a Metal device; a probe step
+  prints the device it found.
+- The memory watchdog enforces its ceiling on the larger of the process footprint and MLX's active plus cached memory,
+  names the counter that tripped in its abort file, and records the peak of each.
+- The benchmark refuses a pinned snapshot whose weight shards are not all in the local cache, and names the
+  `hf download` command that completes it.
+- CI's mflux lane gets the Hub token for its test step only, so the three tokenizer tests against the gated FLUX.1
+  bases run there instead of skipping.
+
+[Unreleased]: https://github.com/IonDen/mlx-dfloat/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/IonDen/mlx-dfloat/releases/tag/v0.1.0

mlx_dfloat-0.1.0/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.

mlx_dfloat-0.1.0/NOTICE

@@ -0,0 +1,40 @@
+mlx-dfloat
+Copyright 2026 Denis Ineshin
+
+Licensed under the Apache License, Version 2.0.
+
+mlx-dfloat is an independent reader and decoder for the DFloat11 checkpoint format. It is not a fork of DFloat11
+and is not affiliated with the DFloat11 authors.
+
+DFloat11
+--------
+The DFloat11 method and checkpoint format come from:
+
+  Tianyi Zhang, Mohsen Hariri, Shaochen Zhong, Vipin Chaudhary, Yang Sui, Xia Hu, Anshumali Shrivastava.
+  "70% Size, 100% Accuracy: Lossless LLM Compression for Efficient GPU Inference via Dynamic-Length Float
+  (DFloat11)". arXiv:2504.11651, https://arxiv.org/abs/2504.11651. The paper is distributed under the
+  Creative Commons Attribution 4.0 International licence (CC BY 4.0).
+
+The authors' implementation is https://github.com/LeanModels/DFloat11, licensed under the Apache License,
+Version 2.0. The format reader and the decoders in this package are a separate implementation of the published
+format. The only file taken from that repository is the test-only encoder described below.
+
+Test-only encoder and test data
+-------------------------------
+tests/_upstream/dfloat11_encoder.py is derived from dfloat11_utils.py of https://github.com/LeanModels/DFloat11
+at commit 457733886c, Copyright 2025 Tianyi Zhang, licensed under the Apache License, Version 2.0. It builds test
+fixtures only and is not part of the installed package. tests/_upstream/NOTICE lists the changes made to it.
+
+tests/fixtures/upstream/ holds a small slice (four compressed blocks of one matrix) of the DFloat11/Qwen3-4B-DF11
+checkpoint and the matching BF16 values from Qwen/Qwen3-4B, which is licensed under the Apache License, Version 2.0.
+
+mflux
+-----
+The optional FLUX.1 integration (the mlx-dfloat[mflux] extra) and the benchmark run on mflux,
+https://github.com/mflux-community/mflux, Copyright (c) 2026 Filip Strand, licensed under the MIT License. mflux is a
+dependency installed separately; mlx-dfloat does not include its code.
+
+Model weights
+-------------
+mlx-dfloat ships no model weights. A DFloat11 checkpoint carries the licence of the model it was compressed from;
+FLUX.1-dev and FLUX.1-Krea-dev, for example, are under Black Forest Labs' non-commercial licence.