PuGa

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