dodoxandClaude Sonnet 5
3bbf524ebb
- tools/simulate.py + puga/simulate.py: replica of PRUNplanner's simulator (flows and efficiency verified against screenshots), reports real new capex (planned minus built) - tools/scan.py: staffing variants, freight, HQ/experts, --planet mode, demolish-later, --min-n as a pure market-size filter, --json output - tools/history.py, tools/persistence.py: margin history and short-horizon payback checks - tools/plan_push.py: guarded delete; tools/state.py: syncs to empire/ - README with features and setup; CLAUDE.md made generic - Own-empire material (profile, state, plans, notes) moved to gitignored empire/; generic examples in plans/examples and state/company.example.yaml Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
119 lines
6.6 KiB
Markdown
119 lines
6.6 KiB
Markdown
<h1 align="center">
|
||
<br>
|
||
<img src='./PuGa.png' width="250px">
|
||
<br><br>
|
||
<b>PuGa</b>
|
||
<br><br>
|
||
</h1>
|
||
|
||
A set of tools and know-how for Claude (Claude Code) to assist in the game [Prosperous Universe](https://prosperousuniverse.com), usable by humans too. You ask questions in plain language; Claude answers by running the tools in this repo against live market data and your own company data, instead of guessing.
|
||
|
||
Name origin:
|
||
Plutonium–gallium alloy (Pu–Ga) is a specialized metallic blend of plutonium and gallium primarily used to stabilize the desirable delta (δ) phase of plutonium at room temperature.
|
||
|
||
## How it is meant to be used
|
||
|
||
Open Claude Code in this folder. `CLAUDE.md` is loaded automatically: it tells Claude who the player is, which tools exist, which numbers to trust, and how to answer. Claude also reads `empire/PROFILE.md` (who you are, how you want answers) if you have one. Then just ask, e.g. *"what should I build on Sunday?"*, *"is BHP still worth it?"*, *"simulate my HWP plan"*. Every tool is also a normal command line script, so you can run them yourself.
|
||
|
||
Everything the tools print is an **estimate** from public and personal game data. Prices move; re-run before acting.
|
||
|
||
## Features
|
||
|
||
**Data layer**
|
||
- Cached clients for the FIO REST API and the PRUNplanner API (public game data, order books, price history, your own sites, storage, production, ships, cash).
|
||
|
||
**Market tools**
|
||
- `price`: bid, ask, 7/30-day VWAP, daily volume, supply and demand at every exchange; fill price for a quantity.
|
||
- `book`: order-book ladder with cumulative depth (market-maker orders handled).
|
||
|
||
**Economics engine** (`puga/econ.py`, ported from the PRUNplanner source, which is treated as the source of truth and checked against its own tests and live FIO values)
|
||
- Building efficiency: COGC, HQ, experts, faction bonus, fertility, building condition.
|
||
- Workforce satisfaction and consumption, extraction rates, production per day, housing optimizer.
|
||
|
||
**Finding opportunities**
|
||
- `scan`: ranks every recipe with a depth-aware market model, so it does not recommend recipes whose whole market fits one or two buildings. Fully staffed and understaffed variants, freight cost, HQ/COGC/experts, `--min-n` filter for real markets, a `--planet` mode (extraction, fertility, COGC of a specific planet) and a demolish-later cost.
|
||
- `persistence` and `history`: how long has a margin lasted? Re-prices any opportunity over the exchange history (30/90/180 days), with payback and expected net gain over 7 and 14 days.
|
||
- `chain`: make-versus-buy cost tree with sourcing depth of every input.
|
||
- `arb` (planned) and the legacy `prun_scan` / `prun_cxarb` (kept as a baseline, they overstate thin markets).
|
||
|
||
**Your own position**
|
||
- `state`: syncs `empire/state/company.yaml` from FIO: cash, permits, buildings, real production efficiency, storage and ships.
|
||
- `simulate`: a Python replica of the PRUNplanner simulator (workforce, efficiency, material I/O, profit), verified against screenshots of it. Reads a local plan or a saved plan from your account, and reports the real new capex (planned minus already built).
|
||
- `plan_push`: creates, updates and deletes plans in your PRUNplanner account from small YAML files (examples in `plans/examples/`). Dry run by default; only plans named `[PuGa] ...` can be written or deleted.
|
||
|
||
**Knowledge for Claude** (`CLAUDE.md`, `docs/`)
|
||
- Verified game mechanics, the market-saturation design, a decision log and a roadmap (`docs/`). Everything specific to your own empire (profile, state, plans, notes) lives in the gitignored `empire/` folder, so this repo can stay public.
|
||
|
||
## Setup
|
||
|
||
Requires Python 3.12 or newer and git.
|
||
|
||
```sh
|
||
git clone <repo-url> PuGa
|
||
cd PuGa
|
||
|
||
# 1. virtual environment
|
||
python3 -m venv .venv
|
||
.venv/bin/pip install -r requirements.txt
|
||
|
||
# 2. keys
|
||
cp .env.example .env
|
||
chmod 600 .env
|
||
$EDITOR .env # fill in the values below
|
||
|
||
# 3. optional: the PRUNplanner source used as reference for game mechanics (gitignored)
|
||
tools/refresh_refs.sh
|
||
|
||
# 4. check it works
|
||
.venv/bin/python -m pytest
|
||
.venv/bin/python tools/price.py BHP --cx AI1
|
||
```
|
||
|
||
### `.env`
|
||
|
||
`.env` is gitignored and never committed. Do not paste keys into chat; edit the file.
|
||
|
||
| Variable | What it is |
|
||
|---|---|
|
||
| `FIO_USERNAME` | your in-game / FIO user name |
|
||
| `FIO_REST_KEY` | your FIO REST key (used for your own sites, storage, production, ships, cash on `rest.fnar.net`) |
|
||
| `FIO_API_KEY` | your FIO API (web) key; separate from the REST key, currently unused |
|
||
| `PRUNPLANNER_API_KEY` | API key from your PRUNplanner account, sent as `Authorization: Api-Key <key>` |
|
||
| `COMPANY_CODE` | your company code (used by `tools/state.py` for the first sync) |
|
||
| `DEFAULT_CX`, `DEFAULT_REGION` | default exchange (`AI1` = Antares) and region |
|
||
|
||
Only the public data works without keys (prices, recipes, planets). Your own data needs the FIO extension for the browser client to have uploaded it recently: run `tools/state.py sync` and check the `as_of` time.
|
||
|
||
## Usage
|
||
|
||
```sh
|
||
.venv/bin/python tools/state.py sync # refresh your company state from FIO
|
||
.venv/bin/python tools/scan.py --cogc METALLURGY --experts METALLURGY=2 --min-n 3 --top 20
|
||
.venv/bin/python tools/scan.py --planet ZV-307d --min-n 3 # a specific planet
|
||
.venv/bin/python tools/scan.py --min-n 3 --json rows.json && .venv/bin/python tools/persistence.py rows.json
|
||
.venv/bin/python tools/chain.py KV --qty 13
|
||
.venv/bin/python tools/simulate.py plans/examples/hwp_buildout.yaml --basis vwap30
|
||
.venv/bin/python tools/plan_push.py plans/examples/hwp_buildout.yaml # dry run; add --apply to write
|
||
```
|
||
|
||
## Layout
|
||
|
||
```
|
||
CLAUDE.md entry point for Claude: rules, tool index, source-of-truth order
|
||
docs/ game and toolkit knowledge: mechanics, market model, decisions, roadmap
|
||
puga/ library: data clients, market, economics, saturation, simulator
|
||
tools/ command line tools
|
||
plans/examples/ generic plan specs (also test fixtures)
|
||
state/ company.example.yaml, the shape of your synced state
|
||
tests/ pytest suite
|
||
empire/ (gitignored) YOUR empire: PROFILE.md, state/company.yaml, plans/, docs/ (notes, build plans)
|
||
data/ (gitignored) fetched data cache
|
||
ref/ (gitignored) PRUNplanner source, read-only reference
|
||
```
|
||
|
||
### The `empire/` folder
|
||
|
||
Game knowledge and generic methods go in `docs/`; anything about your own bases, cash, decisions or preferences goes in `empire/`, which is gitignored. `tools/state.py sync` creates `empire/state/company.yaml` (on first use set `COMPANY_CODE` in `.env`). Add `empire/PROFILE.md` yourself: your name, company, how you want answers, agreements with Claude.
|
||
|
||
Not affiliated with Prosperous Universe, FIO or PRUNplanner.
|