aneforge 0.1.0__tar.gz

aneforge-0.1.0/.githooks/pre-commit

@@ -0,0 +1,35 @@
+#!/bin/sh
+# Pre-commit gate for ANEForge: the off-hardware CI checks, run before every commit so
+# broken code cannot land. Mirrors .github/workflows/ci.yml's lint + build jobs:
+#   1. ruff check          (lint)
+#   2. compileall aneforge (every module byte-compiles)
+# The on-device corpus (tests/run_corpus.py) and pytest suites need ANE hardware, so they
+# are NOT run here (they gate separately; see docs development.md).
+#
+# Enable once per clone (git does not auto-trust committed hooks):
+#   git config core.hooksPath .githooks
+# Bypass a single commit with:  git commit --no-verify
+set -e
+cd "$(git rev-parse --show-toplevel)"
+
+if [ -x .venv/bin/ruff ]; then RUFF=.venv/bin/ruff
+elif command -v ruff >/dev/null 2>&1; then RUFF=ruff
+else echo "pre-commit: ruff not found - run: pip install -e '.[dev]'" >&2; exit 1; fi
+
+if [ -x .venv/bin/python ]; then PY=.venv/bin/python
+elif command -v python3 >/dev/null 2>&1; then PY=python3
+else echo "pre-commit: python3 not found" >&2; exit 1; fi
+
+echo "pre-commit: ruff check"
+if ! "$RUFF" check; then
+    echo "pre-commit: BLOCKED - ruff check failed. Fix (or '$RUFF check --fix'), or bypass with 'git commit --no-verify'." >&2
+    exit 1
+fi
+
+echo "pre-commit: compileall aneforge"
+if ! "$PY" -m compileall -q aneforge; then
+    echo "pre-commit: BLOCKED - a module in aneforge/ failed to byte-compile." >&2
+    exit 1
+fi
+
+echo "pre-commit: OK"

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

@@ -0,0 +1,103 @@
+name: CI
+
+# ANEForge dispatches to the Apple Neural Engine, which GitHub's hosted runners cannot
+# reach: their macOS images are Apple Silicon but virtualized, and the ANE is not passed
+# through to the guest (the same reason CoreML falls back to CPU in a VM). So the on-device
+# correctness corpus (tests/run_corpus.py) is run by hand on a Mac with an ANE, e.g.
+# `bash scripts/reproduce.sh gates`. This workflow covers everything CI *can* verify:
+# lint, packaging, a multi-version compile + import matrix, the hardware-free unit tests,
+# the documentation build, and — on a hosted macOS runner — that the Objective-C++
+# dispatch dylib actually compiles (which the Linux jobs cannot do).
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check
+
+  build:
+    name: package (build + twine)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*
+
+  compile-import:
+    name: compile + import (py ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+      # Every module byte-compiles (no import, so no dylib/ANE needed).
+      - run: python -m compileall -q aneforge
+      # The package imports with only NumPy and builds a graph; compile/dispatch is lazy
+      # and needs the ANE, so it is exercised on-device, not here.
+      - run: pip install -e .
+      - run: python -c "import aneforge as af; print('aneforge', af.__version__); af.input((1, 3, 8, 8))"
+
+  unit-tests:
+    name: off-device unit tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      # The compile-backoff rate-limiter is a pure unit test (fake clock, no ANE).
+      - run: pytest tests/test_compile_breaker.py -q
+
+  docs:
+    name: docs (mkdocs build)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install -r docs/requirements.txt
+      - run: mkdocs build --strict
+
+  macos:
+    name: macOS build + smoke (Apple Silicon, no ANE)
+    runs-on: macos-14
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      # The Objective-C++ dispatch shim links Apple frameworks and only builds on macOS;
+      # this proves it compiles. The hosted runner has no ANE, so it is never dispatched
+      # (the dylib loads lazily on first dispatch, which does not happen here).
+      - run: sh aneforge/_lib/build.sh
+      - run: python -m compileall -q aneforge
+      - run: pip install -e ".[dev]"
+      # Import + graph build on macOS, and the hardware-free unit test.
+      - run: python -c "import aneforge as af; print('aneforge', af.__version__); af.input((1, 3, 8, 8))"
+      - run: pytest tests/test_compile_breaker.py -q

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

@@ -0,0 +1,70 @@
+# Build and publish aneforge to PyPI via Trusted Publishing (OIDC, no stored token).
+#
+# One-time setup on PyPI (https://pypi.org/manage/account/publishing/): add a pending
+# publisher for project "aneforge", owner "sbryngelson", repo "ANEForge", workflow
+# "release.yml", environment "pypi". Repeat on https://test.pypi.org with environment
+# "testpypi" if you want the dry-run path.
+#
+# Publish to PyPI:     push a tag matching v* (e.g. `git tag v0.1.0 && git push --tags`).
+# Dry-run to TestPyPI: Actions tab -> Release -> Run workflow -> target = testpypi.
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Publish target"
+        type: choice
+        options: [testpypi, pypi]
+        default: testpypi
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade build
+      - run: python -m build
+      - run: python -m pip install --upgrade twine && python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    needs: build
+    if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    needs: build
+    if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && inputs.target == 'pypi')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

aneforge-0.1.0/.gitignore

@@ -0,0 +1,111 @@
+# =====================================================================
+# ANEForge .gitignore
+#
+# Source only. Everything generated (compiled binaries, traces, model
+# dumps, runtime sweeps) stays local and is not tracked.
+# =====================================================================
+
+# Generated artifacts: runtime outputs, traces, model dumps.
+ane_artifacts/
+
+# Build outputs: per-machine compiled invoker/probe binaries, dSYM bundles, cache.
+# Invokers rebuild from aneforge/_invokers/; the dispatch dylib from aneforge/_lib/.
+ane_build/
+
+# The package's bundled dispatch dylib is built on the target Mac (sh
+# aneforge/_lib/build.sh); we ship the source, not the per-machine binary.
+aneforge/_lib/*.dylib
+
+# Local RE/paper test tooling (fuzzers, capability census + its sweep data).
+# Untracked on purpose: not user-facing proof, not collected by pytest, not shipped.
+utils/
+
+# Python build artifacts (python -m build / setuptools).
+build/
+dist/
+
+# =====================================================================
+# macOS / OS junk
+# =====================================================================
+.DS_Store
+._.DS_Store
+**/.DS_Store
+
+# =====================================================================
+# Python
+# =====================================================================
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+.eggs/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.venv/
+venv/
+.venv/
+
+# =====================================================================
+# Editors
+# =====================================================================
+*.swp
+*.swo
+*.swn
+.vscode/
+.idea/
+.cursor/
+
+# =====================================================================
+# Local scratch / temp output the fuzzer or probes may drop into the repo
+# =====================================================================
+/tmp_*/
+/scratch_*/
+*.tmp
+
+# =====================================================================
+# Local AI-tool session files
+# =====================================================================
+.codex/
+.claude/
+
+# =====================================================================
+# Secrets — defensive, none expected in this tree
+# =====================================================================
+*.env
+*.env.local
+.env.*
+credentials.json
+*_credentials.json
+*.pem
+*.key
+auth.json
+
+# =====================================================================
+# Example outputs and on-disk caches (regenerated on demand)
+# =====================================================================
+.aneforge_cache/
+examples/sd15_out.png
+
+# vhs intermediate; the shipped README asset is demo.png (APNG), see demo.tape.
+docs/assets/demo.gif
+
+# LaTeX figure build artifacts
+docs/figures/*.aux
+docs/figures/*.log
+docs/figures/*.synctex.gz
+
+# Full-MNIST loader cache (fetched, never committed)
+examples/data/mnist_cache/
+
+# Debug matrix dumps from the solver probes
+.dbg_slmat/
+
+# CIFAR-10 dataset downloaded by examples/cifar_data.py (large, regenerated on demand)
+examples/data/cifar10/
+examples/data/cifar_cnn.npz
+
+# MkDocs build output
+site/

aneforge-0.1.0/.readthedocs.yaml

@@ -0,0 +1,15 @@
+# Read the Docs build configuration for the ANEForge package documentation.
+# https://docs.readthedocs.io/en/stable/config-file/v2.html
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+mkdocs:
+  configuration: mkdocs.yml
+
+python:
+  install:
+    - requirements: docs/requirements.txt

aneforge-0.1.0/CITATION.cff

@@ -0,0 +1,12 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "ANEForge: a direct, CoreML-free Apple Neural Engine backend"
+type: software
+authors:
+  - family-names: Bryngelson
+    given-names: "Spencer H."
+    affiliation: "Georgia Institute of Technology"
+repository-code: "https://github.com/sbryngelson/ANEForge"
+license: MIT
+version: "0.1.0"
+date-released: "2026-06-10"

aneforge-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing
+
+Build, test, and "adding an operator" details are in
+[`docs/development.md`](docs/development.md). This is the short version.
+
+## Bug reports
+
+Behavior on the ANE is per-chip and per-OS, so include:
+
+- The chip (M1 through M5, or the A-series equivalent) and the macOS version.
+- A minimal graph that reproduces it: ops, shapes, dtypes.
+- Expected versus actual: numbers, traceback, or compile error.
+
+Two things are expected rather than bugs: a graph that compiles for one family
+but overflows a dimension cap on another (caps are per family, see
+[`docs/capabilities.md`](docs/capabilities.md)), and small CPU/ANE divergence at
+boundary fp16 values. A wrong result well inside the fp16 range is a real bug.
+
+Report security issues privately, not in a public issue: see
+[`SECURITY.md`](SECURITY.md).
+
+## Changes
+
+Operator-coverage gaps are the place to start: anything in
+[`docs/capabilities.md`](docs/capabilities.md) not yet covered, via the four-step
+path in [`docs/development.md`](docs/development.md#adding-an-operator). Open an
+issue first for larger or architectural changes.
+
+## Setup
+
+```sh
+pip install -e ".[dev]"               # ruff + pytest
+sh aneforge/_lib/build.sh             # build the dispatch dylib (needs the Mac)
+git config core.hooksPath .githooks   # off-hardware pre-commit checks
+```
+
+The corpus is the gate and must pass before a change lands:
+
+```sh
+KMP_DUPLICATE_LIB_OK=TRUE PYTHONPATH=. python3 tests/run_corpus.py
+```
+
+Most tests need a real ANE, so CI runs only the off-hardware checks. Run the
+corpus and the pytest suite on your Mac before opening a pull request.
+
+## Style
+
+Python 3.10+, linted with `ruff`. Match the surrounding packed style; do not
+reformat existing code.
+
+## License
+
+Contributions are licensed under the [MIT License](LICENSE).

aneforge-0.1.0/LICENSE

@@ -0,0 +1,31 @@
+MIT License
+
+Copyright (c) 2026 Spencer H. Bryngelson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+NOTE ON SCOPE. ANEForge is an independent research project. It dispatches to the
+Apple Neural Engine through private, undocumented system symbols (the e5rt
+runtime) and is not an Apple product, is not endorsed by Apple, and relies on no
+Apple API contract. "Apple", "Apple Neural Engine", and related marks belong to
+Apple Inc. The MIT grant above covers this project's own source only; it confers
+no rights in Apple software, and the private interfaces it calls may change or
+break without notice. Use is intended for research and interoperability.

aneforge-0.1.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: aneforge
+Version: 0.1.0
+Summary: Direct Apple Neural Engine (ANE) backend. A CoreML-free Python frontend that compiles operator graphs into a single fused e5rt program and dispatches them to the ANE.
+Project-URL: Homepage, https://github.com/sbryngelson/ANEForge
+Project-URL: Repository, https://github.com/sbryngelson/ANEForge
+Project-URL: Documentation, https://aneforge.readthedocs.io
+Project-URL: Issues, https://github.com/sbryngelson/ANEForge/issues
+Author-email: Spencer Bryngelson <shb@gatech.edu>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ane,apple-neural-engine,apple-silicon,e5rt,espresso,inference,machine-learning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: numpy
+Provides-Extra: bench
+Requires-Dist: mlx>=0.31; extra == 'bench'
+Requires-Dist: torch; extra == 'bench'
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-forked; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: models
+Requires-Dist: torch; extra == 'models'
+Requires-Dist: torchvision; extra == 'models'
+Requires-Dist: transformers; extra == 'models'
+Description-Content-Type: text/markdown
+
+# ANEForge
+
+[![CI](https://github.com/sbryngelson/ANEForge/actions/workflows/ci.yml/badge.svg)](https://github.com/sbryngelson/ANEForge/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-2e6b69.svg)](LICENSE)
+[![Apple Silicon](https://img.shields.io/badge/Apple%20Silicon-macOS%2014%2B-b84310.svg)](#install)
+
+**Train and run neural networks directly on the Apple Neural Engine, from
+Python, with no CoreML.**
+
+<p align="center">
+  <img src="docs/assets/demo.png" width="680"
+       alt="A small transformer trains from scratch and generates text live on the Apple Neural Engine">
+</p>
+
+<p align="center">
+  <sub>A transformer training from scratch on the engine (forward, backward, and
+  Adam), then completing a prompt. Reproduce with <a href="examples/demo.py"><code>python examples/demo.py</code></a>.</sub>
+</p>
+
+Apple exposes the Neural Engine only through CoreML, and only for inference.
+CoreML decides whether your model lands on the engine or quietly falls back to the
+CPU or GPU, and it gives you no way to train there. ANEForge skips it: it compiles
+a tensor graph into one ANE program and dispatches that program through the same
+private `aned` stack CoreML, MPSGraph, and Espresso use internally. From there:
+
+- **Training runs on the engine.** The forward pass, the backward pass, and the
+  Adam update all compile to ANE programs. A CNN trains from scratch on CIFAR-10 to
+  71%, on a chip Apple ships for inference only.
+- **Hardware layers CoreML can't reach.** `af.sdpa` drives the engine's
+  fused-attention layer directly, the one Apple's compiler decomposes and never
+  emits; 18 other native layers (`argmax`, `topk`, `sort`, geometry) come the same way.
+- **The engine, never a fallback.** A pretrained ResNet-18 runs end to end in
+  0.33 ms, matching reference to cosine 1.0000, at a fraction of the GPU's
+  energy (table below).
+- **Cross-compilation for chips you don't own.** Lower and gate a graph for any of
+  28 ANE targets (M1-M5) from one machine, and estimate its latency without running it.
+
+```python
+import aneforge as af
+
+x   = af.input((1, 3, 32, 32))             # a lazy graph input
+y   = af.conv(x, W, pad=1).relu().mean((2, 3))
+net = af.compile(y, compress="int8")       # graph -> one fused ANE program
+out = net(image)                           # callable; runs on ANE silicon
+
+# ...or load a pretrained model
+enc = af.load(".../all-MiniLM-L6-v2")      # MiniLM sentence encoder
+vec = enc(tokens)                          # on-device, cosine 1.0000 vs reference
+```
+
+A graph is built from 58 fused operators plus 19 native bridge operators, lowered
+into one program and reused across calls, near a 70 us dispatch floor.
+
+> **Status:** research project on Apple Silicon / macOS, verified on M5 Pro and M1
+> Max. Relies on private framework symbols that may change without notice. Not
+> affiliated with Apple.
+
+## Install
+
+Apple Silicon Mac, macOS 14+, Xcode command-line tools, Python 3.10+.
+
+```sh
+git clone https://github.com/sbryngelson/ANEForge.git
+cd ANEForge
+pip install -e .                              # core dependency is just NumPy
+PYTHONPATH=. python3 tests/op_smoketest.py    # compile + run each op on the ANE
+```
+
+The `e5rt` dispatch shim links Apple frameworks, so it compiles from source on your
+Mac. That happens automatically the first time you dispatch to the ANE; build it
+ahead of time with `python -m aneforge.build` if you prefer.
+
+Optional extras: `pip install -e ".[models]"` (torch / torchvision / transformers
+for the pretrained loaders) and `".[bench]"` (mlx / torch for the GPU-comparison
+tools). Then browse [`examples/`](examples/), starting with
+[`examples/quickstart.py`](examples/quickstart.py).
+
+## How it compares
+
+|                       | On the ANE        | No CoreML | Trains on it |
+| --------------------- | :---------------: | :-------: | :----------: |
+| CoreML / coremltools  | scheduler chooses | --        | no           |
+| MLX, PyTorch (MPS)    | no (GPU)          | yes       | on the GPU   |
+| **ANEForge**          | **yes (direct)**  | **yes**   | **yes**      |
+
+CoreML is the only public door to the engine, and it only ever decides whether to
+use it. ANEForge compiles to the engine directly, from an ordinary user process,
+with no entitlement and without disabling system integrity protection.
+
+## Measured
+
+Single input, fp16, on an M5 Pro. The GPU baseline is PyTorch on Metal (MPS) at
+fp16; energy is whole-package, read with `powermetrics`.
+
+| Pretrained model | ANE     | GPU (fp16) | ANE energy | GPU energy |
+| ---------------- | ------: | ---------: | ---------: | ---------: |
+| ResNet-18        | 0.33 ms | 2.03 ms    | 2.2 mJ     | 35 mJ      |
+| MiniLM encoder   | 0.53 ms | 1.92 ms    | 2.4 mJ     | 21 mJ      |
+| ViT-B/16         | 18.3 ms | 15.9 ms    | 75 mJ      | 612 mJ     |
+
+The engine is faster on the convolutional and encoder workloads and 8 to 16x more
+energy efficient on all three, even on ViT-B/16 where the GPU edges it on latency.
+Reproduce with
+[`bench/device_compare_wattcomplete.py`](bench/device_compare_wattcomplete.py)
+and [`bench/real_models_fp16.py`](bench/real_models_fp16.py); the full per-workload
+device map (16 classes, measured on M1 / M2 / M5) is in
+[`bench/results/`](bench/results/).
+
+## A fluid simulation on the Neural Engine
+
+<p align="center">
+  <img src="docs/assets/fluid_vorticity.png" width="400"
+       alt="A passive dye shaped as the word ANEForge stirred into glowing filaments by a fluid simulation on the Apple Neural Engine">
+</p>
+
+A passive dye is painted as the word ANEForge, and a 2-D incompressible
+Navier-Stokes flow (pseudo-spectral) stirs it into thin glowing filaments. Every
+Fourier transform in the 2,200-step loop runs on the ANE, and the whole
+simulation costs about 9 J at the measured 1.48 W rail. Reproduce with
+[`python examples/fluid_vorticity.py`](examples/fluid_vorticity.py).
+
+## What it does
+
+- **Graph -> compile -> run.** 58 fused operators (conv/pool, `matmul`/`bmm`/`einsum`,
+  activations, reductions, norms, softmax, attention, shape/geometry) into one
+  program with int8/int4/fp16 weights, plus a bridge route for 19 native ops the
+  public toolchain never emits.
+- **Streaming weight compression.** int8, int4-LUT, or sparse weights streamed from
+  the engine's dequant path (~4x smaller for int4), accuracy-gated.
+- **On-device uint8 image input,** dequantized in-graph, so raw camera or video
+  bytes feed the model directly.
+- **Resident state.** KV-cache and optimizer state kept on the engine across steps
+  via buffer aliasing (`share_buffer`).
+- **Accuracy-preserving optimizer.** `af.tune` measures equivalent lowerings on the
+  engine and returns the lossless pick.
+- **Linear algebra and spectral methods.** `aneforge.linalg` and `aneforge.fft` as
+  static-dataflow graphs.
+
+## What runs
+
+Pretrained models, each fused into one ANE program:
+
+| Model              | Task                       | Fidelity vs reference   |
+| ------------------ | -------------------------- | ----------------------- |
+| ResNet-18          | ImageNet classification    | cosine 1.0000           |
+| ViT-B/16           | vision transformer encoder | cosine 1.0000           |
+| all-MiniLM-L6-v2   | sentence embedding         | cosine 1.0000           |
+| ESPCN              | super-resolution           | runs end to end         |
+| Stable Diffusion 1.5 | U-Net + VAE (per component) | U-Net 1.5%, VAE 4.4% rel. |
+
+Trained from scratch on the engine: an MLP, a CNN (CIFAR-10 to 71%), a transformer
+block, a LLaMA-style block, and a character language model. Operator coverage is
+tracked op by op across M1 to M5 in the [op catalog](docs/op-catalog.md), the
+exhaustive native-MIL-op x device table; [capabilities](docs/capabilities.md) has
+the dtype matrix and the known limits.
+
+## Verify
+
+The correctness corpus compiles and runs every op and kernel on the ANE, and is
+the project's reproducibility gate:
+
+```sh
+KMP_DUPLICATE_LIB_OK=TRUE PYTHONPATH=. python3 tests/run_corpus.py
+KMP_DUPLICATE_LIB_OK=TRUE PYTHONPATH=. python3 -m pytest tests/ -q
+```
+
+## Documentation
+
+The manual lives in [`docs/`](docs/) (MkDocs; `pip install -r docs/requirements.txt`,
+then `mkdocs serve`), starting at [`docs/index.md`](docs/index.md). The API is
+documented in the module docstrings, and runnable usage in [`examples/`](examples/).
+
+## Contributing
+
+[`CONTRIBUTING.md`](CONTRIBUTING.md) has the bug-report checklist (include your
+chip and macOS version), the development setup, and where to start. Report security
+issues privately per [`SECURITY.md`](SECURITY.md).
+
+## License
+
+[MIT](LICENSE). The Apple Neural Engine is proprietary hardware, and the framework
+symbols this project calls are private, undocumented, and may change at any time.
+Nothing here is endorsed by, or constitutes an API contract from, Apple.