Tensoris

Tensoris is a production-ready PyTorch deep learning library and framework featuring modular neural components, automated multi-version documentation via mike, pre-commit quality checks, and automated PyPI CI/CD releases.

---

Minimum System Requirements

Before getting started, ensure your local environment meets the following requirements:

• Python: >= 3.11
• Package & Environment Manager: uv (recommended) or pip
• Version Control: Git
• Container Runtime (Optional): Docker + NVIDIA Container Toolkit (for GPU containerization)

---

Pre-Coding Setup Checklist

Complete this manual checklist before writing project code:

• Project Metadata: Update name, version, description, and requires-python in pyproject.toml.
• Environment Synchronization: Run uv sync --all-groups to create the virtual environment and install the source package in editable mode (-e .).
• Git Pre-commit Hooks: Run uv run pre-commit install to enable automatic formatting and linting on git commits.
• Secrets & Environment Variables: Verify .env files are ignored in .gitignore before storing sensitive API keys or credentials.
• Documentation URLs & Metadata: Update site_name, site_url, and repo_url in properdocs.yml.
• Citation Info: Update author details and ORCID in CITATION.cff and docs/citation-contact.md.

---

Quickstart

# 1. Clone the repository
git clone https://github.com/haddagart/tensoris.git
cd tensoris

# 2. Sync dependencies & setup virtual environment
uv sync --all-groups

# 3. Install pre-commit hooks
uv run pre-commit install

# 4. Launch training workflow
uv run python scripts/train.py --config inputs/experiments/default.yaml

# 5. Serve documentation site locally
uv run properdocs serve

Or Run via GPU Docker Container (Hot-Reloaded)

# Launch training inside hot-reloaded GPU Docker environment
docker compose -f docker/docker-compose.yml up dev

---

Template Flexibility

This project structure is designed as a generic, modular boilerplate suitable for both academic research and production-ready applications.

[!TIP] Developers are encouraged to delete or remove any unnecessary folders or template files (e.g., docker/, notebooks/marimo/, toolkit/, or unused entrypoint scripts) to tailor the workspace to your specific project needs.

---

Project Structure & Architecture

For a complete breakdown of all directories and architectural guidelines, see the Project Structure Overview.

---

Automatic Versioning & Releases

This project features tag-based dynamic versioning and automated bundling:

• Dynamic Python Versioning: Version is computed automatically from Git tags via hatch-vcs and exposed in src/__init__.__version__.
• Automated GitHub Releases: Pushing a tag (git tag v1.0.0 && git push origin v1.0.0) triggers .github/workflows/release.yml to compile .whl and .tar.gz bundles and publish a GitHub Release.
• Multi-Version Docs: .github/workflows/docs.yml uses mike to build and deploy multi-version documentation with an interactive version dropdown selector.

For full details, see the Versioning Guide.

---

Social Responsibility & Environmental Commitment

🌿 Environmental Sustainability & Green Computing

We advocate for sustainable and energy-efficient practices in Artificial Intelligence and Deep Learning. High-performance GPU training carries a tangible environmental and carbon footprint. Developers using this boilerplate are encouraged to:

• Monitor compute energy consumption and carbon emissions (e.g., via tools like CodeCarbon).
• Leverage efficient hyperparameter search, mixed precision (fp16/bf16), gradient accumulation, and early stopping to avoid wasted GPU compute cycles.

🔬 Support Free Science & Open Access

We stand in solidarity with researchers, scientists, and students worldwide affected by funding cuts, institutional constraints, or prohibitive paywalls. We believe scientific knowledge, open-source code, preprints, and open datasets should be freely accessible to everyone—without financial or geographical barriers.

🤝 Stand Against Discrimination & Racism

We stand firmly against all forms of racism, discrimination, harassment, and social inequality. Open-source science and technology thrive when everyone can participate safely, equitably, and with dignity. We are committed to fostering an inclusive, welcoming, and empowering research community for all.

🤖 AI & Agentic Coding in Research: Ethics & Scientific Deontology

Artificial Intelligence and Agentic Coding assistants are transformative catalysts for modern science—accelerating software setup, streamlining boilerplate engineering, and freeing researchers to focus on core domain insights.

However, technology serves as an amplifier of human intent, not a substitute for human responsibility. We advocate for the ethical and transparent use of AI in scientific research:

• Human Accountability: Authors and researchers remain fully accountable for their code correctness, mathematical proofs, experimental results, and scientific claims.
• Scientific Rigor & Deontology: AI-generated code, algorithms, and analytical logic must be thoroughly audited, verified, and validated against empirical ground truth.
• Transparency & Attribution: We encourage open declaration of AI tools used during software development and manuscript preparation, upholding the highest standards of academic honesty, reproducibility, and scientific ethics.

---

Citation & Attribution

If you use Tensoris in your academic research or production applications, please consider citing it as below:

BibTeX Entry

@software{haddag_tensoris_2026,
  author       = {Haddag, Abdelkader},
  title        = {Tensoris: Production-Ready PyTorch Framework},
  abstract     = {Production-ready PyTorch library with automated CI/CD, multi-version docs, and PyPI packaging. Made for researchers and coders in mind first.},
  year         = {2026},
  publisher    = {GitHub},
  journal      = {GitHub repository},
  howpublished = {\url{https://github.com/haddagart/tensoris}}
}

APA Style

Haddag, A. (2026). Tensoris: Production-Ready PyTorch Framework. GitHub. https://github.com/haddagart/tensoris

---

License

This project is licensed under the MIT License - see the LICENSE file for details.