Skip to content

Welcome

Tensoris Logo

A Production-Grade, Academic-First PyTorch Framework & Architecture Library

GitHub Repo PyPI PyTorch uv Docker

🌟 Executive Summary

Tensoris (tensoris) is a standardized, high-performance architecture framework tailored for AI researchers, scientific engineers, and deep learning practitioners. It bridges the gap between theoretical peer-reviewed research papers and production-ready PyTorch implementations by enforcing strict modularity, automated API documentation, Docker GPU reproducibility, and domain-grouped deep learning primitives.

🏗️ Architectural Design System

The repository enforces a clean 3-tier separation of concerns across neural network building blocks:

src/
└── tensoris/
    ├── backend/
    │   ├── components/
    │   │   ├── layers/      <-- Atomic neural network layers (ConvStem, PositionalEncoding)
    │   │   └── blocks/      <-- Reusable multi-layer blocks (ResidualBlock, TransformerEncoderBlock, VAE Blocks)
    │   ├── losses/          <-- Peer-reviewed loss functions (Focal, Dice, LabelSmoothing, InfoNCE, Perceptual)
    │   ├── metrics/         <-- Evaluation metrics (mIoU, Top-K Accuracy, Perplexity, FID Score)
    │   └── trainers/        <-- Robust ModelTrainer execution loop
    ├── models/              <-- Complete composite end-to-end architectures (VisionBackbone, Transformer, VAE)
├── data/                <-- Dataset loaders and data pipeline abstractions
└── lib/                 <-- Utility helpers, seed managers, and system diagnostics

🔬 Scientific Domains & Implemented Primitives

Every primitive included in this template is implemented in PyTorch and documented with official peer-reviewed paper citations in its docstring:

Domain Neural Block / Layer Loss Function Evaluation Metric Reference Paper
Computer Vision ConvStem, ResidualBlock FocalLoss, DiceLoss MeanIoU, TopKAccuracy Lin et al. (ICCV 2017), Milletari et al. (3DV 2016), Long et al. (CVPR 2015)
Natural Language Processing PositionalEncoding, TransformerEncoderBlock LabelSmoothingCrossEntropy PerplexityMetric Vaswani et al. (NIPS 2017), Szegedy et al. (CVPR 2016), Jelinek et al. (1977)
Generative AI & Multimodal VAEEncoderBlock, VAEDecoderBlock ContrastiveInfoNCELoss, PerceptualLoss FIDScoreMetric Kingma & Welling (ICLR 2014), Oord et al. (2018), Heusel et al. (NIPS 2017)

🚀 Workflow Entrypoints & Commands

Command Purpose Target Script
python3 main.py Run environment diagnostics (Python, PyTorch, GPU device) main.py
python3 scripts/train.py Launch PyTorch model training loop scripts/train.py
python3 scripts/evaluate.py Compute evaluation metrics on validation set scripts/evaluate.py
uv run properdocs serve Launch live local documentation server properdocs.yml
docker compose -f docker/docker-compose.yml up Launch GPU Docker container with live volume mounts docker/docker-compose.yml

🛠️ Specialized AI Agent Skills

This repository includes custom AI agent skills designed for automated project conversion, hyperparameter sweeps, checkpoint export, and paper translation:

  • convert-to-dl-template: Reorganizes raw PyTorch codebases to adhere strictly to this boilerplate layout.
  • dl-experiment-runner: Launches automated hyperparameter sweeps and tracks metric outputs.
  • dl-model-exporter: Converts trained PyTorch checkpoints (.pt) to ONNX and TorchScript deployment formats.
  • dl-paper-to-code: Translates novel scientific paper equations into modular backend/components/ and unit tests.
  • Getting Started: System requirements, setup guide, project structure, Docker workflow, AI skills, and documentation guide.
  • For Academics: Key references, citation formats (CITATION.cff), and researcher contact details.
  • API Reference: Dynamically generated, human-readable module hierarchy displaying docstrings and paper citations.

⚡ AI Pair Programming Acknowledgment
This deep learning boilerplate template and documentation ecosystem was elaborated through AI pair programming powered by Google's Gemini and Antigravity in collaboration with Abdelkader Haddag.