mirror of
https://github.com/saymrwulf/BraiinsRatchet.git
synced 2026-11-21 06:43:11 +00:00
Add operator-first ratchet workflow
This commit is contained in:
parent
b51a8b137e
commit
d9b36082ab
5 changed files with 271 additions and 13 deletions
14
README.md
14
README.md
|
|
@ -14,22 +14,20 @@ The first implementation is deliberately conservative:
|
||||||
## Quick Start
|
## Quick Start
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
python3 -m venv .venv
|
./scripts/ratchet setup
|
||||||
./.venv/bin/python -m braiins_ratchet.cli init-db
|
./scripts/ratchet once
|
||||||
./.venv/bin/python -m braiins_ratchet.cli cycle
|
|
||||||
./.venv/bin/python -m braiins_ratchet.cli report
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Set `PYTHONPATH=src` if running without installation:
|
For a 6-hour monitoring session:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
PYTHONPATH=src python3 -m braiins_ratchet.cli evaluate
|
./scripts/ratchet watch 6
|
||||||
```
|
```
|
||||||
|
|
||||||
Run a bounded monitor loop:
|
For the human operating guide:
|
||||||
|
|
||||||
```bash
|
```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:
|
Import a manual Braiins market snapshot:
|
||||||
|
|
|
||||||
|
|
@ -1,6 +1,19 @@
|
||||||
# CLI Reference
|
# 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:
|
Use the local virtual environment:
|
||||||
|
|
||||||
|
|
|
||||||
136
docs/OPERATOR_GUIDE.md
Normal file
136
docs/OPERATOR_GUIDE.md
Normal 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`.
|
||||||
|
|
@ -5,8 +5,7 @@
|
||||||
Run these commands from the repository root:
|
Run these commands from the repository root:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli cycle
|
./scripts/ratchet once
|
||||||
PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli report
|
|
||||||
```
|
```
|
||||||
|
|
||||||
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.
|
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:
|
For short monitor sessions:
|
||||||
|
|
||||||
```bash
|
```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
|
## Manual Market Snapshot
|
||||||
|
|
||||||
|
|
|
||||||
112
scripts/ratchet
Executable file
112
scripts/ratchet
Executable 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 "$@"
|
||||||
Loading…
Reference in a new issue