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).
