mirror of
https://github.com/saymrwulf/BraiinsRatchet.git
synced 2026-11-17 06:20:41 +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
|
||||
|
||||
```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:
|
||||
|
|
|
|||
|
|
@ -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
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:
|
||||
|
||||
```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
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