Files

T

dodoxandClaude Sonnet 5 7a538cb300 Initial PuGa toolkit: data layer, econ, depth-aware scan, state sync, plan push

- puga/: cached FIO + PRUNplanner clients, market view with order-book walk,
  econ formulas ported from PRUNplanner (tested against its suite and live FIO),
  saturation model v1 (reviewed by Opus)
- tools/: scan (depth-aware), price, book, chain, state sync, plan_push
  (dry run default, [PuGa]-prefixed plans only), legacy prun_scan/prun_cxarb
- docs/: mechanics (PRUNplanner is source of truth), roadmap, decisions,
  saturation design, archived handoff
- secrets stay in .env (gitignored); ref/ holds PRUNplanner source (ignored)

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

2026-09-18 23:00:21 +02:00

4.2 KiB

Raw Blame History

PuGa: Prosperous Universe advisory toolkit

Agent-first toolkit for advising Dominik (username dodox, company GBI, faction Antares, home CX AI1). He asks questions; you answer by running tools in tools/ against live data. Read this file first, then docs/mechanics.md and state/company.yaml.

How to work with Dominik

Expert user. Numbers, tables, ROI per day. Short answers, no fluff, no moralising. Semicolons over dashes; no em dashes.
He plays on browser APEX (free licence) and sends screenshots; read them carefully, they override assumptions.
Never guess APEX commands or numbers. Pull data (tools, FIO, PRUNplanner) or search. Command list: docs/apex.md (when written) and docs/handoff-2026-09-18.md §4.
Label every number: live (tool output), state (company.yaml), or estimate; say which in-game command would confirm an estimate.
Prices move; re-run tools before quoting. Snapshot prices in the handoff doc are stale.

Source-of-truth rules

PRUNplanner code wins over our own docs for game mechanics (ref/frontend/src/features/planning/calculations/, ref/backend/). If docs/handoff-2026-09-18.md conflicts with it, the handoff is wrong; fix docs/mechanics.md.
In-game numbers Dominik reports beat both, especially for planet resource factors.
ref/ is a gitignored copy of the PRUNplanner repos; refresh with tools/refresh_refs.sh.

Setup

Python venv at .venv (.venv/bin/python, .venv/bin/pip). Deps in requirements.txt.
Secrets in .env (gitignored; template .env.example): FIO REST key, FIO API key, PRUNplanner key. Never print or commit them; do not ask Dominik to paste keys into chat.
Scope: whole universe supported; default region Antares (exchange AI1, --cx to change).

Layout

CLAUDE.md this file; docs/ mechanics, refs, roadmap, decisions, archived handoff.
state/company.yaml company state (bases, buildings, ships); update when Dominik reports changes.
puga/ shared library (data layer, market, econ, world); tools/ CLIs; data/cache/ fetched data; tests/.
ref/ PRUNplanner source (read-only reference).

Tools (current)

tools/state.py sync|show refreshes state/company.yaml from live FIO (cash, permits, buildings, real production efficiency, storage, ships). Run it before answering anything about his current position.
tools/plan_push.py builds/validates PRUNplanner plans from plans/*.yaml (dry run by default; --apply only after Dominik says yes; only [PuGa]-named plans are created/updated; list shows his plans). Specs live in plans/.
tools/chain.py TICKER make-vs-buy cost tree plus sourcing depth of inputs.
tools/book.py order-book ladder (price levels, cumulative units) for one material at one CX.
tools/price.py prices across CX with VWAP, daily volume, and order-book fill price for a quantity (--qty). Library: puga/market.py, puga/fio.py, puga/prunplanner.py.
tools/scan.py DEPTH-AWARE recipe scan (use this): N* buildings the market absorbs, ROI at N=1 and N*, patient prices, ask-walked inputs. Flags: --cx --tier --cogc --skip --hq --budget --min-n --sort roi|total|roi1 --show-thin. Library: puga/saturation.py.
tools/prun_scan.py legacy single-step scan at top-of-book prices; overstates thin markets. Baseline only.
tools/prun_cxarb.py inter-exchange arbitrage per material. Legacy; overstated profit 7 to 11x on thin routes; tools/arb.py replacement is on the roadmap.
puga/econ.py pure formulas ported from PRUNplanner: efficiency stack, workforce satisfaction/consumption, extraction, production I/O, hab optimizer. tests/test_econ.py holds the reference values.

Model policy

Sonnet builds; spawn a bigger model (Agent model: opus|fable) for the review points in docs/decisions.md. Roadmap: docs/roadmap.md.

Key analytic rule: depth matters

PRUNplanner's ROI Overview ranks recipes as if the market absorbs unlimited output (e.g. 0.25 day ROI on a recipe whose whole market fits in 2 buildings). Every opportunity we report must include saturation: max buildings the market can absorb on both the output side (demand, traded volume, order-book walk) and the input side (supply). Report ROI at realistic fill prices, not top-of-book, and total absorbable profit/day.

4.2 KiB Raw Blame History