From d9b36082ab6c41119efdc363a01f75fcf81c332f Mon Sep 17 00:00:00 2001 From: saymrwulf Date: Sat, 25 Apr 2026 18:09:22 +0200 Subject: [PATCH] Add operator-first ratchet workflow --- README.md | 14 ++-- docs/CLI_REFERENCE.md | 15 +++- docs/OPERATOR_GUIDE.md | 136 +++++++++++++++++++++++++++++++++++++ docs/RATCHET_OPERATIONS.md | 7 +- scripts/ratchet | 112 ++++++++++++++++++++++++++++++ 5 files changed, 271 insertions(+), 13 deletions(-) create mode 100644 docs/OPERATOR_GUIDE.md create mode 100755 scripts/ratchet diff --git a/README.md b/README.md index 53d0786..5d7ad15 100644 --- a/README.md +++ b/README.md @@ -14,22 +14,20 @@ The first implementation is deliberately conservative: ## Quick Start ```bash -python3 -m venv .venv -./.venv/bin/python -m braiins_ratchet.cli init-db -./.venv/bin/python -m braiins_ratchet.cli cycle -./.venv/bin/python -m braiins_ratchet.cli report +./scripts/ratchet setup +./scripts/ratchet once ``` -Set `PYTHONPATH=src` if running without installation: +For a 6-hour monitoring session: ```bash -PYTHONPATH=src python3 -m braiins_ratchet.cli evaluate +./scripts/ratchet watch 6 ``` -Run a bounded monitor loop: +For the human operating guide: ```bash -PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli watch --cycles 12 --interval-seconds 300 +./scripts/ratchet explain ``` Import a manual Braiins market snapshot: diff --git a/docs/CLI_REFERENCE.md b/docs/CLI_REFERENCE.md index 7225596..01f094a 100644 --- a/docs/CLI_REFERENCE.md +++ b/docs/CLI_REFERENCE.md @@ -1,6 +1,19 @@ # CLI Reference -All commands should be run from the repository root. +Most users should use the wrapper: + +```bash +./scripts/ratchet setup +./scripts/ratchet once +./scripts/ratchet watch 6 +./scripts/ratchet report +``` + +Use `./scripts/ratchet raw-cycle` only when debugging the machine-readable cycle output. + +The raw Python CLI is documented below for debugging and development. + +All raw commands should be run from the repository root. Use the local virtual environment: diff --git a/docs/OPERATOR_GUIDE.md b/docs/OPERATOR_GUIDE.md new file mode 100644 index 0000000..d8f0b7b --- /dev/null +++ b/docs/OPERATOR_GUIDE.md @@ -0,0 +1,136 @@ +# Operator Guide + +This project is a monitor and decision aid. It does not place Braiins orders. + +Think of it in Karpathy autoresearch terms: + +1. Observe the world. +2. Score one small candidate action. +3. Do nothing unless the score clears strict guardrails. +4. If you manually act, wait for the result to mature. +5. Ratchet the strategy only after measured evidence improves. + +## First-Time Setup + +From the repository root: + +```bash +./scripts/ratchet setup +``` + +What this does: + +- Creates `.venv` inside this repo if needed. +- Initializes `data/ratchet.sqlite`. +- Does not install packages. +- Does not touch anything outside the repo. + +## First Live Check + +Run: + +```bash +./scripts/ratchet once +``` + +What this does: + +- Fetches one OCEAN snapshot. +- Fetches one public Braiins market snapshot without a token. +- Computes the current breakeven and strategy recommendation. +- Prints a report. + +It intentionally hides raw JSON. If debugging is needed, use: + +```bash +./scripts/ratchet raw-cycle +``` + +## How To Read The Report + +Focus on `Strategy action`. + +If it says: + +```text +Strategy action: observe +``` + +Do not place a bid. The market is not cheap enough or required data is missing. + +If it says: + +```text +Strategy action: manual_bid +``` + +The strategy thinks a small manual canary bid clears the configured guardrails. You still decide manually in the Braiins UI. + +Important fields: + +- `best_ask_btc_per_eh_day`: current buy reference from Braiins. +- `breakeven_btc_per_eh_day`: estimated mining EV at current OCEAN/network inputs. +- `score_btc`: risk-adjusted expected value. Negative means no action. +- `proposed_spend_btc`: canary spend, currently tiny by design. +- `maturity`: how long to wait before judging a manually executed canary. + +## Normal Monitoring Session + +Run: + +```bash +./scripts/ratchet watch 6 +``` + +This watches for about 6 hours, sampling every 5 minutes. + +During the watch: + +- Leave the terminal open. +- Do not babysit every line. +- If it prints `observe`, do nothing. +- If it prints `manual_bid`, stop and run `./scripts/ratchet report` before deciding manually. + +Stop early with `Ctrl-C`. + +## When To Act + +Only consider manual action when all of these are true: + +- `Strategy action: manual_bid`. +- `score_btc` is positive. +- `best_ask_btc_per_eh_day` is below the guardrail-adjusted breakeven. +- The proposed spend is acceptable to lose. +- You can wait through the maturity window before judging the result. + +Do not act because OCEAN is "due". Block discovery is memoryless. + +## How Long To Wait After A Manual Canary + +Use the report's `maturity` line. + +With the current OCEAN estimate, it is about: + +```text +72 hours +``` + +That comes from the 8-block TIDES window and about 9 hours expected OCEAN block time. Do not judge the experiment after only minutes or a few hours. + +## Daily Routine + +Practical routine: + +1. Morning: `./scripts/ratchet once` +2. If `observe`: do nothing. +3. If you want live monitoring: `./scripts/ratchet watch 6` +4. If `manual_bid`: inspect `./scripts/ratchet report` +5. If you manually place a canary, write down the Braiins order parameters and wait through the maturity window. + +## Safety Boundaries + +- No owner token goes into this repo. +- No watcher token is needed for public price monitoring. +- No code here places orders. +- `.venv` and `data/` are local runtime state. +- The Git branch is `master`. diff --git a/docs/RATCHET_OPERATIONS.md b/docs/RATCHET_OPERATIONS.md index 87890a5..aab2f61 100644 --- a/docs/RATCHET_OPERATIONS.md +++ b/docs/RATCHET_OPERATIONS.md @@ -5,8 +5,7 @@ Run these commands from the repository root: ```bash -PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli cycle -PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli report +./scripts/ratchet once ``` The result is a recommendation only. `manual_bid` means the strategy thinks a manually placed bid clears the configured guardrails. `observe` means no action is recommended. @@ -18,10 +17,10 @@ The report's sampled price min/avg/max uses public Braiins snapshots only. Manua For short monitor sessions: ```bash -PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli watch --cycles 12 --interval-seconds 300 +./scripts/ratchet watch 6 ``` -This runs for about one hour at 5-minute intervals. It is bounded by design; use your shell or system scheduler if you want recurring sessions. +This runs for about six hours at 5-minute intervals. It is bounded by design. ## Manual Market Snapshot diff --git a/scripts/ratchet b/scripts/ratchet new file mode 100755 index 0000000..2d9d378 --- /dev/null +++ b/scripts/ratchet @@ -0,0 +1,112 @@ +#!/usr/bin/env bash +set -euo pipefail + +ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +PYTHON_BIN="$ROOT_DIR/.venv/bin/python" + +usage() { + cat <<'USAGE' +Braiins Ratchet + +Commands: + setup Create the local .venv and initialize the local database. + once Run one full monitor cycle, then print the human report. + watch [hours] Run repeated monitor cycles for N hours. Default: 6. + report Print the latest stored report without fetching new data. + raw-cycle Run one full monitor cycle and print raw JSON. + test Run the network-free test suite. + explain Print the operating procedure and interpretation guide. + +Examples: + ./scripts/ratchet setup + ./scripts/ratchet once + ./scripts/ratchet watch 6 + ./scripts/ratchet report +USAGE +} + +ensure_venv() { + if [[ ! -x "$PYTHON_BIN" ]]; then + echo "Creating local virtual environment at .venv ..." + python3 -m venv "$ROOT_DIR/.venv" + fi +} + +run_python() { + ensure_venv + PYTHONPATH="$ROOT_DIR/src" "$PYTHON_BIN" "$@" +} + +cmd_setup() { + ensure_venv + run_python -m braiins_ratchet.cli init-db + echo + echo "Setup complete. Next: ./scripts/ratchet once" +} + +cmd_once() { + run_python -m braiins_ratchet.cli cycle >/dev/null + echo + run_python -m braiins_ratchet.cli report +} + +cmd_raw_cycle() { + run_python -m braiins_ratchet.cli cycle +} + +cmd_watch() { + local hours="${1:-6}" + local interval_seconds=300 + local cycles + + if ! [[ "$hours" =~ ^[0-9]+$ ]] || [[ "$hours" -lt 1 ]]; then + echo "watch expects whole hours, e.g. ./scripts/ratchet watch 6" >&2 + exit 2 + fi + + cycles=$((hours * 3600 / interval_seconds)) + echo "Running $cycles cycles over about $hours hour(s), one cycle every $interval_seconds seconds." + echo "Stop early with Ctrl-C. This only reads public/OCEAN data and writes local snapshots." + echo + + run_python -m braiins_ratchet.cli watch --cycles "$cycles" --interval-seconds "$interval_seconds" + echo + run_python -m braiins_ratchet.cli report +} + +cmd_report() { + run_python -m braiins_ratchet.cli report +} + +cmd_test() { + run_python -m unittest discover -s "$ROOT_DIR/tests" +} + +cmd_explain() { + cat "$ROOT_DIR/docs/OPERATOR_GUIDE.md" +} + +main() { + cd "$ROOT_DIR" + local command="${1:-help}" + shift || true + + case "$command" in + setup) cmd_setup "$@" ;; + once) cmd_once "$@" ;; + watch) cmd_watch "$@" ;; + report) cmd_report "$@" ;; + raw-cycle) cmd_raw_cycle "$@" ;; + test) cmd_test "$@" ;; + explain) cmd_explain "$@" ;; + help|-h|--help) usage ;; + *) + echo "Unknown command: $command" >&2 + echo >&2 + usage >&2 + exit 2 + ;; + esac +} + +main "$@"