████████╗███████╗███╗   ██╗███████╗██████╗  ██████╗ ██╗   ██╗██╗███╗   ███╗
╚══██╔══╝██╔════╝████╗  ██║██╔════╝██╔══██╗██╔═══██╗██║   ██║██║████╗ ████║
   ██║   █████╗  ██╔██╗ ██║█████╗  ██████╔╝██║   ██║██║   ██║██║██╔████╔██║
   ██║   ██╔══╝  ██║╚██╗██║██╔══╝  ██╔══██╗██║   ██║██║   ██║██║██║╚██╔╝██║
   ██║   ███████╗██║ ╚████║███████╗██║  ██║╚██████╔╝╚██████╔╝██║██║ ╚═╝ ██║
   ╚═╝   ╚══════╝╚═╝  ╚═══╝╚══════╝╚═╝  ╚═╝ ╚═════╝  ╚═════╝ ╚═╝╚═╝     ╚═╝

Introduction

Tensorium is a production-ready starter kit for Bittensor developers. It bundles tutorials, scripts, and automation helpers so you can go from a fresh Ubuntu VM to a monitored miner with confidence.

---

Why Tensorium

• Opinionated structure so scripts, logs, and env files live in predictable locations.
• Beginner-friendly narrative with quizzes, example outputs, warnings, and review questions.
• Automation-ready tooling (Tensorium CLI, cron-safe scripts, log rotation guidance).
• Refactor-ready layout that mirrors how production Bittensor teams organize assets.

---

Features

• Guided Learning Path – Six tutorials (700–1200 words) with quizzes, example outputs, warning/tip callouts, and review questions.
• Production Scripts – Hardened installers, GPU detectors, miner launchers, and systemd templates that work on Ubuntu/Debian.
• Tensorium CLI – Colored output, argparse subcommands, auto btcli detection, logging, and friendly error handling.
• Docs & Examples – Architecture notes in docs/, realistic CLI transcripts and outputs in examples/.
• Automation Ready – .env conventions, cron/systemd snippets, log rotation tips, GPU tuning guidance.
• Visual Assets – Use images/ to store diagrams/screenshots referenced throughout tutorials.

---

Tutorials Index

See tutorials/README.md for prerequisites and estimated durations.

#	Title	Highlights
01	Installation & Environment Readiness	Ubuntu prep, venv creation, Bittensor install, GPU setup, validation logs.
02	btcli Basics	Command anatomy, subnet/wallet/stake flows, JSON dashboards.
03	Wallets & Miner Identities	Coldkey vs hotkey, backups, env files, registration workflows.
04	Running Your First Miner	Configs, screen/systemd launches, helper tools, monitoring.
05	Advanced Miner Setup	GPU tuning, multi-miner orchestration, observability, automation.
06	Tensorium CLI Tool	Install, extend, log, and automate the CLI for daily ops.

---

🚀 Quickstart

1. Install Bittensor

   cd scripts
   sudo ./install_bittensor.sh

2. Create a wallet & hotkey

   btcli wallet new --wallet-name tensorium --wallet-hotkey miner-main

3. Start a miner

   ./scripts/run_miner_simple.sh --netuid 1 --config configs/miner-netuid-1.yaml
   # or
   tensorium start-miner --netuid 1 --config configs/miner-netuid-1.yaml

Cursor (or any AI pair programmer) can automate each step end-to-end.

---

Installation Steps

git clone https://github.com/<your-org>/tensorium.git
cd tensorium
tree -L 2
chmod +x scripts/*.sh tools/tensorium_cli.py tools/miner-installer/miner.py

cd scripts
sudo ./install_bittensor.sh
sudo ./install_bittensor.sh --validate-only  # optional sanity check

The installer logs to /var/log/tensorium-install.log, installs dependencies, syncs bittensor into /opt/tensorium/bittensor, and provisions a virtual environment with btcli.

Credentials

cat <<'EOF' | sudo tee /opt/tensorium/.env
BT_WALLET_NAME=tensorium
BT_WALLET_HOTKEY=miner-main
BT_HOTKEY_PASSWORD=change_me
EOF
sudo chmod 600 /opt/tensorium/.env

Follow Tutorials 02–03 for wallet creation, backups, and registration best practices.

---

CLI Usage

cd /opt/tensorium/bittensor
source .venv/bin/activate
sudo ln -sf tools/tensorium_cli.py /usr/local/bin/tensorium
tensorium --help

Command	Description
tensorium list-subnets --max-rows 5	Snapshot incentives & difficulty (wraps btcli subnet list).
tensorium check-wallet --wallet-name tensorium / tensorium wallet-balance --wallet-name tensorium	Show wallet balances/stake with optional JSON output.
tensorium wallet-import --wallet-name tensorium --wallet-hotkey miner-main --mnemonic-file coldkey.txt	Guided coldkey/hotkey import.
tensorium start-miner --netuid 1 --config configs/miner-netuid-1.yaml	Launch miners via scripts/run_miner_simple.sh.
tensorium install --validate-only	Run/validate scripts/install_bittensor.sh (sudo).
tensorium gpu-detect	Calls scripts/detect_gpu.sh for NVIDIA/AMD summaries.

Logs live in /opt/tensorium/logs/tensorium-cli.log; pass --verbose for debug output.

CLI examples

tensorium list-subnets --max-rows 5
tensorium wallet-balance --wallet-name tensorium
tensorium start-miner --netuid 1 --config configs/miner-netuid-1.yaml

---

Screenshots & Images

Use images/ to store diagrams and screenshots referenced in tutorials:

• images/install-overview.png – high-level setup diagram.
• images/miner-flow.png – miner launch flow (used in Tutorial 04).
• images/btcli-overview.png – CLI reference sheet.
• images/cli-overview.png – Tensorium CLI architecture.

Reference them with Markdown:

![miner launch flow placeholder](images/miner-flow.png)

---

Folder Structure

Tensorium/
 ├── tutorials/
 ├── tools/
 ├── scripts/
 ├── images/
 ├── examples/
 ├── README.md
 ├── CHANGELOG.md
 └── LICENSE

Tip: keep new tutorials aligned with templates/tutorial-template.md, and place long-form docs in docs/ when needed.

---

Support & Contributions

• Issues – Log bugs, script requests, or tutorial feedback.
• Discussions – Share miner wins, coaching tips, or roadmap ideas.
• Community – Join the Bittensor Discord (#tensorium) for live help and GPU tips.
• Email – tensorium@yourdomain.com for private inquiries or support agreements.

Contribution checklist:

1. Fork + branch.
2. Match the style used throughout tutorials/scripts.
3. Run tensorium --help, scripts/detect_gpu.sh, and any modified scripts.
4. Provide logs/screenshots showing the change.
5. Open a PR referencing the tutorial/script you updated.

Happy mining — and welcome to Tensorium. 🚀