nsharper 0.1.0__tar.gz

nsharper-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: nsharper
+Version: 0.1.0
+Summary: A lightweight computer-vision framework for building, training and benchmarking compact object detectors
+License-Expression: MIT
+Project-URL: Documentation, https://github.com/nsharper/nsharper/blob/main/docs.md
+Keywords: computer-vision,object-detection,deep-learning,benchmark
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: torch>=2.1
+Requires-Dist: torchvision>=0.16
+Requires-Dist: numpy>=1.24
+Requires-Dist: pillow>=9.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# nsharper
+
+A lightweight Python framework for building and evaluating computer-vision
+models with a deliberately simple API.
+
+```text
+Dataset → Model → Summary → Train → Test → Benchmark → Save
+```
+
+> Keep the model definition simple. Keep the workflow obvious.
+
+Full documentation lives in [`docs.md`](docs.md).
+
+## Install
+
+```bash
+pip install nsharper
+```
+
+## A complete project
+
+```python
+import nsharper as ns
+
+train = ns.Dataset("dataset/train")
+val = ns.Dataset("dataset/val")
+
+model = ns.Model([
+    ns.Conv(224, 224, 3, 16, 3, 2),
+    ns.Conv(112, 112, 16, 32, 3, 2),
+    ns.Conv(56, 56, 32, 64, 3, 2),
+    ns.Detect(28, 28, 64, 10)
+])
+
+model.summary()
+
+model.fit(train, epochs=50, batch_size=32, lr=0.001, val=val)
+
+results = model.test(val)
+results.show()
+
+model.save("supercharger.nsh")
+```
+
+## What each command answers
+
+| Command       | Question it answers                            |
+| ------------- | ---------------------------------------------- |
+| `summary()`   | What is my model, and what does it cost?       |
+| `test()`      | How well does it do on *my* dataset?           |
+| `benchmark()` | How well does it do on COCO?                   |
+
+`summary()` reports parameters, FLOPs, model size, memory and measured
+latency/FPS on every backend the machine offers, plus a Mermaid diagram of
+the graph. It needs no trained weights, so architectures can be compared
+before spending time on training.
+
+## Dataset layout
+
+```text
+dataset/
+├── images/001.jpg
+└── labels/001.yaml
+```
+
+```yaml
+cat:
+  - [0.12, 0.20, 0.43, 0.61]
+dog:
+  - [0.55, 0.31, 0.88, 0.72]
+```
+
+Boxes are normalized `[x1, y1, x2, y2]`, all coordinates between `0.0` and `1.0`.
+
+## Devices
+
+`"auto"` (default) walks CUDA → MPS → CPU and takes the first available
+backend. `"cpu"`, `"cuda"`, `"mps"` and `"gpu"` select one explicitly.
+
+```python
+model.fit(train, epochs=50, device="mps")
+ns.device()   # 'mps'
+```
+
+## Architecture errors surface immediately
+
+```python
+ns.Model([
+    ns.Conv(224, 224, 3, 16, 3, 2),
+    ns.Conv(112, 112, 64, 32, 3, 2),
+])
+```
+
+```text
+error: channel mismatch
+
+layer: Conv
+expected: 64
+received: 16
+```
+
+## COCO benchmark
+
+COCO is not bundled. Point `benchmark()` at a local copy — by argument, via
+`NSHARPER_COCO`, or by placing it in `~/.nsharper/coco`:
+
+```python
+ns.benchmark("supercharger.nsh")
+ns.benchmark(model, data="~/datasets/coco")
+```
+
+Both the nsharper layout (`images/` + `labels/`) and the official COCO
+layout (`val2017/` + `annotations/instances_val2017.json`) are read.
+
+## Examples
+
+```bash
+python examples/make_shapes.py dataset   # generate a synthetic dataset
+python examples/train.py                 # train, test and save a detector
+python examples/predict.py dataset/val/images/0000.jpg
+python examples/benchmark.py             # benchmark saved models
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

nsharper-0.1.0/README.md

@@ -0,0 +1,129 @@
+# nsharper
+
+A lightweight Python framework for building and evaluating computer-vision
+models with a deliberately simple API.
+
+```text
+Dataset → Model → Summary → Train → Test → Benchmark → Save
+```
+
+> Keep the model definition simple. Keep the workflow obvious.
+
+Full documentation lives in [`docs.md`](docs.md).
+
+## Install
+
+```bash
+pip install nsharper
+```
+
+## A complete project
+
+```python
+import nsharper as ns
+
+train = ns.Dataset("dataset/train")
+val = ns.Dataset("dataset/val")
+
+model = ns.Model([
+    ns.Conv(224, 224, 3, 16, 3, 2),
+    ns.Conv(112, 112, 16, 32, 3, 2),
+    ns.Conv(56, 56, 32, 64, 3, 2),
+    ns.Detect(28, 28, 64, 10)
+])
+
+model.summary()
+
+model.fit(train, epochs=50, batch_size=32, lr=0.001, val=val)
+
+results = model.test(val)
+results.show()
+
+model.save("supercharger.nsh")
+```
+
+## What each command answers
+
+| Command       | Question it answers                            |
+| ------------- | ---------------------------------------------- |
+| `summary()`   | What is my model, and what does it cost?       |
+| `test()`      | How well does it do on *my* dataset?           |
+| `benchmark()` | How well does it do on COCO?                   |
+
+`summary()` reports parameters, FLOPs, model size, memory and measured
+latency/FPS on every backend the machine offers, plus a Mermaid diagram of
+the graph. It needs no trained weights, so architectures can be compared
+before spending time on training.
+
+## Dataset layout
+
+```text
+dataset/
+├── images/001.jpg
+└── labels/001.yaml
+```
+
+```yaml
+cat:
+  - [0.12, 0.20, 0.43, 0.61]
+dog:
+  - [0.55, 0.31, 0.88, 0.72]
+```
+
+Boxes are normalized `[x1, y1, x2, y2]`, all coordinates between `0.0` and `1.0`.
+
+## Devices
+
+`"auto"` (default) walks CUDA → MPS → CPU and takes the first available
+backend. `"cpu"`, `"cuda"`, `"mps"` and `"gpu"` select one explicitly.
+
+```python
+model.fit(train, epochs=50, device="mps")
+ns.device()   # 'mps'
+```
+
+## Architecture errors surface immediately
+
+```python
+ns.Model([
+    ns.Conv(224, 224, 3, 16, 3, 2),
+    ns.Conv(112, 112, 64, 32, 3, 2),
+])
+```
+
+```text
+error: channel mismatch
+
+layer: Conv
+expected: 64
+received: 16
+```
+
+## COCO benchmark
+
+COCO is not bundled. Point `benchmark()` at a local copy — by argument, via
+`NSHARPER_COCO`, or by placing it in `~/.nsharper/coco`:
+
+```python
+ns.benchmark("supercharger.nsh")
+ns.benchmark(model, data="~/datasets/coco")
+```
+
+Both the nsharper layout (`images/` + `labels/`) and the official COCO
+layout (`val2017/` + `annotations/instances_val2017.json`) are read.
+
+## Examples
+
+```bash
+python examples/make_shapes.py dataset   # generate a synthetic dataset
+python examples/train.py                 # train, test and save a detector
+python examples/predict.py dataset/val/images/0000.jpg
+python examples/benchmark.py             # benchmark saved models
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

nsharper-0.1.0/nsharper/__init__.py

@@ -0,0 +1,67 @@
+"""nsharper — a lightweight computer-vision framework.
+
+    Dataset → Model → Summary → Train → Test → Benchmark → Save
+
+Keep the model definition simple. Keep the workflow obvious.
+
+>>> import nsharper as ns
+>>>
+>>> train = ns.Dataset("dataset/train")
+>>> model = ns.Model([
+...     ns.Conv(224, 224, 3, 16, 3, 2),
+...     ns.Conv(112, 112, 16, 32, 3, 2),
+...     ns.Conv(56, 56, 32, 64, 3, 2),
+...     ns.Detect(28, 28, 64, 10),
+... ])
+>>> model.summary()
+>>> model.fit(train, epochs=50)
+>>> model.save("supercharger.nsh")
+"""
+
+from __future__ import annotations
+
+from .coco import benchmark
+from .dataset import Box, Dataset, Sample
+from .backends import device
+from .errors import (
+    ArchitectureError,
+    BenchmarkError,
+    DatasetError,
+    DeviceError,
+    ModelError,
+    NsharperError,
+)
+from .layers import Conv, Detect, Layer
+from .model import Model
+from .results import Detection, Prediction, TestResults
+from .serialization import load
+from .summary import Summary
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # core API
+    "Dataset",
+    "Model",
+    "Conv",
+    "Detect",
+    "load",
+    "benchmark",
+    "device",
+    # supporting types
+    "Box",
+    "Sample",
+    "Layer",
+    "Summary",
+    "TestResults",
+    "Prediction",
+    "Detection",
+    # errors
+    "NsharperError",
+    "ArchitectureError",
+    "DatasetError",
+    "DeviceError",
+    "ModelError",
+    "BenchmarkError",
+    "__version__",
+]

nsharper-0.1.0/nsharper/backends.py

@@ -0,0 +1,113 @@
+"""Compute-backend selection.
+
+The public entry point is ``ns.device()``; this module keeps a separate name
+so importing it can never shadow that function.
+
+nsharper accepts the identifiers documented in the "Devices" section:
+``auto``, ``cpu``, ``cuda``, ``mps`` and ``gpu``.  ``auto`` walks the
+priority chain CUDA -> MPS -> GPU -> CPU and picks the first backend the
+installed runtime actually offers.
+"""
+
+from __future__ import annotations
+
+import torch
+
+from .errors import DeviceError
+
+__all__ = ["device", "resolve", "available", "is_available"]
+
+#: Priority chain used by ``device="auto"``.
+PRIORITY = ("cuda", "mps", "cpu")
+
+ALIASES = {
+    None: "auto",
+    "auto": "auto",
+    "cpu": "cpu",
+    "cuda": "cuda",
+    "gpu": "gpu",
+    "mps": "mps",
+}
+
+
+def is_available(name: str) -> bool:
+    """Return whether a concrete backend can be used right now."""
+    if name == "cpu":
+        return True
+    if name == "cuda":
+        return torch.cuda.is_available()
+    if name == "mps":
+        return torch.backends.mps.is_available()
+    return False
+
+
+def available() -> list[str]:
+    """Every usable backend, best first."""
+    return [name for name in PRIORITY if is_available(name)]
+
+
+def resolve(spec: str | torch.device | None = "auto") -> torch.device:
+    """Turn a device identifier into a concrete :class:`torch.device`."""
+    if isinstance(spec, torch.device):
+        return spec
+
+    if isinstance(spec, str):
+        key = spec.strip().lower()
+        # Allow indexed devices such as "cuda:1" to pass through untouched.
+        if ":" in key:
+            base = key.split(":", 1)[0]
+            if base not in ALIASES or base in ("auto", "gpu"):
+                raise DeviceError(_unknown(spec))
+            if not is_available(base):
+                raise DeviceError(_unavailable(base))
+            return torch.device(key)
+    elif spec is None:
+        key = "auto"
+    else:
+        raise DeviceError(_unknown(spec))
+
+    if key not in ALIASES:
+        raise DeviceError(_unknown(spec))
+
+    if key == "auto":
+        return torch.device(available()[0])
+
+    if key == "gpu":
+        for name in ("cuda", "mps"):
+            if is_available(name):
+                return torch.device(name)
+        raise DeviceError(
+            "error: no gpu available\n\n"
+            "requested: gpu\n"
+            f"available: {', '.join(available())}"
+        )
+
+    if not is_available(key):
+        raise DeviceError(_unavailable(key))
+    return torch.device(key)
+
+
+def _unknown(spec: object) -> str:
+    return (
+        "error: unknown device\n\n"
+        f"received: {spec!r}\n"
+        "expected: auto, cpu, cuda, mps or gpu"
+    )
+
+
+def _unavailable(name: str) -> str:
+    return (
+        "error: device unavailable\n\n"
+        f"requested: {name}\n"
+        f"available: {', '.join(available())}"
+    )
+
+
+def device(spec: str | None = "auto") -> str:
+    """Report the execution backend nsharper would use.
+
+    >>> import nsharper as ns
+    >>> ns.device()
+    'mps'
+    """
+    return str(resolve(spec))