kyolo 0.1.0__tar.gz

kyolo-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 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.

kyolo-0.1.0/PKG-INFO

@@ -0,0 +1,254 @@
+Metadata-Version: 2.4
+Name: kyolo
+Version: 0.1.0
+Summary: kyolo: the YOLO object-detection family (v5-v26) in pure Keras 3, with PyTorch weight conversion.
+Author-email: Gitesh Chawda <gitesh.ch.0912@gmail.com>
+License: Apache License 2.0
+Project-URL: homepage, https://github.com/IMvision12/kyolo
+Project-URL: documentation, https://github.com/IMvision12/kyolo
+Project-URL: repository, https://github.com/IMvision12/kyolo.git
+Keywords: keras,keras3,yolo,object-detection,computer-vision,deep-learning,jax,tensorflow,pytorch,neural-networks,pretrained-weights,transfer-learning
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: keras>=3.5.0
+Requires-Dist: numpy>=1.24
+Provides-Extra: tensorflow
+Requires-Dist: tensorflow>=2.16; extra == "tensorflow"
+Provides-Extra: jax
+Requires-Dist: jax>=0.4.28; extra == "jax"
+Provides-Extra: torch
+Requires-Dist: torch>=2.2; extra == "torch"
+Requires-Dist: torchvision>=0.17; extra == "torch"
+Provides-Extra: conversion
+Requires-Dist: torch>=2.2; extra == "conversion"
+Requires-Dist: ultralytics>=8.2.0; extra == "conversion"
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.7; extra == "viz"
+Requires-Dist: pillow>=10.0; extra == "viz"
+Provides-Extra: tests
+Requires-Dist: pytest; extra == "tests"
+Requires-Dist: pytest-cov; extra == "tests"
+Dynamic: license-file
+
+# kyolo — YOLO in pure Keras 3
+
+`kyolo` is a pure [Keras 3](https://keras.io) implementation of the YOLO
+object-detection family (YOLOv5, v6, v7, v8, v9, v10, YOLO11, YOLO12, YOLO26).
+Every layer, loss, and pre/post-processing step is written entirely in
+`keras.ops`, so the exact same code runs unchanged on the **TensorFlow**,
+**JAX**, and **PyTorch** backends. It ships with best-effort utilities for
+converting the official PyTorch checkpoints into Keras `.weights.h5` files.
+
+## Supported models
+
+| Family   | Variants                     | Detection head                         |
+| -------- | ---------------------------- | -------------------------------------- |
+| YOLOv5   | `n` `s` `m` `l` `x`          | Classic anchor-based (NMS)             |
+| YOLOv6   | `n` `s` `m` `l`              | Anchor-free, DFL (NMS)                 |
+| YOLOv7   | `yolov7` `yolov7-tiny` `yolov7-x` | Classic anchor-based (NMS)        |
+| YOLOv8   | `n` `s` `m` `l` `x`          | Anchor-free, DFL (NMS)                 |
+| YOLOv9   | `t` `s` `m` `c` `e`          | Anchor-free, DFL (NMS)                 |
+| YOLOv10  | `n` `s` `m` `b` `l` `x`      | Anchor-free, DFL, **end-to-end (NMS-free)** |
+| YOLO11   | `n` `s` `m` `l` `x`          | Anchor-free, DFL (NMS)                 |
+| YOLO12   | `n` `s` `m` `l` `x`          | Anchor-free, DFL (NMS)                 |
+| YOLO26   | `n` `s` `m` `l` `x`          | Anchor-free, DFL, **end-to-end (NMS-free)** |
+
+Regardless of family, a model's forward pass returns a **list of 3 raw feature
+maps** `[P3, P4, P5]`, each of shape `(B, Hi, Wi, 4 * reg_max + nc)` in
+channels-last layout, with `reg_max = 16` and strides `(8, 16, 32)`. The
+anchor-free families (v6/v8/v9/11/12/26) decode boxes with a Distribution Focal
+Loss (DFL) regression head; the end-to-end families (v10, v26) are trained to be
+NMS-free but a standard NMS postprocessor is still available for the rest.
+
+## Installation
+
+`kyolo` needs Keras 3 plus **exactly one** backend. Install the package in
+editable mode with the backend extra you want:
+
+```bash
+# pick ONE backend
+pip install -e ".[tensorflow]"
+pip install -e ".[jax]"
+pip install -e ".[torch]"
+
+# optional extras
+pip install -e ".[viz]"      # matplotlib + pillow, for the examples
+pip install -e ".[conversion]"  # torch + ultralytics, for weight conversion
+pip install -e ".[all]"      # tensorflow + convert + viz + dev
+```
+
+Select the active backend with the `KERAS_BACKEND` environment variable before
+importing anything:
+
+```bash
+export KERAS_BACKEND=tensorflow   # or "jax" / "torch"
+```
+
+```python
+import os
+os.environ["KERAS_BACKEND"] = "tensorflow"  # must be set before `import keras`
+```
+
+## Quickstart: inference
+
+```python
+import keras
+
+from kyolo.models import yolov8n            # every variant is a factory: yolov5n, yolo11s, ...
+from kyolo.preprocessing import YOLOPreprocessor
+from kyolo.postprocessing import YOLOPostprocessor
+from kyolo.utils import visualize_detections, COCO_CLASS_NAMES
+
+# 1. Build a model (deploy=True fuses reparameterizable branches for inference).
+model = yolov8n(nc=80, input_shape=(640, 640, 3), deploy=True)
+# model.load_weights("yolov8n.weights.h5")  # a converted checkpoint (see below)
+
+# 2. Preprocess: letterbox to a square and (optionally) normalize to [0, 1].
+preprocessor = YOLOPreprocessor(image_size=640, normalize=True, letterbox=True)
+batch = preprocessor.from_files("assets/bird.png")
+# batch == {"images": (B, 640, 640, 3), "ratio": (B, 2), "pad": (B, 2)}
+
+# 3. Forward pass -> list of 3 raw feature maps [P3, P4, P5].
+raw_feats = model(batch["images"])
+
+# 4. Postprocess -> (B, max_detections, 6) = [x1, y1, x2, y2, score, class_id].
+postprocessor = YOLOPostprocessor(
+    nc=80, reg_max=16, strides=(8, 16, 32),
+    conf_threshold=0.25, iou_threshold=0.7, max_detections=300,
+)
+detections = postprocessor(raw_feats)
+
+# 5. Visualize the first image in the batch.
+image = keras.ops.convert_to_numpy(batch["images"])[0]
+dets = keras.ops.convert_to_numpy(detections)[0]
+visualize_detections(image, dets, class_names=COCO_CLASS_NAMES,
+                     save_path="assets/inference_result.png")
+```
+
+A runnable version lives in [`examples/inference.py`](examples/inference.py).
+
+## Training / fine-tuning
+
+`kyolo.training.YOLODetector` is a `keras.Model` subclass that plugs into
+`.fit()`. Datasets yield `(images, targets)` tuples where `targets` is
+`{"boxes", "labels", "mask"}` (boxes are xyxy pixels, labels are ints, mask
+marks real vs. padded boxes). `detect.detect(...)` runs the full decode + NMS
+pipeline in one call:
+
+```python
+import keras
+
+from kyolo.models import yolov8n
+from kyolo.losses import YOLODetectionLoss
+from kyolo.training import YOLODetector
+
+nc = 80
+model = yolov8n(nc=nc)
+
+# Fine-tuning: load converted weights onto the bare model BEFORE wrapping it.
+# model.load_weights("yolov8n.weights.h5")   # AGPL-3.0 converted checkpoint
+
+# Freeze the backbone so only the neck + detection head train:
+for layer in model.layers:
+    if layer.name.startswith("backbone"):
+        layer.trainable = False
+
+loss = YOLODetectionLoss(nc=nc, reg_max=16, strides=(8, 16, 32))
+detector = YOLODetector(model, loss=loss, nc=nc, reg_max=16)
+detector.compile(optimizer=keras.optimizers.Adam(1e-3))
+
+# `dataset` yields (images, {"boxes", "labels", "mask"}) tuples.
+detector.fit(dataset, epochs=1, steps_per_epoch=2)
+
+# Convenience: run the full detect -> NMS pipeline in one call.
+detections = detector.detect(images, conf=0.25, iou=0.7)
+```
+
+A runnable synthetic-data version lives in [`examples/train.py`](examples/train.py).
+
+## Weight conversion
+
+The official YOLO checkpoints are **AGPL-3.0 licensed** and are **not**
+redistributed with this project. To use pretrained weights you must convert an
+official `.pt` file yourself. Each model ships a co-located converter:
+
+```bash
+# per-model converter (co-located under kyolo/models/<name>/)
+python -m kyolo.models.yolov8.convert_yolov8_torch_to_keras \
+    --weights yolov8n.pt --output yolov8n.weights.h5 --variant n
+
+# or the unified CLI (installed as `kyolo-convert`)
+kyolo-convert --model yolov8n --weights yolov8n.pt --output yolov8n.weights.h5
+```
+
+Conversion requires the `conversion` extra (`pip install -e ".[conversion]"`,
+which pulls in `torch` and `ultralytics`). The programmatic entry point is
+`from kyolo.conversion import convert_weights`.
+
+> Conversion is **best-effort**: layer-name and tensor-layout mappings are
+> maintained by hand, so always validate a converted model's outputs against the
+> reference PyTorch implementation before trusting it.
+
+## Package layout
+
+The repo follows the [KerasFormers](https://github.com/IMvision12/KerasFormers)
+layout: a flat top-level package with one self-contained folder per model.
+
+```
+kyolo/                       # flat package (no src/)
+├── __init__.py
+├── version.py               # single source of truth for the version → releases
+├── models/
+│   ├── __init__.py          # per-variant factories (yolov8n, yolo11s, ...)
+│   ├── base.py              # shared assembly (image_input, finalize_detector)
+│   └── yolov8/              # one folder per model (v5, v6, v7, v8, v9, v10, 11, 12, 26)
+│       ├── __init__.py
+│       ├── config.py                          # scale variants
+│       ├── yolov8_model.py                     # architecture
+│       └── convert_yolov8_torch_to_keras.py    # co-located weight converter
+├── heads/                   # detection head
+├── layers/                  # conv/bn, CSP/ELAN/GELAN/attention blocks, DFL, letterbox
+├── ops/                     # anchors, box math, task-aligned assigner (pure keras.ops)
+├── losses/                  # YOLODetectionLoss
+├── preprocessing/           # YOLOPreprocessor
+├── postprocessing/          # YOLOPostprocessor + pure-ops NMS
+├── training/                # YOLODetector (keras.Model subclass)
+├── conversion/              # convert_weights, name mappings, exceptions, CLI
+└── utils/                   # COCO metadata + visualization
+
+.github/workflows/           # release.yml (auto-release) + test_code.yml (CI)
+docs/                        # one page per model
+tests/integration/           # build + processing smoke tests
+examples/                    # inference.py, train.py
+```
+
+## Releasing
+
+Releases are automated. Bump `__version__` in
+[`kyolo/version.py`](kyolo/version.py) and merge to `main`:
+[`.github/workflows/release.yml`](.github/workflows/release.yml) detects the
+change, creates the `v<version>` GitHub release, and publishes the wheel + sdist
+to PyPI (via Trusted Publishing — no API token). The package version is read
+dynamically from `kyolo.__version__`, so `version.py` is the single source of
+truth.
+
+## License
+
+- The **code** in this repository is licensed under the
+  [Apache License 2.0](LICENSE).
+- The official YOLO **weights** are licensed under
+  [AGPL-3.0](https://github.com/ultralytics/ultralytics/blob/main/LICENSE).
+  They are not shipped here; anything you convert from them inherits AGPL-3.0,
+  and using such weights subjects your project to the AGPL-3.0 requirements.

kyolo-0.1.0/README.md

@@ -0,0 +1,210 @@
+# kyolo — YOLO in pure Keras 3
+
+`kyolo` is a pure [Keras 3](https://keras.io) implementation of the YOLO
+object-detection family (YOLOv5, v6, v7, v8, v9, v10, YOLO11, YOLO12, YOLO26).
+Every layer, loss, and pre/post-processing step is written entirely in
+`keras.ops`, so the exact same code runs unchanged on the **TensorFlow**,
+**JAX**, and **PyTorch** backends. It ships with best-effort utilities for
+converting the official PyTorch checkpoints into Keras `.weights.h5` files.
+
+## Supported models
+
+| Family   | Variants                     | Detection head                         |
+| -------- | ---------------------------- | -------------------------------------- |
+| YOLOv5   | `n` `s` `m` `l` `x`          | Classic anchor-based (NMS)             |
+| YOLOv6   | `n` `s` `m` `l`              | Anchor-free, DFL (NMS)                 |
+| YOLOv7   | `yolov7` `yolov7-tiny` `yolov7-x` | Classic anchor-based (NMS)        |
+| YOLOv8   | `n` `s` `m` `l` `x`          | Anchor-free, DFL (NMS)                 |
+| YOLOv9   | `t` `s` `m` `c` `e`          | Anchor-free, DFL (NMS)                 |
+| YOLOv10  | `n` `s` `m` `b` `l` `x`      | Anchor-free, DFL, **end-to-end (NMS-free)** |
+| YOLO11   | `n` `s` `m` `l` `x`          | Anchor-free, DFL (NMS)                 |
+| YOLO12   | `n` `s` `m` `l` `x`          | Anchor-free, DFL (NMS)                 |
+| YOLO26   | `n` `s` `m` `l` `x`          | Anchor-free, DFL, **end-to-end (NMS-free)** |
+
+Regardless of family, a model's forward pass returns a **list of 3 raw feature
+maps** `[P3, P4, P5]`, each of shape `(B, Hi, Wi, 4 * reg_max + nc)` in
+channels-last layout, with `reg_max = 16` and strides `(8, 16, 32)`. The
+anchor-free families (v6/v8/v9/11/12/26) decode boxes with a Distribution Focal
+Loss (DFL) regression head; the end-to-end families (v10, v26) are trained to be
+NMS-free but a standard NMS postprocessor is still available for the rest.
+
+## Installation
+
+`kyolo` needs Keras 3 plus **exactly one** backend. Install the package in
+editable mode with the backend extra you want:
+
+```bash
+# pick ONE backend
+pip install -e ".[tensorflow]"
+pip install -e ".[jax]"
+pip install -e ".[torch]"
+
+# optional extras
+pip install -e ".[viz]"      # matplotlib + pillow, for the examples
+pip install -e ".[conversion]"  # torch + ultralytics, for weight conversion
+pip install -e ".[all]"      # tensorflow + convert + viz + dev
+```
+
+Select the active backend with the `KERAS_BACKEND` environment variable before
+importing anything:
+
+```bash
+export KERAS_BACKEND=tensorflow   # or "jax" / "torch"
+```
+
+```python
+import os
+os.environ["KERAS_BACKEND"] = "tensorflow"  # must be set before `import keras`
+```
+
+## Quickstart: inference
+
+```python
+import keras
+
+from kyolo.models import yolov8n            # every variant is a factory: yolov5n, yolo11s, ...
+from kyolo.preprocessing import YOLOPreprocessor
+from kyolo.postprocessing import YOLOPostprocessor
+from kyolo.utils import visualize_detections, COCO_CLASS_NAMES
+
+# 1. Build a model (deploy=True fuses reparameterizable branches for inference).
+model = yolov8n(nc=80, input_shape=(640, 640, 3), deploy=True)
+# model.load_weights("yolov8n.weights.h5")  # a converted checkpoint (see below)
+
+# 2. Preprocess: letterbox to a square and (optionally) normalize to [0, 1].
+preprocessor = YOLOPreprocessor(image_size=640, normalize=True, letterbox=True)
+batch = preprocessor.from_files("assets/bird.png")
+# batch == {"images": (B, 640, 640, 3), "ratio": (B, 2), "pad": (B, 2)}
+
+# 3. Forward pass -> list of 3 raw feature maps [P3, P4, P5].
+raw_feats = model(batch["images"])
+
+# 4. Postprocess -> (B, max_detections, 6) = [x1, y1, x2, y2, score, class_id].
+postprocessor = YOLOPostprocessor(
+    nc=80, reg_max=16, strides=(8, 16, 32),
+    conf_threshold=0.25, iou_threshold=0.7, max_detections=300,
+)
+detections = postprocessor(raw_feats)
+
+# 5. Visualize the first image in the batch.
+image = keras.ops.convert_to_numpy(batch["images"])[0]
+dets = keras.ops.convert_to_numpy(detections)[0]
+visualize_detections(image, dets, class_names=COCO_CLASS_NAMES,
+                     save_path="assets/inference_result.png")
+```
+
+A runnable version lives in [`examples/inference.py`](examples/inference.py).
+
+## Training / fine-tuning
+
+`kyolo.training.YOLODetector` is a `keras.Model` subclass that plugs into
+`.fit()`. Datasets yield `(images, targets)` tuples where `targets` is
+`{"boxes", "labels", "mask"}` (boxes are xyxy pixels, labels are ints, mask
+marks real vs. padded boxes). `detect.detect(...)` runs the full decode + NMS
+pipeline in one call:
+
+```python
+import keras
+
+from kyolo.models import yolov8n
+from kyolo.losses import YOLODetectionLoss
+from kyolo.training import YOLODetector
+
+nc = 80
+model = yolov8n(nc=nc)
+
+# Fine-tuning: load converted weights onto the bare model BEFORE wrapping it.
+# model.load_weights("yolov8n.weights.h5")   # AGPL-3.0 converted checkpoint
+
+# Freeze the backbone so only the neck + detection head train:
+for layer in model.layers:
+    if layer.name.startswith("backbone"):
+        layer.trainable = False
+
+loss = YOLODetectionLoss(nc=nc, reg_max=16, strides=(8, 16, 32))
+detector = YOLODetector(model, loss=loss, nc=nc, reg_max=16)
+detector.compile(optimizer=keras.optimizers.Adam(1e-3))
+
+# `dataset` yields (images, {"boxes", "labels", "mask"}) tuples.
+detector.fit(dataset, epochs=1, steps_per_epoch=2)
+
+# Convenience: run the full detect -> NMS pipeline in one call.
+detections = detector.detect(images, conf=0.25, iou=0.7)
+```
+
+A runnable synthetic-data version lives in [`examples/train.py`](examples/train.py).
+
+## Weight conversion
+
+The official YOLO checkpoints are **AGPL-3.0 licensed** and are **not**
+redistributed with this project. To use pretrained weights you must convert an
+official `.pt` file yourself. Each model ships a co-located converter:
+
+```bash
+# per-model converter (co-located under kyolo/models/<name>/)
+python -m kyolo.models.yolov8.convert_yolov8_torch_to_keras \
+    --weights yolov8n.pt --output yolov8n.weights.h5 --variant n
+
+# or the unified CLI (installed as `kyolo-convert`)
+kyolo-convert --model yolov8n --weights yolov8n.pt --output yolov8n.weights.h5
+```
+
+Conversion requires the `conversion` extra (`pip install -e ".[conversion]"`,
+which pulls in `torch` and `ultralytics`). The programmatic entry point is
+`from kyolo.conversion import convert_weights`.
+
+> Conversion is **best-effort**: layer-name and tensor-layout mappings are
+> maintained by hand, so always validate a converted model's outputs against the
+> reference PyTorch implementation before trusting it.
+
+## Package layout
+
+The repo follows the [KerasFormers](https://github.com/IMvision12/KerasFormers)
+layout: a flat top-level package with one self-contained folder per model.
+
+```
+kyolo/                       # flat package (no src/)
+├── __init__.py
+├── version.py               # single source of truth for the version → releases
+├── models/
+│   ├── __init__.py          # per-variant factories (yolov8n, yolo11s, ...)
+│   ├── base.py              # shared assembly (image_input, finalize_detector)
+│   └── yolov8/              # one folder per model (v5, v6, v7, v8, v9, v10, 11, 12, 26)
+│       ├── __init__.py
+│       ├── config.py                          # scale variants
+│       ├── yolov8_model.py                     # architecture
+│       └── convert_yolov8_torch_to_keras.py    # co-located weight converter
+├── heads/                   # detection head
+├── layers/                  # conv/bn, CSP/ELAN/GELAN/attention blocks, DFL, letterbox
+├── ops/                     # anchors, box math, task-aligned assigner (pure keras.ops)
+├── losses/                  # YOLODetectionLoss
+├── preprocessing/           # YOLOPreprocessor
+├── postprocessing/          # YOLOPostprocessor + pure-ops NMS
+├── training/                # YOLODetector (keras.Model subclass)
+├── conversion/              # convert_weights, name mappings, exceptions, CLI
+└── utils/                   # COCO metadata + visualization
+
+.github/workflows/           # release.yml (auto-release) + test_code.yml (CI)
+docs/                        # one page per model
+tests/integration/           # build + processing smoke tests
+examples/                    # inference.py, train.py
+```
+
+## Releasing
+
+Releases are automated. Bump `__version__` in
+[`kyolo/version.py`](kyolo/version.py) and merge to `main`:
+[`.github/workflows/release.yml`](.github/workflows/release.yml) detects the
+change, creates the `v<version>` GitHub release, and publishes the wheel + sdist
+to PyPI (via Trusted Publishing — no API token). The package version is read
+dynamically from `kyolo.__version__`, so `version.py` is the single source of
+truth.
+
+## License
+
+- The **code** in this repository is licensed under the
+  [Apache License 2.0](LICENSE).
+- The official YOLO **weights** are licensed under
+  [AGPL-3.0](https://github.com/ultralytics/ultralytics/blob/main/LICENSE).
+  They are not shipped here; anything you convert from them inherits AGPL-3.0,
+  and using such weights subjects your project to the AGPL-3.0 requirements.