neurovisionx 0.1.0__tar.gz

neurovisionx-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Srikanth Sridhar
+
+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.

neurovisionx-0.1.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: neurovisionx
+Version: 0.1.0
+Summary: Unified CNN library for image classification and anchor-free object detection with Adaptive Feature Pyramid Attention (AFPA).
+Author-email: Srikanth Sridhar <srisrikanthtvs@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/sricodings/neurovisionx
+Project-URL: Documentation, https://github.com/sricodings/neurovisionx#readme
+Project-URL: Issues, https://github.com/sricodings/neurovisionx/issues
+Keywords: deep learning,computer vision,object detection,image classification,pytorch,cnn,attention
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=1.13
+Requires-Dist: torchvision>=0.14
+Requires-Dist: pillow>=9.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# NeuroVisionX
+
+**A unified PyTorch library for image classification and anchor-free object detection**,
+built around a single shared backbone and a custom attention module: **AFPA (Adaptive
+Feature Pyramid Attention)**.
+
+[![PyPI version](https://img.shields.io/pypi/v/neurovisionx.svg)](https://pypi.org/project/neurovisionx/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/)
+
+---
+
+## Why NeuroVisionX
+
+Most beginner-friendly libraries make you choose: a simple classifier *or* a heavy,
+hard-to-configure detector (YOLO/SSD-style with anchor boxes and many hyperparameters).
+
+NeuroVisionX gives you **both, from one backbone**:
+
+- **One backbone, two heads.** Train a classifier, a detector, or both, without
+  duplicating feature extraction code.
+- **AFPA attention block.** Lightweight channel+spatial attention with a learnable
+  residual gate, so it starts as identity and "switches on" only when useful —
+  more stable than dropping raw attention into a network from scratch.
+- **Anchor-free detection head.** Predicts object centers, sizes, and sub-pixel
+  offsets directly (CenterNet/FCOS-style) — no anchor box tuning.
+- **One `Trainer` class** for both tasks, with sensible defaults.
+- **Minimal dependencies**: `torch`, `torchvision`, `pillow`. Nothing exotic.
+
+## Installation
+
+```bash
+pip install neurovisionx
+```
+
+For local development:
+
+```bash
+git clone https://github.com/sricodings/neurovisionx.git
+cd neurovisionx
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+### Classification
+
+```python
+import neurovisionx as nv
+from torch.utils.data import DataLoader
+
+train_ds = nv.ImageFolderDataset("data/train", image_size=224)
+train_loader = DataLoader(train_ds, batch_size=32, shuffle=True)
+
+model = nv.NeuroVisionXNet(num_classes=len(train_ds.classes), mode="classify")
+trainer = nv.Trainer(model, train_loader, task="classify")
+trainer.fit(epochs=20)
+```
+
+### Object detection
+
+```python
+import neurovisionx as nv
+from torch.utils.data import DataLoader
+
+train_ds = nv.DetectionDataset("data/images", "data/annotations.json", image_size=512)
+train_loader = DataLoader(train_ds, batch_size=8, shuffle=True,
+                           collate_fn=nv.dataset.detection_collate_fn)
+
+model = nv.NeuroVisionXNet(num_classes=5, mode="detect")
+trainer = nv.Trainer(model, train_loader, task="detect")
+trainer.fit(epochs=30)
+
+detections = model.detect(image_tensor, score_thresh=0.4)
+```
+
+Annotation format (`annotations.json`) — simple COCO-lite JSON:
+
+```json
+[
+  {"image": "img1.jpg", "boxes": [[34, 12, 200, 180]], "labels": [0]},
+  {"image": "img2.jpg", "boxes": [[10, 10, 50, 50], [60, 60, 120, 140]], "labels": [2, 4]}
+]
+```
+
+## Architecture overview
+
+```
+Input image
+    │
+    ▼
+ Stem conv
+    │
+    ▼
+ Stage 1 (downsample + AFPA) ─────────────┐
+    │                                     │
+    ▼                                     │
+ Stage 2 (downsample + AFPA)  -> C3       │  multi-scale
+    │                                     │  feature maps
+    ▼                                     │
+ Stage 3 (downsample + AFPA)  -> C4 ──┐   │
+    │                                 │   │
+    ▼                                 │   │
+ Stage 4 (downsample + AFPA)  -> C5   │   │
+    │                                 │   │
+    ├──> Classifier head (GAP + FC)   │   │
+    │                                 ▼   │
+    └──> 1x1 conv + upsample ──> fuse with C4
+                                       │
+                                       ▼
+                            Anchor-free detection head
+                          (heatmap, size, offset maps)
+```
+
+## Repository layout
+
+```
+neurovisionx/
+├── neurovisionx/
+│   ├── __init__.py        # public API
+│   ├── layers.py           # ConvBNAct, AFPABlock (the novel attention module)
+│   ├── backbone.py         # multi-stage CNN backbone
+│   ├── detection_head.py   # anchor-free detection head
+│   ├── model.py             # NeuroVisionXNet (combines backbone + heads)
+│   ├── dataset.py           # ImageFolderDataset, DetectionDataset
+│   ├── trainer.py           # Trainer (training loop, losses)
+│   └── utils.py             # IoU, NMS, heatmap decoding, visualization
+├── examples/
+│   ├── train_classifier.py
+│   └── train_detector.py
+├── tests/
+├── docs/
+│   └── PUBLISHING_GUIDE.md
+├── pyproject.toml
+├── LICENSE
+└── README.md
+```
+
+## Roadmap (suggested, fill in as you build)
+
+- [ ] Pretrained backbone weights (ImageNet-style pretraining)
+- [ ] ONNX export for deployment
+- [ ] Mixed-precision training support
+- [ ] Data augmentation pipeline (mosaic, mixup, random crop)
+- [ ] Benchmark results vs ResNet/YOLO baselines on COCO subset
+- [ ] Sphinx-generated documentation site
+
+## Contributing
+
+Pull requests are welcome. Please open an issue first to discuss major changes.
+Run `pytest` and `black .` before submitting.
+
+## Citing
+
+If you use NeuroVisionX in research, please cite:
+
+```bibtex
+@software{neurovisionx2026,
+  author = {YOUR NAME},
+  title = {NeuroVisionX: Unified Classification and Anchor-Free Detection with Adaptive Feature Pyramid Attention},
+  year = {2026},
+  url = {https://github.com/YOUR_USERNAME/neurovisionx}
+}
+```
+
+## License
+
+MIT License — see [LICENSE](LICENSE).

neurovisionx-0.1.0/README.md

@@ -0,0 +1,168 @@
+# NeuroVisionX
+
+**A unified PyTorch library for image classification and anchor-free object detection**,
+built around a single shared backbone and a custom attention module: **AFPA (Adaptive
+Feature Pyramid Attention)**.
+
+[![PyPI version](https://img.shields.io/pypi/v/neurovisionx.svg)](https://pypi.org/project/neurovisionx/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/)
+
+---
+
+## Why NeuroVisionX
+
+Most beginner-friendly libraries make you choose: a simple classifier *or* a heavy,
+hard-to-configure detector (YOLO/SSD-style with anchor boxes and many hyperparameters).
+
+NeuroVisionX gives you **both, from one backbone**:
+
+- **One backbone, two heads.** Train a classifier, a detector, or both, without
+  duplicating feature extraction code.
+- **AFPA attention block.** Lightweight channel+spatial attention with a learnable
+  residual gate, so it starts as identity and "switches on" only when useful —
+  more stable than dropping raw attention into a network from scratch.
+- **Anchor-free detection head.** Predicts object centers, sizes, and sub-pixel
+  offsets directly (CenterNet/FCOS-style) — no anchor box tuning.
+- **One `Trainer` class** for both tasks, with sensible defaults.
+- **Minimal dependencies**: `torch`, `torchvision`, `pillow`. Nothing exotic.
+
+## Installation
+
+```bash
+pip install neurovisionx
+```
+
+For local development:
+
+```bash
+git clone https://github.com/sricodings/neurovisionx.git
+cd neurovisionx
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+### Classification
+
+```python
+import neurovisionx as nv
+from torch.utils.data import DataLoader
+
+train_ds = nv.ImageFolderDataset("data/train", image_size=224)
+train_loader = DataLoader(train_ds, batch_size=32, shuffle=True)
+
+model = nv.NeuroVisionXNet(num_classes=len(train_ds.classes), mode="classify")
+trainer = nv.Trainer(model, train_loader, task="classify")
+trainer.fit(epochs=20)
+```
+
+### Object detection
+
+```python
+import neurovisionx as nv
+from torch.utils.data import DataLoader
+
+train_ds = nv.DetectionDataset("data/images", "data/annotations.json", image_size=512)
+train_loader = DataLoader(train_ds, batch_size=8, shuffle=True,
+                           collate_fn=nv.dataset.detection_collate_fn)
+
+model = nv.NeuroVisionXNet(num_classes=5, mode="detect")
+trainer = nv.Trainer(model, train_loader, task="detect")
+trainer.fit(epochs=30)
+
+detections = model.detect(image_tensor, score_thresh=0.4)
+```
+
+Annotation format (`annotations.json`) — simple COCO-lite JSON:
+
+```json
+[
+  {"image": "img1.jpg", "boxes": [[34, 12, 200, 180]], "labels": [0]},
+  {"image": "img2.jpg", "boxes": [[10, 10, 50, 50], [60, 60, 120, 140]], "labels": [2, 4]}
+]
+```
+
+## Architecture overview
+
+```
+Input image
+    │
+    ▼
+ Stem conv
+    │
+    ▼
+ Stage 1 (downsample + AFPA) ─────────────┐
+    │                                     │
+    ▼                                     │
+ Stage 2 (downsample + AFPA)  -> C3       │  multi-scale
+    │                                     │  feature maps
+    ▼                                     │
+ Stage 3 (downsample + AFPA)  -> C4 ──┐   │
+    │                                 │   │
+    ▼                                 │   │
+ Stage 4 (downsample + AFPA)  -> C5   │   │
+    │                                 │   │
+    ├──> Classifier head (GAP + FC)   │   │
+    │                                 ▼   │
+    └──> 1x1 conv + upsample ──> fuse with C4
+                                       │
+                                       ▼
+                            Anchor-free detection head
+                          (heatmap, size, offset maps)
+```
+
+## Repository layout
+
+```
+neurovisionx/
+├── neurovisionx/
+│   ├── __init__.py        # public API
+│   ├── layers.py           # ConvBNAct, AFPABlock (the novel attention module)
+│   ├── backbone.py         # multi-stage CNN backbone
+│   ├── detection_head.py   # anchor-free detection head
+│   ├── model.py             # NeuroVisionXNet (combines backbone + heads)
+│   ├── dataset.py           # ImageFolderDataset, DetectionDataset
+│   ├── trainer.py           # Trainer (training loop, losses)
+│   └── utils.py             # IoU, NMS, heatmap decoding, visualization
+├── examples/
+│   ├── train_classifier.py
+│   └── train_detector.py
+├── tests/
+├── docs/
+│   └── PUBLISHING_GUIDE.md
+├── pyproject.toml
+├── LICENSE
+└── README.md
+```
+
+## Roadmap (suggested, fill in as you build)
+
+- [ ] Pretrained backbone weights (ImageNet-style pretraining)
+- [ ] ONNX export for deployment
+- [ ] Mixed-precision training support
+- [ ] Data augmentation pipeline (mosaic, mixup, random crop)
+- [ ] Benchmark results vs ResNet/YOLO baselines on COCO subset
+- [ ] Sphinx-generated documentation site
+
+## Contributing
+
+Pull requests are welcome. Please open an issue first to discuss major changes.
+Run `pytest` and `black .` before submitting.
+
+## Citing
+
+If you use NeuroVisionX in research, please cite:
+
+```bibtex
+@software{neurovisionx2026,
+  author = {YOUR NAME},
+  title = {NeuroVisionX: Unified Classification and Anchor-Free Detection with Adaptive Feature Pyramid Attention},
+  year = {2026},
+  url = {https://github.com/YOUR_USERNAME/neurovisionx}
+}
+```
+
+## License
+
+MIT License — see [LICENSE](LICENSE).

neurovisionx-0.1.0/neurovisionx/__init__.py

@@ -0,0 +1,42 @@
+"""
+NeuroVisionX
+===========
+A unified deep-learning library for image classification AND object detection,
+built around a single shared backbone with a novel attention module called
+AFPA (Adaptive Feature Pyramid Attention).
+
+Why it's different from "just another CNN wrapper":
+- One backbone, two heads (classification + detection) trained jointly or separately.
+- AFPA blocks fuse multi-scale features with learned channel+spatial gating,
+  cheaper than full transformer attention but more expressive than plain FPN.
+- Anchor-free detection head (center + size regression) -> simpler, fewer
+  hyperparameters than anchor-based YOLO/SSD style heads.
+- Single training loop (Trainer) handles both tasks via a configurable loss mix.
+
+Quick start
+-----------
+    import neurovisionx as nv
+
+    model = nv.NeuroVisionXNet(num_classes=10, mode="both")
+    trainer = nv.Trainer(model, train_loader, val_loader)
+    trainer.fit(epochs=20)
+
+    detections = model.detect(image_tensor)
+"""
+
+from .layers import AFPABlock, ConvBNAct
+from .backbone import NeuroVisionXBackbone
+from .detection_head import DetectionHead
+from .model import NeuroVisionXNet
+from .dataset import ImageFolderDataset, DetectionDataset
+from .trainer import Trainer
+from .utils import nms, iou, visualize_detections
+
+__version__ = "0.1.0"
+__all__ = [
+    "AFPABlock", "ConvBNAct",
+    "NeuroVisionXBackbone", "DetectionHead", "NeuroVisionXNet",
+    "ImageFolderDataset", "DetectionDataset",
+    "Trainer",
+    "nms", "iou", "visualize_detections",
+]

neurovisionx-0.1.0/neurovisionx/backbone.py

@@ -0,0 +1,42 @@
+"""
+NeuroVisionBackbone: a multi-stage CNN backbone with AFPA attention inserted
+after every downsampling stage. Returns a list of multi-scale feature maps
+(C3, C4, C5) so the same backbone can feed both a classification head and a
+detection head (feature pyramid style).
+"""
+
+import torch
+import torch.nn as nn
+from .layers import ConvBNAct, AFPABlock
+
+
+class Stage(nn.Module):
+    def __init__(self, in_ch, out_ch, num_blocks=2, stride=2):
+        super().__init__()
+        layers = [ConvBNAct(in_ch, out_ch, stride=stride)]
+        for _ in range(num_blocks - 1):
+            layers.append(ConvBNAct(out_ch, out_ch, stride=1))
+        layers.append(AFPABlock(out_ch))
+        self.block = nn.Sequential(*layers)
+
+    def forward(self, x):
+        return self.block(x)
+
+
+class NeuroVisionBackbone(nn.Module):
+    def __init__(self, in_channels=3, width=(32, 64, 128, 256, 512), depth=(1, 2, 2, 3, 3)):
+        super().__init__()
+        self.stem = ConvBNAct(in_channels, width[0], kernel_size=3, stride=1)
+        self.stage1 = Stage(width[0], width[1], num_blocks=depth[1], stride=2)
+        self.stage2 = Stage(width[1], width[2], num_blocks=depth[2], stride=2)  # C3
+        self.stage3 = Stage(width[2], width[3], num_blocks=depth[3], stride=2)  # C4
+        self.stage4 = Stage(width[3], width[4], num_blocks=depth[4], stride=2)  # C5
+        self.out_channels = {"C3": width[2], "C4": width[3], "C5": width[4]}
+
+    def forward(self, x):
+        x = self.stem(x)
+        x = self.stage1(x)
+        c3 = self.stage2(x)
+        c4 = self.stage3(c3)
+        c5 = self.stage4(c4)
+        return {"C3": c3, "C4": c4, "C5": c5}

neurovisionx-0.1.0/neurovisionx/dataset.py

@@ -0,0 +1,87 @@
+"""
+Lightweight dataset classes. No heavy dependency beyond torch + PIL, so the
+library stays easy to install and doesn't force a specific data format.
+"""
+
+import os
+import json
+import torch
+from torch.utils.data import Dataset
+from PIL import Image
+import torchvision.transforms as T
+
+
+class ImageFolderDataset(Dataset):
+    """Expects: root/class_name/image.jpg layout."""
+
+    def __init__(self, root, image_size=224, transform=None):
+        self.root = root
+        self.classes = sorted(
+            d for d in os.listdir(root) if os.path.isdir(os.path.join(root, d))
+        )
+        self.class_to_idx = {c: i for i, c in enumerate(self.classes)}
+        self.samples = []
+        for c in self.classes:
+            class_dir = os.path.join(root, c)
+            for fname in os.listdir(class_dir):
+                if fname.lower().endswith((".jpg", ".jpeg", ".png")):
+                    self.samples.append((os.path.join(class_dir, fname), self.class_to_idx[c]))
+
+        self.transform = transform or T.Compose([
+            T.Resize((image_size, image_size)),
+            T.ToTensor(),
+            T.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]),
+        ])
+
+    def __len__(self):
+        return len(self.samples)
+
+    def __getitem__(self, idx):
+        path, label = self.samples[idx]
+        img = Image.open(path).convert("RGB")
+        return self.transform(img), label
+
+
+class DetectionDataset(Dataset):
+    """Expects a COCO-lite JSON annotation file:
+    [
+      {"image": "img1.jpg", "boxes": [[x1,y1,x2,y2], ...], "labels": [0, 2, ...]},
+      ...
+    ]
+    """
+
+    def __init__(self, root, annotation_file, image_size=512, transform=None):
+        self.root = root
+        with open(annotation_file) as f:
+            self.records = json.load(f)
+        self.image_size = image_size
+        self.transform = transform or T.Compose([
+            T.Resize((image_size, image_size)),
+            T.ToTensor(),
+            T.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]),
+        ])
+
+    def __len__(self):
+        return len(self.records)
+
+    def __getitem__(self, idx):
+        rec = self.records[idx]
+        img = Image.open(os.path.join(self.root, rec["image"])).convert("RGB")
+        orig_w, orig_h = img.size
+        scale_x = self.image_size / orig_w
+        scale_y = self.image_size / orig_h
+
+        boxes = torch.tensor(rec["boxes"], dtype=torch.float32)
+        if len(boxes) > 0:
+            boxes[:, [0, 2]] *= scale_x
+            boxes[:, [1, 3]] *= scale_y
+        labels = torch.tensor(rec["labels"], dtype=torch.long)
+
+        img = self.transform(img)
+        return img, {"boxes": boxes, "labels": labels}
+
+
+def detection_collate_fn(batch):
+    images = torch.stack([b[0] for b in batch])
+    targets = [b[1] for b in batch]
+    return images, targets

neurovisionx-0.1.0/neurovisionx/detection_head.py

@@ -0,0 +1,34 @@
+"""
+Anchor-free detection head, in the spirit of CenterNet/FCOS but simplified.
+For each pyramid level it predicts, per spatial cell:
+  - heatmap: probability an object center lies here (per class)
+  - size: (w, h) of the object, regressed directly
+  - offset: sub-pixel (dx, dy) correction within the cell
+
+This avoids hand-tuned anchor boxes entirely, which is one of the biggest
+sources of friction/hyperparameter pain in classic detectors.
+"""
+
+import torch
+import torch.nn as nn
+from .layers import ConvBNAct
+
+
+class DetectionHead(nn.Module):
+    def __init__(self, in_channels, num_classes):
+        super().__init__()
+        self.num_classes = num_classes
+        self.shared = nn.Sequential(
+            ConvBNAct(in_channels, in_channels, kernel_size=3),
+            ConvBNAct(in_channels, in_channels, kernel_size=3),
+        )
+        self.heatmap = nn.Conv2d(in_channels, num_classes, kernel_size=1)
+        self.size = nn.Conv2d(in_channels, 2, kernel_size=1)
+        self.offset = nn.Conv2d(in_channels, 2, kernel_size=1)
+
+    def forward(self, feat):
+        x = self.shared(feat)
+        heatmap = torch.sigmoid(self.heatmap(x))
+        size = self.size(x)
+        offset = torch.tanh(self.offset(x))
+        return {"heatmap": heatmap, "size": size, "offset": offset}

neurovisionx-0.1.0/neurovisionx/layers.py

@@ -0,0 +1,87 @@
+"""
+Core building blocks for NeuroVisionX.
+
+AFPABlock (Adaptive Feature Pyramid Attention) is the signature module of
+this library. It combines:
+  1. Channel attention (squeeze-excite style) to weight "what" matters.
+  2. Spatial attention (lightweight, single-conv) to weight "where" matters.
+  3. A learnable scalar gate that blends the attended features back with the
+     original input (residual gating), so the block can fall back to an
+     identity mapping early in training and only "turn on" attention once it
+     is useful. This stabilizes training on small/medium datasets compared to
+     dropping raw attention blocks into a network from scratch.
+"""
+
+import torch
+import torch.nn as nn
+
+
+class ConvBNAct(nn.Module):
+    """Conv -> BatchNorm -> Activation, the basic unit reused everywhere."""
+
+    def __init__(self, in_ch, out_ch, kernel_size=3, stride=1, padding=None, act=True):
+        super().__init__()
+        if padding is None:
+            padding = kernel_size // 2
+        self.conv = nn.Conv2d(in_ch, out_ch, kernel_size, stride, padding, bias=False)
+        self.bn = nn.BatchNorm2d(out_ch)
+        self.act = nn.SiLU(inplace=True) if act else nn.Identity()
+
+    def forward(self, x):
+        return self.act(self.bn(self.conv(x)))
+
+
+class ChannelAttention(nn.Module):
+    def __init__(self, channels, reduction=8):
+        super().__init__()
+        hidden = max(channels // reduction, 4)
+        self.pool = nn.AdaptiveAvgPool2d(1)
+        self.fc = nn.Sequential(
+            nn.Linear(channels, hidden),
+            nn.SiLU(inplace=True),
+            nn.Linear(hidden, channels),
+            nn.Sigmoid(),
+        )
+
+    def forward(self, x):
+        b, c, _, _ = x.shape
+        w = self.pool(x).view(b, c)
+        w = self.fc(w).view(b, c, 1, 1)
+        return x * w
+
+
+class SpatialAttention(nn.Module):
+    def __init__(self, kernel_size=7):
+        super().__init__()
+        self.conv = nn.Conv2d(2, 1, kernel_size, padding=kernel_size // 2, bias=False)
+        self.sigmoid = nn.Sigmoid()
+
+    def forward(self, x):
+        avg_out = torch.mean(x, dim=1, keepdim=True)
+        max_out, _ = torch.max(x, dim=1, keepdim=True)
+        w = self.sigmoid(self.conv(torch.cat([avg_out, max_out], dim=1)))
+        return x * w
+
+
+class AFPABlock(nn.Module):
+    """Adaptive Feature Pyramid Attention block.
+
+    Args:
+        channels: number of input/output channels (kept equal for residual gating).
+        reduction: channel reduction ratio for the channel-attention branch.
+    """
+
+    def __init__(self, channels, reduction=8):
+        super().__init__()
+        self.channel_att = ChannelAttention(channels, reduction)
+        self.spatial_att = SpatialAttention()
+        self.refine = ConvBNAct(channels, channels, kernel_size=3)
+        # learnable gate, starts near 0 -> behaves like identity at init
+        self.gate = nn.Parameter(torch.tensor(0.0))
+
+    def forward(self, x):
+        attended = self.channel_att(x)
+        attended = self.spatial_att(attended)
+        attended = self.refine(attended)
+        g = torch.sigmoid(self.gate)
+        return x + g * (attended - x)

neurovisionx-0.1.0/neurovisionx/model.py

@@ -0,0 +1,58 @@
+"""
+NeuroVisionNet: the user-facing model class.
+
+mode="classify"  -> only classification head is active
+mode="detect"    -> only detection head is active
+mode="both"      -> both heads are computed every forward pass (multi-task)
+"""
+
+import torch
+import torch.nn as nn
+from .backbone import NeuroVisionBackbone
+from .detection_head import DetectionHead
+from .utils import decode_heatmap
+
+
+class NeuroVisionNet(nn.Module):
+    def __init__(self, num_classes, mode="both", in_channels=3):
+        super().__init__()
+        assert mode in ("classify", "detect", "both")
+        self.mode = mode
+        self.num_classes = num_classes
+        self.backbone = NeuroVisionBackbone(in_channels=in_channels)
+
+        c5 = self.backbone.out_channels["C5"]
+        c4 = self.backbone.out_channels["C4"]
+
+        if mode in ("classify", "both"):
+            self.classifier = nn.Sequential(
+                nn.AdaptiveAvgPool2d(1),
+                nn.Flatten(),
+                nn.Linear(c5, num_classes),
+            )
+        if mode in ("detect", "both"):
+            self.det_head = DetectionHead(c4, num_classes)
+            # project C5 down and upsample to fuse with C4 for slightly richer features
+            self.fuse = nn.Conv2d(c5, c4, kernel_size=1)
+
+    def forward(self, x):
+        feats = self.backbone(x)
+        out = {}
+        if self.mode in ("classify", "both"):
+            out["class_logits"] = self.classifier(feats["C5"])
+        if self.mode in ("detect", "both"):
+            up = nn.functional.interpolate(
+                self.fuse(feats["C5"]), size=feats["C4"].shape[-2:], mode="nearest"
+            )
+            fused = feats["C4"] + up
+            out["detections"] = self.det_head(fused)
+        return out
+
+    @torch.no_grad()
+    def detect(self, image_tensor, score_thresh=0.3, max_dets=100):
+        """Convenience inference method. image_tensor: (1, C, H, W) normalized."""
+        self.eval()
+        out = self.forward(image_tensor)
+        if "detections" not in out:
+            raise RuntimeError("Model was not built with a detection head (mode='classify').")
+        return decode_heatmap(out["detections"], image_tensor.shape[-2:], score_thresh, max_dets)

neurovisionx-0.1.0/neurovisionx/trainer.py

@@ -0,0 +1,100 @@
+"""
+Trainer: a single class that handles training for classify / detect / both
+modes, including a focal-loss-style heatmap loss for detection, mixed with
+classification cross-entropy when mode="both" is used jointly with a labeled
+classification dataset (advanced use). For most users, train classification
+and detection separately with two Trainer instances on two datasets.
+"""
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+
+def focal_heatmap_loss(pred, target, alpha=2, beta=4):
+    pos_mask = (target == 1).float()
+    neg_mask = (target < 1).float()
+    pos_loss = -((1 - pred) ** alpha) * torch.log(pred.clamp(min=1e-6)) * pos_mask
+    neg_loss = -((1 - target) ** beta) * (pred ** alpha) * torch.log((1 - pred).clamp(min=1e-6)) * neg_mask
+    num_pos = pos_mask.sum().clamp(min=1)
+    return (pos_loss.sum() + neg_loss.sum()) / num_pos
+
+
+def build_heatmap_target(targets, heatmap_shape, image_size, num_classes, device):
+    """Builds a Gaussian heatmap target tensor from box annotations (simplified)."""
+    b, _, h, w = heatmap_shape
+    target = torch.zeros(b, num_classes, h, w, device=device)
+    stride_y = image_size[0] / h
+    stride_x = image_size[1] / w
+    for i, t in enumerate(targets):
+        boxes, labels = t["boxes"], t["labels"]
+        for box, label in zip(boxes, labels):
+            x1, y1, x2, y2 = box.tolist()
+            cx, cy = (x1 + x2) / 2 / stride_x, (y1 + y2) / 2 / stride_y
+            xi, yi = int(cx), int(cy)
+            if 0 <= xi < w and 0 <= yi < h:
+                target[i, int(label), yi, xi] = 1.0
+    return target
+
+
+class Trainer:
+    def __init__(self, model, train_loader, val_loader=None, lr=1e-3,
+                 device=None, task="classify"):
+        """
+        task: "classify" or "detect" — which loss to compute on this loader.
+        """
+        self.model = model
+        self.train_loader = train_loader
+        self.val_loader = val_loader
+        self.task = task
+        self.device = device or ("cuda" if torch.cuda.is_available() else "cpu")
+        self.model.to(self.device)
+        self.optimizer = torch.optim.AdamW(self.model.parameters(), lr=lr)
+
+    def fit(self, epochs=10, log_every=50):
+        for epoch in range(1, epochs + 1):
+            self.model.train()
+            running_loss = 0.0
+            for step, batch in enumerate(self.train_loader):
+                loss = self._step(batch)
+                self.optimizer.zero_grad()
+                loss.backward()
+                self.optimizer.step()
+                running_loss += loss.item()
+                if step % log_every == 0:
+                    print(f"[epoch {epoch}] step {step} loss {loss.item():.4f}")
+
+            avg = running_loss / max(1, len(self.train_loader))
+            msg = f"Epoch {epoch}/{epochs} - avg train loss: {avg:.4f}"
+            if self.val_loader is not None:
+                val_loss = self.evaluate()
+                msg += f" - val loss: {val_loss:.4f}"
+            print(msg)
+
+    def _step(self, batch):
+        if self.task == "classify":
+            images, labels = batch
+            images, labels = images.to(self.device), labels.to(self.device)
+            out = self.model(images)
+            return F.cross_entropy(out["class_logits"], labels)
+
+        elif self.task == "detect":
+            images, targets = batch
+            images = images.to(self.device)
+            targets = [{k: v.to(self.device) for k, v in t.items()} for t in targets]
+            out = self.model(images)["detections"]
+            heatmap_target = build_heatmap_target(
+                targets, out["heatmap"].shape, images.shape[-2:],
+                self.model.num_classes, self.device,
+            )
+            return focal_heatmap_loss(out["heatmap"], heatmap_target)
+
+        raise ValueError(f"Unknown task: {self.task}")
+
+    @torch.no_grad()
+    def evaluate(self):
+        self.model.eval()
+        total = 0.0
+        for batch in self.val_loader:
+            total += self._step(batch).item()
+        return total / max(1, len(self.val_loader))

neurovisionx-0.1.0/neurovisionx/utils.py

@@ -0,0 +1,86 @@
+"""Shared utility functions: geometry, decoding, visualization."""
+
+import torch
+
+
+def iou(box1, box2):
+    """box format: [x1, y1, x2, y2]. Returns scalar IoU."""
+    x1 = max(box1[0], box2[0])
+    y1 = max(box1[1], box2[1])
+    x2 = min(box1[2], box2[2])
+    y2 = min(box1[3], box2[3])
+    inter = max(0, x2 - x1) * max(0, y2 - y1)
+    area1 = (box1[2] - box1[0]) * (box1[3] - box1[1])
+    area2 = (box2[2] - box2[0]) * (box2[3] - box2[1])
+    union = area1 + area2 - inter
+    return inter / union if union > 0 else 0.0
+
+
+def nms(boxes, scores, iou_thresh=0.5):
+    """Standard greedy NMS. boxes: list/tensor of [x1,y1,x2,y2], scores: list/tensor."""
+    if len(boxes) == 0:
+        return []
+    boxes = torch.as_tensor(boxes, dtype=torch.float32)
+    scores = torch.as_tensor(scores, dtype=torch.float32)
+    order = scores.argsort(descending=True)
+    keep = []
+    while order.numel() > 0:
+        i = order[0].item()
+        keep.append(i)
+        if order.numel() == 1:
+            break
+        rest = order[1:]
+        ious = torch.tensor([iou(boxes[i].tolist(), boxes[j].tolist()) for j in rest])
+        order = rest[ious <= iou_thresh]
+    return keep
+
+
+def decode_heatmap(det_out, image_size, score_thresh=0.3, max_dets=100):
+    """Convert raw detection head output into a list of (box, label, score)."""
+    heatmap = det_out["heatmap"][0]      # (num_classes, h, w)
+    size = det_out["size"][0]            # (2, h, w)
+    offset = det_out["offset"][0]        # (2, h, w)
+
+    num_classes, h, w = heatmap.shape
+    stride_y = image_size[0] / h
+    stride_x = image_size[1] / w
+
+    scores, classes = heatmap.max(dim=0)
+    flat_scores = scores.flatten()
+    topk = min(max_dets, flat_scores.numel())
+    top_scores, top_idx = flat_scores.topk(topk)
+
+    results = []
+    for score, idx in zip(top_scores.tolist(), top_idx.tolist()):
+        if score < score_thresh:
+            continue
+        yy, xx = divmod(idx, w)
+        cls = classes[yy, xx].item()
+        dx, dy = offset[0, yy, xx].item(), offset[1, yy, xx].item()
+        bw, bh = size[0, yy, xx].item(), size[1, yy, xx].item()
+        cx = (xx + 0.5 + dx) * stride_x
+        cy = (yy + 0.5 + dy) * stride_y
+        box = [cx - bw / 2, cy - bh / 2, cx + bw / 2, cy + bh / 2]
+        results.append({"box": box, "label": cls, "score": score})
+
+    if results:
+        keep = nms([r["box"] for r in results], [r["score"] for r in results])
+        results = [results[i] for i in keep]
+    return results
+
+
+def visualize_detections(image, detections, class_names=None, save_path=None):
+    """Draw boxes on a PIL image using only stdlib-adjacent deps (Pillow)."""
+    from PIL import ImageDraw
+
+    img = image.copy()
+    draw = ImageDraw.Draw(img)
+    for det in detections:
+        x1, y1, x2, y2 = det["box"]
+        label = det["label"]
+        name = class_names[label] if class_names else str(label)
+        draw.rectangle([x1, y1, x2, y2], outline="red", width=2)
+        draw.text((x1, max(0, y1 - 10)), f"{name} {det['score']:.2f}", fill="red")
+    if save_path:
+        img.save(save_path)
+    return img

neurovisionx-0.1.0/neurovisionx.egg-info/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: neurovisionx
+Version: 0.1.0
+Summary: Unified CNN library for image classification and anchor-free object detection with Adaptive Feature Pyramid Attention (AFPA).
+Author-email: Srikanth Sridhar <srisrikanthtvs@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/sricodings/neurovisionx
+Project-URL: Documentation, https://github.com/sricodings/neurovisionx#readme
+Project-URL: Issues, https://github.com/sricodings/neurovisionx/issues
+Keywords: deep learning,computer vision,object detection,image classification,pytorch,cnn,attention
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=1.13
+Requires-Dist: torchvision>=0.14
+Requires-Dist: pillow>=9.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# NeuroVisionX
+
+**A unified PyTorch library for image classification and anchor-free object detection**,
+built around a single shared backbone and a custom attention module: **AFPA (Adaptive
+Feature Pyramid Attention)**.
+
+[![PyPI version](https://img.shields.io/pypi/v/neurovisionx.svg)](https://pypi.org/project/neurovisionx/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/)
+
+---
+
+## Why NeuroVisionX
+
+Most beginner-friendly libraries make you choose: a simple classifier *or* a heavy,
+hard-to-configure detector (YOLO/SSD-style with anchor boxes and many hyperparameters).
+
+NeuroVisionX gives you **both, from one backbone**:
+
+- **One backbone, two heads.** Train a classifier, a detector, or both, without
+  duplicating feature extraction code.
+- **AFPA attention block.** Lightweight channel+spatial attention with a learnable
+  residual gate, so it starts as identity and "switches on" only when useful —
+  more stable than dropping raw attention into a network from scratch.
+- **Anchor-free detection head.** Predicts object centers, sizes, and sub-pixel
+  offsets directly (CenterNet/FCOS-style) — no anchor box tuning.
+- **One `Trainer` class** for both tasks, with sensible defaults.
+- **Minimal dependencies**: `torch`, `torchvision`, `pillow`. Nothing exotic.
+
+## Installation
+
+```bash
+pip install neurovisionx
+```
+
+For local development:
+
+```bash
+git clone https://github.com/sricodings/neurovisionx.git
+cd neurovisionx
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+### Classification
+
+```python
+import neurovisionx as nv
+from torch.utils.data import DataLoader
+
+train_ds = nv.ImageFolderDataset("data/train", image_size=224)
+train_loader = DataLoader(train_ds, batch_size=32, shuffle=True)
+
+model = nv.NeuroVisionXNet(num_classes=len(train_ds.classes), mode="classify")
+trainer = nv.Trainer(model, train_loader, task="classify")
+trainer.fit(epochs=20)
+```
+
+### Object detection
+
+```python
+import neurovisionx as nv
+from torch.utils.data import DataLoader
+
+train_ds = nv.DetectionDataset("data/images", "data/annotations.json", image_size=512)
+train_loader = DataLoader(train_ds, batch_size=8, shuffle=True,
+                           collate_fn=nv.dataset.detection_collate_fn)
+
+model = nv.NeuroVisionXNet(num_classes=5, mode="detect")
+trainer = nv.Trainer(model, train_loader, task="detect")
+trainer.fit(epochs=30)
+
+detections = model.detect(image_tensor, score_thresh=0.4)
+```
+
+Annotation format (`annotations.json`) — simple COCO-lite JSON:
+
+```json
+[
+  {"image": "img1.jpg", "boxes": [[34, 12, 200, 180]], "labels": [0]},
+  {"image": "img2.jpg", "boxes": [[10, 10, 50, 50], [60, 60, 120, 140]], "labels": [2, 4]}
+]
+```
+
+## Architecture overview
+
+```
+Input image
+    │
+    ▼
+ Stem conv
+    │
+    ▼
+ Stage 1 (downsample + AFPA) ─────────────┐
+    │                                     │
+    ▼                                     │
+ Stage 2 (downsample + AFPA)  -> C3       │  multi-scale
+    │                                     │  feature maps
+    ▼                                     │
+ Stage 3 (downsample + AFPA)  -> C4 ──┐   │
+    │                                 │   │
+    ▼                                 │   │
+ Stage 4 (downsample + AFPA)  -> C5   │   │
+    │                                 │   │
+    ├──> Classifier head (GAP + FC)   │   │
+    │                                 ▼   │
+    └──> 1x1 conv + upsample ──> fuse with C4
+                                       │
+                                       ▼
+                            Anchor-free detection head
+                          (heatmap, size, offset maps)
+```
+
+## Repository layout
+
+```
+neurovisionx/
+├── neurovisionx/
+│   ├── __init__.py        # public API
+│   ├── layers.py           # ConvBNAct, AFPABlock (the novel attention module)
+│   ├── backbone.py         # multi-stage CNN backbone
+│   ├── detection_head.py   # anchor-free detection head
+│   ├── model.py             # NeuroVisionXNet (combines backbone + heads)
+│   ├── dataset.py           # ImageFolderDataset, DetectionDataset
+│   ├── trainer.py           # Trainer (training loop, losses)
+│   └── utils.py             # IoU, NMS, heatmap decoding, visualization
+├── examples/
+│   ├── train_classifier.py
+│   └── train_detector.py
+├── tests/
+├── docs/
+│   └── PUBLISHING_GUIDE.md
+├── pyproject.toml
+├── LICENSE
+└── README.md
+```
+
+## Roadmap (suggested, fill in as you build)
+
+- [ ] Pretrained backbone weights (ImageNet-style pretraining)
+- [ ] ONNX export for deployment
+- [ ] Mixed-precision training support
+- [ ] Data augmentation pipeline (mosaic, mixup, random crop)
+- [ ] Benchmark results vs ResNet/YOLO baselines on COCO subset
+- [ ] Sphinx-generated documentation site
+
+## Contributing
+
+Pull requests are welcome. Please open an issue first to discuss major changes.
+Run `pytest` and `black .` before submitting.
+
+## Citing
+
+If you use NeuroVisionX in research, please cite:
+
+```bibtex
+@software{neurovisionx2026,
+  author = {YOUR NAME},
+  title = {NeuroVisionX: Unified Classification and Anchor-Free Detection with Adaptive Feature Pyramid Attention},
+  year = {2026},
+  url = {https://github.com/YOUR_USERNAME/neurovisionx}
+}
+```
+
+## License
+
+MIT License — see [LICENSE](LICENSE).

neurovisionx-0.1.0/neurovisionx.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+neurovisionx/__init__.py
+neurovisionx/backbone.py
+neurovisionx/dataset.py
+neurovisionx/detection_head.py
+neurovisionx/layers.py
+neurovisionx/model.py
+neurovisionx/trainer.py
+neurovisionx/utils.py
+neurovisionx.egg-info/PKG-INFO
+neurovisionx.egg-info/SOURCES.txt
+neurovisionx.egg-info/dependency_links.txt
+neurovisionx.egg-info/requires.txt
+neurovisionx.egg-info/top_level.txt

neurovisionx-0.1.0/neurovisionx.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

neurovisionx-0.1.0/neurovisionx.egg-info/requires.txt

@@ -0,0 +1,10 @@
+torch>=1.13
+torchvision>=0.14
+pillow>=9.0
+
+[dev]
+pytest
+black
+flake8
+build
+twine

neurovisionx-0.1.0/neurovisionx.egg-info/top_level.txt

@@ -0,0 +1 @@
+neurovisionx

neurovisionx-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "neurovisionx"
+version = "0.1.0"
+description = "Unified CNN library for image classification and anchor-free object detection with Adaptive Feature Pyramid Attention (AFPA)."
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "MIT"}
+authors = [
+  { name = "Srikanth Sridhar", email = "srisrikanthtvs@gmail.com" }
+]
+keywords = ["deep learning", "computer vision", "object detection", "image classification", "pytorch", "cnn", "attention"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Topic :: Scientific/Engineering :: Image Recognition",
+]
+dependencies = [
+  "torch>=1.13",
+  "torchvision>=0.14",
+  "pillow>=9.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/sricodings/neurovisionx"
+Documentation = "https://github.com/sricodings/neurovisionx#readme"
+Issues = "https://github.com/sricodings/neurovisionx/issues"
+
+[project.optional-dependencies]
+dev = ["pytest", "black", "flake8", "build", "twine"]
+
+[tool.setuptools.packages.find]
+include = ["neurovisionx*"]

neurovisionx-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+