Quantoshi

Bitcoin price projection tools built on a quantile regression bubble model.

quantoshi.xyz  ·  Tor onion  ·  Download AppImage

---

Three components share the same underlying model:

Component	Description
Notebook (SP.ipynb)	Jupyter notebook — bubble model, QR analysis, chart export (retired; see tools/build_bm_model.py)
Web app (btc_web/)	Plotly Dash — live at quantoshi.xyz or run locally

The web app provides nine interactive tabs: Bubble + QR Overlay, CAGR Heatmap, BTC Accumulator, BTC RetireMentator, HODL Supercharger, Stack Tracker, Model Info, FAQ, and Citadel Planner. The CAGR Heatmap supports an optional Monte Carlo (Markov chain) simulation overlay in addition to the quantile regression and power law models. The User Model (U₁) feature lets you upload your own custom price model and overlay it on any chart.

---

Web App

Requirements

• Python 3.10+ (developed on 3.14.3)
• Linux (tested on Arch/CachyOS; should work on any modern distro)

Local setup

git clone https://github.com/bg002h/quantoshi.git
cd quantoshi

# Create virtual environment
python3 -m venv btc_venv --system-site-packages
btc_venv/bin/pip install -r btc_web/requirements.txt

# Start the server (gunicorn, port 8050)
bash run_web.sh

# Or use the Dash dev server with hot-reload (single user only)
DEV=1 bash run_web.sh

Open http://localhost:8050 in your browser.

To use a different port:

PORT=8080 bash run_web.sh

systemd service (auto-start on boot)

Copy the included service file and enable it:

# Edit btc-web.service first if your username or path differs from defaults
sudo cp btc-web.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now btc-web
sudo systemctl status btc-web

---

Tor Onion Service

Expose the web app as a .onion address so you can reach it from any device running Tor Browser — including over mobile data, without opening firewall ports or needing a domain name.

1. Install Tor

# Arch / Manjaro / CachyOS
sudo pacman -S tor

# Debian / Ubuntu
sudo apt install tor

2. Configure the hidden service

Add the following two lines to /etc/tor/torrc:

HiddenServiceDir /var/lib/tor/btcprojections/
HiddenServicePort 80 127.0.0.1:8050

3. Start Tor and the web app

sudo systemctl enable --now tor
sudo systemctl enable --now btc-web   # or run_web.sh manually

4. Get your onion address

sudo cat /var/lib/tor/btcprojections/hostname
# → something like abcdef1234567890.onion

Open that address in Tor Browser.

Note: The first connection takes 30–60 seconds while Tor establishes its circuit. Subsequent loads are faster.

---

Repository structure

BitcoinPricesDaily.csv      Historical BTC price data
model_data.pkl              Pre-computed QR fits (regenerated by tools/build_bm_model.py)
btc_web/
  app.py                    Dash app entry point — model loading, cache prewarm
  _app_ctx.py               Shared application context (constants, dynamic state)
  tab_defaults.py           Tab default values
  cache.py                  LRU figure cache helpers
  snapshot.py               Snapshot/URL state encoding and decoding
  utils.py                  Shared utilities (price fetching, quantization)
  figures/                  Plotly chart builders (one module per tab)
  layout/                   Tab controls and layout assembly (one module per tab)
  callbacks/                All Dash callbacks (one module per concern)
  engines/                  Citadel Planner and user model engine adapters
  assets/style.css          Light theme CSS
  requirements.txt
btc-web.service             systemd unit file
run_web.sh                  Convenience startup script
scripts/
  quantoshi-health          Production health check (HTTP, SSH, systemd, error log)
  quantoshi-restart         Production restart helper
  change_origin.py          Git remote URL updater

---

Operations scripts

scripts/ contains helper scripts for managing the production deployment.

Health check

# Verbose status report
scripts/quantoshi-health

# Fullscreen PyQt6 alert popup on failure (for systemd timer)
scripts/quantoshi-health --popup

# Simulate a random failure (test the alert pipeline)
scripts/quantoshi-health --test --popup

Checks: HTTPS health endpoint, SSH reachability, systemd service status, and gunicorn error log for tracebacks/BackgroundCallbackError since the last restart (avoids false alarms from pre-fix errors).

To install for local use, symlink into your PATH:

ln -s "$(pwd)/scripts/quantoshi-health" ~/bin/quantoshi/quantoshi-health

---

Updating price data

BitcoinPricesDaily.csv is read by both the notebook and the desktop app. After updating it, re-run the notebook to regenerate model_data.pkl, then rebuild the AppImage if you want the desktop app to reflect the new data.

---

Heavy cache regeneration (MC + Citadel)

Two compute-intensive caches are built on dev and shipped to prod:

Cache	Size	Build time
MC cache (Markov simulations)	~1.2 GB	2–4 hours
Citadel band cache	~200 MB	~4 hours (18 workers)

Both are too large for git (.gitignore-d). Prod loads them at startup and saves a snapshot to /dev/shm for fast restarts.

# Build both on dev, rsync to prod, restart quantoshi:
bash tools/rebuild_caches.sh

# Options:
bash tools/rebuild_caches.sh --mc          # MC cache only
bash tools/rebuild_caches.sh --citadel     # Citadel bands only
bash tools/rebuild_caches.sh --no-deploy   # build only, skip rsync

When to regenerate: after major model changes or significant new price history. Small LPPL parameter drift (from the monthly refit on prod) does NOT warrant a rebuild — the drift is negligible.

---

Multi-user / privacy notes

The web app stores no user data server-side. Stack Tracker lots are kept in your browser's localStorage only. The JSON export/import buttons let you back up and restore your lot data manually.

For a public-facing server, run behind a reverse proxy (nginx/caddy) with TLS, or use the Tor onion service which provides end-to-end encryption by default.

---

Further documentation

• Architecture guide — system design overview
• User manual — tab-by-tab feature guide for end users
• LPPL model family — 10 LPPL variants, weighting, regime shifts, why LP3 is the honest default
• Cache architecture — figure caches, MC cache, Citadel bands, refit schedules