Add operator-first ratchet workflow

This commit is contained in:
saymrwulf 2026-04-25 18:09:22 +02:00
parent b51a8b137e
commit d9b36082ab
5 changed files with 271 additions and 13 deletions

View file

@ -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:

View file

@ -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:

136
docs/OPERATOR_GUIDE.md Normal file
View file

@ -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`.

View file

@ -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

112
scripts/ratchet Executable file
View file

@ -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 "$@"