dodox/PuGa
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: short README pitch, move tool/setup reference to docs/usage.md

Browse Source 
README keeps the one-paragraph pitch and name origin, adds example
questions and a quick start. The tool index, usage examples, .env table
and layout move to docs/usage.md (now also lists sell tiers, parkcash,
undervalued, ships, lmscan). CLAUDE.md layout line points at it.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
dodox
2026-10-10 22:28:21 +02:00
co-authored by Claude Fable 5.1
parent c902e14107
commit 7837ac6631
3 changed files with 129 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+1 -1
View File
@@ -26,7 +26,7 @@ Agent-first toolkit for advising a Prosperous Universe player. The player asks q
- Scope: whole universe supported; default exchange from `DEFAULT_CX` (AI1 = Antares), `--cx` to change.
## Layout
- `CLAUDE.md` this file; `README.md` for humans.
- `CLAUDE.md` this file; `README.md` for humans (short pitch), `docs/usage.md` the human tool/setup reference.
- `docs/` GAME and toolkit knowledge, safe to publish: `mechanics.md` (verified rules), `saturation-design.md` (market model), `decisions.md` (toolkit decisions and guardrails), `roadmap.md`.
- `empire/` (**gitignored**) OUR game state, nothing here goes public: `PROFILE.md`, `state/company.yaml` (synced from FIO), `plans/` (own plan specs), `docs/` (handoffs, build plans, personal notes).
- `puga/` library; `tools/` CLIs; `plans/examples/` generic plan specs (also test fixtures); `state/company.example.yaml` example state; `tests/`; `data/` (gitignored fetched data cache); `ref/` (gitignored PRUNplanner source).
README.md
+22 -115
View File
@@ -8,131 +8,38 @@
A recursively self-improving harness for Claude and humans for the game [Prosperous Universe](https://prosperousuniverse.com). 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 - and when it catches itself doing the same ad-hoc work by hand more than once, it builds a tool for it instead, so the harness keeps getting sharper the more it's used.
```
what should I build next?
is a second smelter still worth it, or is the AL market full?
simulate adding a CHP to Deimos before I spend anything
how long until Nike runs out of RAT?
where do I post 40 BHP so it actually clears today?
```
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
## What it can do
Open Claude Code in this folder. `CLAUDE.md` is loaded automatically: it tells Claude 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?"*, *"simulate adding a 2nd CHP before I commit to it"*, *"scan for anything I'm not exploiting yet"* - this is how it kept surfacing 25%/day marginal ROIs sitting unbuilt. Claude answers by running the tools against live market data and your own company data, instead of guessing, and can simulate a proposed plan end-to-end (construction cost, workforce, saturation, marginal profit) before you spend a single penny on it. Every tool is also a normal command (`puga <tool>`), so you can run them yourself. Claude can also read and write your plans in PRUNplanner (`puga plan`), so you can check and tweak them in the web UI and Claude picks up your saved changes.
- **Find what to build.** Every recipe, but with market depth: how many buildings the market absorbs, what you'd really get for the output, and whether the margin has held for months or is a spike.
- **Simulate before you spend.** A replica of the PRUNplanner simulator, verified against the real thing. Marginal payback of one more building, and a warning if it overloads your housing.
- **Watch your position.** Cash, permits, buildings, storage and ships synced from FIO. Runway per material, cash-aware shopping lists, multi-base chains with real freight.
- **Trade.** Where to post an ask, how to split it, how long it takes to clear, where idle cash can sit meanwhile.
- **Talk to PRUNplanner.** Reads your plans, writes new ones, picks up edits you make in the web UI. Only touches plans it created.
Everything the tools print is an **estimate** from public and personal game data. Prices move; re-run before acting.
Every number 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).
- `sell`: where to post an ask, expected hours to clear, and a tranche split (aggressive undercut capped at a volume percentile, patient priced under the next competitor tier).
**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; `--consumers` flips it to find deeper downstream products worth chaining into.
- `planet`: ranks planets for a raw resource by extraction factor, with founding cost from real environment-extras materials and jump distance from an existing base (via `route`).
- `route`: jump-distance between two planets/systems, built from FIO's own star-system graph (not a PRUNplanner feature).
- `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).
- `whatif`: marginal ROI of adding to a base you already run (whole-plan diff, not the overstated plan-level ROI); flags any workforce tier the addition newly overloads.
- `buy`: cash-aware shopping list for a plan - construction gap versus your built buildings, plus N days of net operating stock, checked against cash and a reserve.
- `runway`: days of runway per material before a base stalls, from real net consumption, base storage, and any ship already inbound.
- `network`: models a multi-base supply chain (e.g. mine a material at one base, ship it, process it at another) - nets producer surplus against consumer need, charges real freight only on what's moved.
- `plan` (plan_push): reads plans from your PRUNplanner account into small YAML files and writes them back (create, update, delete), so you and Claude can edit the same plan, you in the UI and Claude in code. 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.
## Quick start
```sh
git clone <repo-url> PuGa
cd PuGa
# 1. virtual environment; installs the `puga` command into it
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
source .venv/bin/activate # once per shell, so `puga` is on your PATH
# 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
puga test
puga price BHP --cx AI1
git clone <repo-url> PuGa && cd PuGa
python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
cp .env.example .env # FIO and PRUNplanner keys, see docs/usage.md
claude # open Claude Code here and ask
```
### `.env`
Every tool is also a command: `puga scan`, `puga simulate plan.yaml`, `puga sell BHP 40`. Tool list, setup and layout: [`docs/usage.md`](docs/usage.md). Verified game mechanics and the market model: [`docs/`](docs/).
`.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 `puga state sync` and check the `as_of` time.
## Usage
`puga help` lists the tools; `puga <tool> --help` shows the options.
```sh
puga state sync # refresh your company state from FIO
puga price BHP --cx AI1 # prices, VWAP, volume, fill price for a quantity
puga scan --cogc METALLURGY --experts METALLURGY=2 --min-n 3 --top 20
puga scan --planet ZV-307d --min-n 3 # a specific planet
puga scan --min-n 3 --json rows.json && puga persistence rows.json
puga chain KV --qty 13 # make-vs-buy and input sourcing
puga simulate plans/examples/hwp_buildout.yaml --basis vwap30
puga whatif my_base.yaml --add CHP:1 # marginal ROI of adding to a base you already run
puga buy my_base.yaml --days 1.5 # shopping list, construction gap + N days of stock
puga runway my_base.yaml # days left per material before the base stalls
puga planet FEO --min-factor 0.5 --from ZV-759c # rank planets for a resource, with jump distance
puga plan list # plans in your PRUNplanner account
puga plan pull <uuid> -o my_plan.yaml # read a plan (including your UI edits) into a YAML file
puga plan my_plan.yaml # dry run: validated summary of what would be written
puga plan my_plan.yaml --apply # write it to your account as a [PuGa] plan
puga simulate --uuid <uuid> # simulate the plan as saved in your account
```
## 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.
Your own empire (profile, state, plans, notes) lives in the gitignored `empire/` folder, so the repo stays public.
Not affiliated with Prosperous Universe, FIO or PRUNplanner.
docs/usage.md
+106
View File
@@ -0,0 +1,106 @@
# Usage reference
Every tool runs as `puga <tool> [args]` (or `tools/<tool>.py`). `puga help` lists them, `puga <tool> --help` shows the options. `CLAUDE.md` has the authoritative one-paragraph description of each tool and its caveats; this page is the human-facing index.
## Tools
**Market**
- `price TICKER` bid, ask, 7/30-day VWAP, volume, supply and demand at every exchange; fill price for a quantity.
- `book TICKER` order-book ladder with cumulative depth.
- `sell TICKER QTY [--tight] [--tiers]` where to post an ask, expected time to clear, a tranche split, and whether pricing above market is ever worth the wait.
- `parkcash` where to park idle cash in a buy-low/sell-high position while it has no better use.
- `undervalued` manufactured goods priced below their input cost (buy-and-hold candidates, low return).
**Finding what to build**
- `scan` ranks every recipe with a depth-aware market model: buildings the market can absorb, payback at realistic fill prices, staffed and understaffed variants, freight, planet-specific extraction and COGC (`--planet`).
- `persistence rows.json` re-prices scan rows over 30/90/180 days of history: is the margin a spike?
- `history TICKER` monthly margin history of one recipe.
- `chain TICKER` make-vs-buy cost tree; `--consumers` lists what eats the ticker downstream.
- `planet RESOURCE --from PLANET` ranks planets for a resource by extraction factor, founding cost and jump distance.
- `route A B` jump route between planets or systems.
**Your own position**
- `state sync|show` refreshes `empire/state/company.yaml` from FIO: cash, permits, buildings, efficiency, storage, ships.
- `simulate spec.yaml | --uuid U` replica of the PRUNplanner simulator; reports the real new capex (planned minus built).
- `whatif base.yaml --add CHP:1` marginal payback of adding to a base you already run; flags newly overloaded workforce tiers and charges marginal freight.
- `buy base.yaml --days N` shopping list: construction gap plus N days of net operating stock, checked against cash.
- `runway base.yaml` days per material before the base stalls, including ships already inbound.
- `network chain.yaml` multi-base chain: mine here, ship, process there, with real freight.
- `plan list | pull UUID | spec.yaml [--apply] | delete UUID` read and write plans in your PRUNplanner account. Dry run by default; only `[PuGa]`-named plans are ever written.
**Ships**
- `shiptrip SHIP FROM TO` fuel cost of a trip for one of your ships.
- `shipcost --jumps N ...` the same from explicit physics parameters (gateway routes).
- `lmscan PLANET` live Local Market hauling ads ranked by margin after fuel.
**Legacy**
- `prun_scan`, `prun_cxarb` top-of-book scans kept as a baseline; they overstate thin markets.
## Examples
```sh
puga state sync
puga price BHP --cx AI1
puga scan --cogc METALLURGY --experts METALLURGY=2 --min-n 3 --top 20
puga scan --planet ZV-307d --min-n 3
puga scan --min-n 3 --json rows.json && puga persistence rows.json
puga chain KV --qty 13
puga simulate plans/examples/hwp_buildout.yaml --basis vwap30
puga whatif my_base.yaml --add CHP:1
puga buy my_base.yaml --days 1.5
puga runway my_base.yaml
puga planet FEO --min-factor 0.5 --from ZV-759c
puga plan list
puga plan pull <uuid> -o my_plan.yaml
puga plan my_plan.yaml # dry run
puga plan my_plan.yaml --apply
puga simulate --uuid <uuid>
```
## Setup
Requires Python 3.12 or newer and git.
```sh
git clone <repo-url> PuGa && cd PuGa
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
source .venv/bin/activate # once per shell, so `puga` is on your PATH
cp .env.example .env && chmod 600 .env && $EDITOR .env
tools/refresh_refs.sh # optional: PRUNplanner source as mechanics reference (gitignored)
puga test
puga price BHP --cx AI1
```
### `.env`
Gitignored, 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` | FIO REST key (your sites, storage, production, ships, cash on `rest.fnar.net`) |
| `FIO_API_KEY` | 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 the first `state sync` |
| `DEFAULT_CX`, `DEFAULT_REGION` | default exchange (`AI1` = Antares) and region |
Public data (prices, recipes, planets) works without keys. Your own data needs the FIO browser extension to have uploaded recently; run `puga state sync` and check `as_of`.
## Layout
```
CLAUDE.md entry point for Claude: rules, tool index, source-of-truth order
docs/ game and toolkit knowledge: mechanics, market model, decisions, roadmap, this file
puga/ library: data clients, market, economics, saturation, simulator, shipping
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/
data/ (gitignored) fetched data cache
ref/ (gitignored) PRUNplanner source, read-only reference
```
Game knowledge and generic methods go in `docs/`; anything about your own bases, cash, decisions or preferences goes in `empire/`. `puga state sync` creates `empire/state/company.yaml` (set `COMPANY_CODE` in `.env` first). Add `empire/PROFILE.md` yourself: who you are, how you want answers, agreements with Claude.