🐍 ViperX
The Mentor-Based Project Initializer Stop memorizing boilerplate. Start learning best practices.
ViperX is more than a CLI—it's an automated mentor. It generates production-ready Python projects (Classic, ML, DL) using uv, but crucially, it creates ultra-commented code that teaches you why the structure is built that way.
🦅 Philosophy: "Freedom & Grip"
- Grip (Mentorship): We hold your hand at the start with strict, educational defaults.
- Freedom (No Lock-in): Use
viperx ejectto remove the tool entirely. Your code remains standard Python. - Conscious Mastery: We aim to make you autonomous, not dependent.
🎓 Educational Features
1. The Knowledge Base (viperx learn)
Don't leave the terminal to read generic tutorials. ViperX includes a curated knowledge base about modern Python tooling.
viperx learn uv # Why uv is the future of packaging
viperx learn structure # Why we use the src/ layout
viperx learn packaging # Understanding pyproject.toml
2. Explain Mode (--explain or Persistent)
Pass the global --explain flag to any command to get a real-time architectural breakdown.
Or make it permanent:
viperx explain --activate # I want a mentor for everything
viperx explain --deactivate # I know what I'm doing now
When active, every command explains itself:
$ viperx config -n my-lib --explain
╭─ 🎓 Explain: Project Structure Strategy ────────────────────────╮
│ We are about to create my-lib. │
│ - Layout: src/ layout (Standard) │
│ - Why?: Placing code in src/ prevents "import side effects". │
│ It forces you to install the package to test it. │
│ - Tool: We use uv init because it sets up a modern │
│ pyproject.toml automatically. │
╰─────────────────────────────────────────────────────────────────╯
✨ Features
- Education First: Generated files are learning materials.
viperx --explaintells you the "why". - Blazing Fast: Built on top of
uvfor sub-second setup. - Pre-configured:
pyproject.toml, propersrclayout,ruffready. - ML/DL First: Templates with
torch,tensorflow,kagglehuband Smart Caching. - Smart Caching: Auto-downloads and caches datasets to
~/.cache/viperx/data(or localdata/). - Strict Isolation: Environment variables (
.env) isolated insrc/<pkg>/for better security. - Config-in-Package: Solves the "Colab/Kaggle doesn't see my config" problem.
- Platform Agnostic: Works on Local, VSCode, Colab, and Kaggle.
- Safe Mode: Never overwrites or deletes files automatically—reports changes for manual action.
📦 Installation
Recommended (Global Tool)
pipx install viperx
Alternative (uv)
uv tool install viperx
🚀 Quick Start
# Classic Package
viperx config -n my-lib
# Machine Learning Project
viperx config -n churn-prediction -t ml --env
# Deep Learning Project (PyTorch)
viperx config -n deep-vision -t dl -f pytorch
# Declarative Config (Infrastructure as Code)
viperx config get # Generate template
viperx config -c viperx.yaml # Apply config
🧱 Project Structure
Standard Layout
my-lib/
├── pyproject.toml # Managed by uv
├── README.md
├── .gitignore
├── viperx.yaml # Config file
└── src/
└── my_lib/
├── __init__.py
├── main.py # Entry point
├── config.yaml # Data URLs & Params
├── config.py # Loader
├── .env # Secrets (ISOLATED)
└── tests/
└── test_core.py
ML/DL Layout
deep-vision/
├── pyproject.toml
├── notebooks/
│ ├── Base_Kaggle.ipynb
│ └── Base_General.ipynb
├── data/ # Cached datasets
└── src/
└── deep_vision/
├── main.py
├── config.py # <--- ISOLATED
├── .env # <--- ISOLATED
├── data_loader.py # Smart caching
└── tests/
💻 CLI Reference
config - Main Command
viperx config [OPTIONS]
Options:
| Flag | Description | Default |
|---|---|---|
-n, --name |
Project name (Required) | - |
-t, --type |
classic, ml, dl |
classic |
-d, --description |
Project description | - |
-a, --author |
Author name | git user |
-l, --license |
MIT, Apache-2.0, GPLv3 |
MIT |
-b, --builder |
uv, hatch |
uv |
-f, --framework |
pytorch, tensorflow (DL only) |
pytorch |
--env / --no-env |
Generate .env file |
--no-env |
-c, --config |
Path to viperx.yaml |
- |
learn - Educational Hub
viperx learn # List topics
viperx learn uv # Learn about uv
Global Options
--explain: Enable detailed architectural explanations during execution.--version: Show version.
config get - Generate Template
viperx config get
Creates a viperx.yaml template in current directory.
config update - Rebuild from Codebase
viperx config update
Scans the existing project and updates viperx.yaml to match reality:
- Detects packages in
src/ - Detects
use_config,use_env,use_testsfrom actual files - Adds annotations for any mismatches
package - Workspace Management
# Add package
viperx package add -n worker-api -t classic
# Delete package
viperx package delete -n worker-api
# Update dependencies
viperx package update -n worker-api
📝 Declarative Config (viperx.yaml)
project:
name: "my-project"
description: "A cool project"
author: "Your Name"
license: "MIT"
builder: "uv"
settings:
type: "classic" # classic | ml | dl
use_env: false
use_config: true
use_tests: true
workspace:
packages:
- name: "api"
type: "classic"
- name: "ml-core"
type: "ml"
use_env: true
🔒 Safe Mode Philosophy
ViperX follows a non-destructive approach:
| Action | Behavior |
|---|---|
| Add | ✅ Creates new files/packages |
| Update | ⚠️ Reports changes, user decides |
| Delete | ❌ Never deletes—warns user |
| Overwrite | ❌ Never overwrites existing files |
🧪 Test Coverage
uv run pytest src/viperx/tests
# 46 tests | 76% coverage
Test Structure:
unit/- Validation (5 tests)functional/- CLI, licenses, project types, updates (18 tests)scenarios/- Classic, workspace, type blocking, config scanner (18 tests)integration/- E2E lifecycle (5 tests)
🤝 Contributing
git clone https://github.com/KpihX/viperx.git
cd viperx
uv sync
uv run viperx --help
Built with ❤️ by KpihX
1 maintainer
Metadata
1 maintainer
Release files for viperx 1.7.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| viperx-1.7.0.tar.gz | 62.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| viperx-1.7.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 146.6 kB
Release files / viperx-1.7.0.tar.gz
| Download URL | viperx-1.7.0.tar.gz |
|---|---|
| Size | 62.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0bf3f0560345f0faa310c4d3dcdaa5f5dc2af483f4093a8a193e83d2ee0f5a69
|
|
BLAKE2b-256 checksum How to use checksums |
12a6bce0bdc0424e1853581d707596aa8fcfc3efc5a3912948e600cce3b5d8fa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.21 {"installer":{"name":"uv","version":"0.9.21","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"25.10","id":"questing","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / viperx-1.7.0-py3-none-any.whl
| Download URL | viperx-1.7.0-py3-none-any.whl |
|---|---|
| Size | 84.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d976c41878c7d38ddc65b872d8208c66084b180c000c5b081f7398b1bcb1f08c
|
|
BLAKE2b-256 checksum How to use checksums |
37059ab855f9ae03e65b6d8380370699dab434c500d324d291d95ce30430978d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.21 {"installer":{"name":"uv","version":"0.9.21","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"25.10","id":"questing","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
