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>
This commit is contained in:
Claude Sonnet 5
@@ -0,0 +1,18 @@
|
||||
# Decisions log
|
||||
|
||||
## 2026-09-18 Project plan and working agreements
|
||||
- Goal: agent-first toolkit; Dominik asks, the agent answers by running tools against live data. Not an end-user app.
|
||||
- PRUNplanner source (`ref/`) is the source of truth for mechanics; conflicts with the old handoff resolved in its favour (`docs/mechanics.md`).
|
||||
- Scope: whole universe, default region Antares (CX AI1). Python in `.venv`, secrets in `.env`, git branch `master`. No commits without Dominik asking.
|
||||
- Every reported opportunity must include market saturation (buildings the market can absorb, fill-price ROI, absorbable profit/day). Reason: PRUNplanner's ROI Overview ranks recipes with no depth awareness (e.g. 0.25 day ROI on recipes 2 buildings saturate).
|
||||
- PRUNplanner integration: API key auth (`Authorization: Api-Key <key>`); plans can be created/updated via `/planning/plan/`. Writes only create/update plans prefixed `[PuGa]`; never touch Dominik's other plans; show payload and get a yes before each write.
|
||||
|
||||
## Model and review policy
|
||||
- Default: Sonnet 5 does the building (API plumbing, CLIs, ports, tests).
|
||||
- Bigger model (Agent tool `model: opus` or `fable`, fresh context, brief with files and question) is allowed and expected at these points:
|
||||
1. Saturation model design, before building it, and again on real output.
|
||||
2. Econ formula port (efficiency stack, workforce, hab LP, extraction) checked against PRUNplanner numbers.
|
||||
3. `plan_push` payload handling and the own-plans-only guard.
|
||||
4. Big-money recommendations (e.g. BHP go/no-go, roughly 100k AIC): independent second opinion on the numbers.
|
||||
- If a bigger-model spawn is refused, tell Dominik and ask him to run the review.
|
||||
- Routine tool building is not reviewed by a bigger model.
|
||||
@@ -0,0 +1,96 @@
|
||||
> ARCHIVE. Superseded where it conflicts with docs/mechanics.md (PRUNplanner model). Its measured smelter times (14h55, 12h26) were taken before coffee was supplied and are dropped; use base times / efficiency model.
|
||||
|
||||
# Prosperous Universe: handoff for advising Dominik (company GBI)
|
||||
|
||||
Snapshot date: 2026-09-18. Prices move; re-pull from FIO before quoting numbers.
|
||||
|
||||
## 0. How to work with Dominik
|
||||
- Expert user, wants numbers, tables, ROI per day, no fluff, no moralising. Short answers. Semicolons over dashes; no em dashes.
|
||||
- He plays on browser APEX (free licence). Sends screenshots; read them carefully, they override my assumptions.
|
||||
- When unsure, pull FIO data or search; do not guess commands (mistakes made: NOTS is notifications not notes; CO needs a company code; REP and FLTP do not exist; flight planning is SFC <ship>).
|
||||
- Always state which numbers are estimates and what in-game command would replace them.
|
||||
## 1. Company status (as of 2026-09-18)
|
||||
- Company: greenish-blue Industries, ticker **GBI**. Username dodox. Faction Antares Initiative (AI). Exchange AI1 (Antares Station, ANT, in Antares I / ZV-307). Currency AIC.
|
||||
- Licence: FREE. Consequences: no Local Market ads or player contracts (browse only), max 2 ships in flight, no screen variables, HQ max level 5. One month of PRO converts permanently to BASIC (can accept LM ads and shipping jobs, not post).
|
||||
- Base: **Deimos (ZV-759c, Antares II)**. Metallurgy COGC programme (Antares Metallurgy bonus applies). ~200 of 500 area used. Environment normal: only MCG surcharge (4 MCG per area).
|
||||
- Buildings: 2 EXT (ALO), 5 SME, 4 HB1 (400 beds), pioneers 370/400 required/capacity. Possibly more since; ask.
|
||||
- Smelters run flux recipe: 6 ALO + 1 FLX + 1 C + 1 O -> 4 AL, 14h55 (his measured time). Non-flux: 6 ALO + C + O -> 3 AL, 12h26.
|
||||
- Extractor (SUPERSEDED, see docs/mechanics.md): actual is 28 ALO/day/EXT (factor 0.4 x 70); the 'concentration 28' here was the daily-extraction chip.
|
||||
- Burn (his table): 11.5 batches/day -> ~46 AL/day, uses 69 ALO/day; own ore ~40/day; buys ~29 ALO/day (~6.2k AIC/day). C, O, FLX 11.5/day each. DW, RAT 14.8/day. COF 1.9, PWO 0.7.
|
||||
- Daily inputs ~26k AIC (C ~13.7k is the big one), AL revenue ~56k, margin ~30k/day.
|
||||
- Ships: 2 starter ships, 500 t / 500 m3 cargo, empty mass 828 t. Ship 2 mostly idle.
|
||||
- Fuel measured: ANT -> Deimos one way, nearly empty: 109 SF + 18 FF = 3,241 AIC. FTL is per jump (18 FF), STL scales with mass. Loaded round trip est. 8.5 to 10k AIC.
|
||||
- Cash: ~6k at last report; wealth is in AL stock and daily output.
|
||||
- Base permits: 2, one used (Deimos). Faction sent "expansion package" contract offer (arrives in CONTS, accept manually; deadline starts on accept; core module materials supplied, environment materials not).
|
||||
- Second base decision: **Nike** (ZV-194a, Antares III), parked; see plan.
|
||||
## 2. Current plan (agreed 2026-09-18)
|
||||
### Thesis: Basic Hull Plates (BHP) on Deimos
|
||||
- Recipe: 12 AL + 1 STL + 1 HE -> 4 BHP, 7.2 h, Hull Weld Plant (HWP: 25 area, 40 settlers + 10 technicians, Metallurgy expertise; cost 4 BBH, 6 BDE, 6 BSE, 2 LTA, 4 TRU + 100 MCG ~72k).
|
||||
- Why: technician gate keeps producers few; AI1 supply fell ~3,300 -> ~800 units/month over the year; steel fell 2,700 -> 1,850; BHP rose 4,000 (Mar 2026) -> 6,490 (Sep) at all exchanges (NC1 4,300 bid/5,780 ask, CI1 5,000/6,500). Own AL costs ~565 to make vs 1,210 bid; plant adds ~500 to 675 AIC per AL on top.
|
||||
- Margin history (per batch, AI1 monthly avg): positive 11 of last 14 months; negative Jan to Apr 2026 (steel spike). 12-month avg BHP ~4,700.
|
||||
- Run without technicians: efficiency is proportional to headcount present, not tier-weighted (handbook FAQ confirms; example 20 settlers of 20+30 -> 40%). HWP with 40/50 -> ~80%: ~2.67 batches/day, ~11 BHP, ~32 AL/day.
|
||||
- Net/day at 80%: ~19k at BHP 6,000, ~13.5k at 5,500, ~10k at 5,000. Capex HWP + HB2 ~105k -> 12 to 17%/day. HB3 (~155k, lightweight prefabs) adds only ~25% output -> 3 to 4%/day; conditional.
|
||||
- Market risk: AI1 trades ~40 BHP/day; his 11/day is ~40% of that, so plan to sell at 5,500 to 6,000 with patient asks; CI1/NC1 as outlets. Cluster-wide ~6,000 BHP/month trade.
|
||||
- Exit: sell AL as AL; sunk cost ~105k.
|
||||
- Go/no-go before buying: BHP bid > 5,500 and STL ask < 2,300 (CXOB BHP.AI1, CXOB STL.AI1).
|
||||
### Deimos TODO (ordered)
|
||||
1. HWP + HB2 (~105k) + 3 days imports (~23k). Needs ~106 AL sold. Time completion near the weekly POPR so 40 settlers arrive (reserve pool may fill immediately). Deimos idle settlers ~17k, technicians ~1.3k.
|
||||
- Buy: HWP 4 BBH, 6 BDE, 6 BSE, 2 LTA, 4 TRU, 100 MCG; HB2 2 BBH, 2 BDE, 2 BSE, 2 BTA, 2 TRU, 48 MCG; 8 STL, 8 HE; settler goods 3 days for 40: 6 DW, 7 RAT, 1 KOM, 1 EXO, 1 PT, 1 REP.
|
||||
- Ongoing extra imports at 80%: 2.7 STL, 2.7 HE, 2.0 DW, 2.4 RAT, 0.4 KOM, 0.2 EXO, 0.2 PT, 0.08 REP per day (~7.6k AIC, ~22 t). Ship gets lighter overall (86 t/day less AL outbound).
|
||||
2. FP for DW (~47k: 4 BBH, 4 BDE, 6 BSE, 48 MCG; 40 pioneers, 12 area). 10 H2O -> 7 DW, 2.4 h; buy water at ANT (0.2 t/unit, ~57 AIC), ~3.6k/day net, ~7.8%/day; margin positive every month for a year (1k to 3.5k/day range). FP is Food Industries expertise, no bonus on Deimos.
|
||||
3. HB1 + EXT (~80k: 140 MCG, 18 BSE, 4 BBH, 2 BDE, 1 BTA). Ends the 29 ALO/day purchase; ~6%/day (18% only if smelters were idling).
|
||||
4. HB3 (~155k: 4 LBH, 4 LDE, 4 LSE, 8 LTA, 56 MCG) only if PROD shows HWP ~80% and BHP > 5,500. Technician goods per 100/day: 7.5 DW, 7 RAT, 1 ALE, 0.5 MED, 0.5 HMS, 0.1 SCN, 0.1 SC.
|
||||
5. Grow AL: EXT + 2 SME + HB1 per step (~180k, ~3.6%/day); second HWP when AL > 80/day and BHP still pays.
|
||||
6. HQ level 1 (~56k: 12 MCG, 4 TRU, 6 BBH, 4 BDE, 4 BSE, 2 BTA) for a permit to expand Deimos to 750 area.
|
||||
### Second base (parked): Nike, ZV-194a, Antares III
|
||||
- 1 jump from Antares II; 2 jumps to ANT (via Antares II). Construction COGC. LST 58 (very rich), BOR 4. Env: 0.62 g, 0.04 bar (needs SEA, 1 per area, ~200 AIC each), 30 C. Fertility -1. LM + warehouse exist. Population: ~7k idle pioneers, ~15k idle settlers, ~3.8k idle technicians.
|
||||
- Phase 0: found (25 SEA for core) + HB1 + EXT (~92k) -> ~42 LST/day (estimate, scaled by concentration) sold at ~159 -> ~5.3k/day, ~5.8%/day.
|
||||
- Phase 1: PP1 + HB1 (~76k). PP1 pioneer-only, Construction expertise (bonus). BTA from 1 FE + 50 PE (3.6 h), BSE from 2 LST + 1 FE (6 h), BBH from 1 LST + 2 FE (7.9 h).
|
||||
- Phase 2: BMP + HB1 (~79k). 4 LST + 2 SIO -> 50 MCG, 6 h (Manufacturing expertise, no bonus).
|
||||
- Phase 3 optional: CHP + HB2 (~73k). 1 LST -> 10 FLX, 12 h (20 pio + 60 settlers, Chemistry, no bonus).
|
||||
- Alternatives evaluated and rejected: Harmonia (ZV-896b, Antares IV; fertility -0.10, water 37, Agriculture; carbon via FRM 2 H2O -> 4 HCP then INC 4 HCP -> 4 C; ~268k for ~7.4k/day; better later for food when workforce > 600), Vulcan (FEO 35 but HSE per building, 1.1%/day), Black Mesa (-225 C, 4.6 bar, INS + HSE ~66k per building, TIO 12; 0.5 to 1%/day), Antares II a (85 C, TSH 40k per building), Phobos (Antares I, mild, water 15, SIO 30; fine as a later hub/bottling site), Norwick (YK-649b, Food Industries bonus, 2 jumps).
|
||||
- Expansion contract: accept only when carrying the SEA; found base with BSC ZV-194a.
|
||||
## 3. Game mechanics learned (verified unless marked est.)
|
||||
- Profession only sets starter buildings; faction only sets start planets and community. COLIQ resets company (cooldown). One base per planet per company. Permits: 2 at start; HQ levels add permits; a permit can expand a base 500 -> 750 area; demolishing a core module (no HQ, no buildings, empty storage, ship present) refunds the permit.
|
||||
- Demolition refunds materials: 100% within 1 h, then linear decay with age since last repair; ~0 at 60 days. BSL shows "Reclaimable materials". Repair around 90 days.
|
||||
- MCG per building = 4 x area on normal rocky planets. Environment extras per building: TSH (>75 C, ~40k each), INS (cold, 10 per area, ~200 each), HSE (>2 bar, ~17k each), SEA (<0.25 bar, 1 per area, ~200 each), MGC (low g, ~39k), AEF + BL (gaseous). Core module: 4 LSE, 4 LDE, 4 LTA, 12 PSL, 8 TRU + 100 MCG + env extras. Planet BuildRequirements in FIO list exact extras.
|
||||
- Workforce: efficiency multiplier = workers present / required, headcount-proportional across tiers (handbook). Missing luxuries: PWO alone ~87%, COF alone ~91% (FAQ). Weekly distribution at POPR; reserve pool fills immediately if available; bases keep 75% of workforce between reports. Idle workers still consume.
|
||||
- Consumption per 100 per day: Pioneers 4 DW, 4 RAT, 0.5 OVE, 0.5 COF (lux), 0.2 PWO (lux). Settlers 5 DW, 6 RAT, 0.5 EXO, 0.5 PT, 1 KOM (lux), 0.2 REP (lux). Technicians 7.5 DW, 7 RAT, 0.5 MED, 0.5 HMS, 0.1 SCN, 1 ALE (lux), 0.1 SC (lux). Wages at AI1 asks: pioneer ~23, settler ~39, technician ~71, engineer ~249, scientist ~541 AIC/day.
|
||||
- Housing: HB1 100 pioneers, 10 area (4 BBH, 2 BDE, 2 BSE, 1 BTA + 40 MCG ~33k). HB2 75 settlers, 12 area (~32k). HB3 75 technicians, 14 area (4 LBH, 4 LDE, 4 LSE, 8 LTA ~155k).
|
||||
- Buildings (area, workforce, base cost ex MCG): EXT 25, 60 pio, 16 BSE. SME 17, 50 pio, 4 BBH 4 BDE 6 BSE. FP 12, 40 pio. FRM 30, 50 pio. INC 10, 40 pio. COL 15, 50 pio. RIG 10, 30 pio. BMP 12, 100 pio. PP1 19, 80 pio. WEL 70 pio. PP2 25, 25 pio + 25 sett. CHP 18, 20 pio + 60 sett. GF 27, 80 sett. HWP 25, 40 sett + 10 tech. FS 25, 50 sett. STO 15, no workforce.
|
||||
- Extractor rate est.: scale his Deimos number (20 ALO/day at concentration 28) linearly by concentration; RIG/COL for liquids/gases assumed ~0.7x (unverified). Real rate shows only after building on that planet.
|
||||
- Fertility: farm speed roughly x(1 + fertility); range about -33% to +33%. Deimos -0.34, Harmonia -0.10, Promitor +0.40. COGC programme bonus assumed ~25% for matching expertise (unverified; read PROD batch time vs BUI base time).
|
||||
- Weights (t/unit): H2O 0.2, DW 0.1, RAT 0.21, C 2.25, O 1.14, FLX 0.25, ALO 1.35, AL 2.7, LST 2.73, MCG 0.24, BSE 0.3, SEA 0.15, STL 7.85.
|
||||
- Carbon comes only from INC burning crops (HCP, GRN, MAI). FLX from CHP (1 LST -> 10). GL from GF (2 SIO + NA [+FLX] -> 10 to 12). STL from SME (2 FE + 8 O -> 2 STL) at about its market price.
|
||||
- Markets: player-driven, thin; inter-exchange spreads of 5 to 15% persist because hauling is slow and capital-heavy; MM (market maker) sets floors/caps on some goods (e.g. SDR 100k bid). Prices trend over months, not days. Antares imports worker goods (SC, HMS, ALE, DDT) at a premium.
|
||||
- Fuel: FTL fixed per jump (18 FF starter ship), STL scales with total mass. Jumps: Antares II is hub, 1 jump each to Antares I (ANT station), III (Nike), IV (Harmonia). Exchanges by distance from ZV-759 (FIO units): ANT 47, HRT 391, BEN 423, ARC 492, MOR 642, HUB 1414. Exchange codes: AI1 ANT, NC1 MOR, CI1 BEN, IC1 HRT, NC2 HUB, CI2 ARC.
|
||||
- Shipping ads: 5 AIC/t cross-faction is a lowball; a starter ship needs fee > 2x SFC cost. Free licence cannot accept ads anyway.
|
||||
- Naming planets is a paid support-tier perk, not tied to bases.
|
||||
## 4. APEX commands that matter
|
||||
BS <base> base overview; BSC <planet> found/construct; BSL buildings list + demolish; WF <base> workforce; PROD <base> production lines (efficiency shown); BUI <ticker> building info (generic, no planet extras); PLI <planet> planet info; POPR <planet> population report; SYSI <system>; CX <ex>; CXOB <MAT.EX> order book; CXPC <MAT.EX> chart; CXPO place order; CXOS own orders; LM <planet/station> local market; CONTS contracts; CO <company code> company info incl. rating and faction reputation; USR <name> user profile; SFC <ship> flight planning (fuel and cost); FLT fleet; INV; SCRN screens, ADD; COMG chat; NOTS notifications (not notes). Notes need Refined PrUn (XIT NOTE, XIT TODO). Screen variables exist (June 2026) but PRO only. Commands are case-insensitive.
|
||||
|
||||
## 5. FIO API (rest.fnar.net), public, no auth
|
||||
- /exchange/all: all materials x exchanges with Bid, Ask, Supply, Demand, MMBuy, MMSell (book totals only, no order list). /exchange/{MAT}.{EX}: single, includes BuyingOrders/SellingOrders lists. /exchange/cxpc/{MAT}.{EX}: OHLCV history (filter Interval == DAY_ONE).
|
||||
- /exchange/station: stations with SystemId and ComexCode.
|
||||
- /material/allmaterials: Ticker, Name, Weight, Volume, CategoryName, MaterialId.
|
||||
- /recipes/allrecipes: BuildingTicker, Inputs, Outputs (Ticker, Amount), TimeMs.
|
||||
- /building/allbuildings and /building/{TICKER}: AreaCost, Pioneers..Scientists, BuildingCosts (excludes MCG and env extras), Expertise.
|
||||
- /planet/allplanets/full and /planet/{id}: Gravity, Pressure, Temperature, Fertility, Resources (MaterialId, Factor, ResourceType), COGCPrograms (ProgramType, Start/EndEpochMs), BuildRequirements (incl. MCG and env extras with amounts), HasLocalMarket, HasWarehouse, FactionCode, SystemId. Some fields may be None; guard.
|
||||
- /systemstars: SystemId, NaturalId, Name, PositionX/Y/Z, Connections (jump graph; BFS for routes).
|
||||
- /global/workforceneeds: consumption per 100 per tier.
|
||||
- Private data (his inventory, production, ships) needs the FIO Client extension installed and a username / API key; not set up yet.
|
||||
- Note: some planet resource Factor values differ from in-game display (Deimos H2O shows 20 in FIO vs 14 in UI); prefer in-game numbers when they conflict.
|
||||
## 6. Analysis scripts (delivered as files)
|
||||
- prun_scan.py: scans every recipe; buys inputs at ask, sells outputs at bid at one exchange; subtracts wages; capex = building + housing (MCG 4x area, no env extras, no COGC, no fuel); filters by days of open demand. Flags: --cx, --tier P|S|T|E|Sc, --depth, --sort roi|net|area, --top, --mcg, --understaff (drops tiers, efficiency = staffed share ** --penalty), --cross (buy cheapest CX, sell best CX; not a real trade route).
|
||||
- prun_cxarb.py: pure inter-exchange arbitrage per material; spread per unit / ton / m3; depth proxy min(supply src, demand dst). Flags --from, --to, --minqty, --sort, --top.
|
||||
- Findings 2026-09-18 (AI1): HWP BHP 24% ROI/day (25% without technicians); then settler tier ~8 to 9% (POL DEC, CLF HMS, FS AFR); pioneer tier: PP1 BTA 8.1%, FP DW 7.8%, FRM GRN 6.9%, WEL GV 6.6%, FP RAT ~6%, SME SI 5.9%. Raw-extraction bases galaxy-wide: Nike LST is #2 (5.8%) behind a Moria gold-ore planet. Last-step assembly with MM bids (e.g. surgical drones, 94k in / 100k out) is near-zero after wages.
|
||||
## 7. Price snapshot 2026-09-18 (AI1 ask unless noted)
|
||||
AL bid 1,210 / ask 1,250; ALO 215; C 1,140 (1y avg 1,066; 890 a year ago, ~1,200 since Feb); O 116; FLX 298 (bid 260); STL 2,000 (bid 1,600); HE 247; BHP bid 6,490; DW 151 (bid 150); RAT 232; H2O 59; COF 994; PWO 445; MCG 49; BBH 3,990; BDE 3,690; BSE 2,600; BTA 2,790; TRU 650; LTA 5,400; LBH 6,850; LDE 13,700; LSE 12,800; PSL 5,670; SEA 200; INS 197; HSE 16,900; TSH 39,900; LST 167 (bid 159); SIO 105 to 119; GL 411 to 470; HCP 469; FE 1,000 (bid 975); FEO 116; TI bid 2,110; TIO 338; SF 24.5 (bid 23.8); FF 35 (bid 28.6). Prefabs (BTA, BSE, BBH) are at 1-year highs (+35 to 55% vs annual average).
|
||||
|
||||
## 8. Open items / things to verify in-game
|
||||
- HWP: expertise line in BUI HWP (FIO says Metallurgy); actual efficiency without technicians on PROD; real BHP fill prices.
|
||||
- Extractor LST rate on Nike (after building). SEA count per building on Nike BSC.
|
||||
- COGC bonus size: compare PROD batch time to BUI base time.
|
||||
- Loaded-ship fuel: SFC with full hold.
|
||||
- Whether faction expansion contract has a founding deadline and what it supplies.
|
||||
- Population report timing on Deimos (last one ~2026-09-16).
|
||||
@@ -0,0 +1,48 @@
|
||||
# Mechanics (PRUNplanner-derived; source of truth)
|
||||
|
||||
Source files in `ref/frontend/src/features/planning/calculations/`. Everything here is read from their code, not verified in-game unless marked.
|
||||
|
||||
## Building efficiency = product of factors (`bonusCalculations.ts`)
|
||||
| Factor | Value |
|
||||
|---|---|
|
||||
| Workforce | sum over tiers of (tier headcount / total headcount) x tier satisfaction-efficiency |
|
||||
| COGC programme matching building expertise | x1.25 |
|
||||
| COGC workforce programme (e.g. SETTLERS), building uses that tier | x1.10 |
|
||||
| Corporation HQ | x1.10 |
|
||||
| Expert count in that expertise (1..5) | x(1 + 0.0306, 0.0696, 0.1248, 0.1974, 0.284) |
|
||||
| Fertility (FRM, ORC only) | x(1 + fertility x 10/33); fertility -1 gives 0 |
|
||||
| Faction bonus | x(1 + bonus x m), m = 2 x (-2 x permits_used/permits_total + 3); needs building expertise |
|
||||
|
||||
Faction bonus table: ANTARES electronics 5%; BENTEN manufacturing 5%; HORTUS agriculture 3%, food industries 2%; MORIA metallurgy 2%, construction 3%; OUTSIDEREGION chemistry, fuel refining, resource extraction 2% each.
|
||||
|
||||
## Workforce satisfaction (`workforceCalculations.ts`)
|
||||
- Satisfaction per tier = min(1, capacity/required) x base, base = 0.02 x (1+10/3) x 5 x (1+5/6) = 0.794.
|
||||
- Luxury 1 met: x(1+1/11); luxury 2 met: x(1+2/13); both met gives 1.0. Consistent with handbook (PWO alone ~87%, COF alone ~91%).
|
||||
- Consumption per worker per day = need/100 (table in the file). Consumption uses min(required, capacity) workers. Engineers and scientists needs (DW 10, MED 0.5, FIM/MEA 7, HSS/LC, PDA/WS, VG/NST lux1, GIN/WIN lux2) are in the source, absent from the old handoff.
|
||||
|
||||
## Extraction (`extractionCalculations.ts`)
|
||||
- Cycle times: EXT (mineral) 12 h, COL (gas) 6 h, RIG (liquid) 4.8 h.
|
||||
- Amount per cycle = ceil(daily_extraction x cycle/24h); time scaled so daily rate stays daily_extraction.
|
||||
- Daily extraction = factor x 70 (MINERAL, LIQUID) or x 60 (GASEOUS), factor = concentration as a fraction (backend `gamedata/fio/importers.py`). VERIFIED live: Deimos ALO factor 0.4 -> 28/day per EXT (FIO order 14 ALO / 12.008 h), O 0.3 x 60 = 18, H2O 0.2 x 70 = 14: exactly the resource chips APEX and PRUNplanner show (the chip number IS daily extraction, not concentration). The old handoff note 'FIO H2O 20 vs UI 14' was factor x 100 vs x 70. Efficiency then scales it. PRUNplanner quirk: ceil() on a float 28.0000004 shows 15 per 12h51m instead of 14 per 12h; the daily rate (28) is the same.
|
||||
|
||||
## Production time
|
||||
- Recipe time in a building = time_ms x repeats / efficiency (efficiency shortens time). Batches/day = 24h x buildings / sum(times) (`usePlanCalculation.ts`, `buildingCalculations.ts`).
|
||||
|
||||
## Habitation (`habOptimization.ts`)
|
||||
- Areas: HB1 10, HB2 12, HB3 14, HB4 16, HB5 18, HBB 14, HBC 17, HBM 20, HBL 22.
|
||||
- Combined habs (75 + 75): HBB pioneer+settler, HBC settler+technician, HBM technician+engineer, HBL engineer+scientist.
|
||||
- Optimizer is an LP (min cost, else min area if it does not fit). Reimplement in `puga/econ.py`.
|
||||
|
||||
## Conflicts with the old handoff (resolved in favour of PRUNplanner)
|
||||
1. Handoff says "Antares Metallurgy bonus applies" on Deimos. PRUNplanner: Antares faction bonus is electronics only; metallurgy is Moria. The Deimos benefit is the COGC x1.25, not a faction bonus. Verify in-game via PROD batch time.
|
||||
2. Handoff treats COGC ~25% as unverified; PRUNplanner models it as x1.25 efficiency for matching expertise.
|
||||
3. Impact on BHP thesis: HWP is Metallurgy and Deimos runs an active Metallurgy COGC, so with both luxuries supplied SME/HWP run at about 125% workforce-weighted; HWP at 40/50 headcount is about 0.8 x 1.25 = 100% before expert and HQ. The handoff's 80% output figure ignores COGC.
|
||||
4. Fertility slope is 10/33 (about 0.30 per fertility point), not 1.0.
|
||||
|
||||
## Base recipe times (FIO, confirmed in APEX)
|
||||
- SME AL: non-flux 12h0m (6 ALO + C + O -> 3 AL), flux 14h24m (6 ALO + FLX + C + O -> 4 AL). Actual times = base / efficiency; use the efficiency model, not old hand measurements.
|
||||
|
||||
## Verified against live FIO (2026-09-18)
|
||||
- FIO `/production/{user}` lines carry `Efficiency` (ground truth per building type) and `Condition`. Deimos smelters: 1.3361. Model: COGC 1.25 x expert(2) 1.0696 x condition 0.99936 = 1.33614, i.e. within 0.004%. So PRUNplanner's factor stack is right in-game; add a CONDITION factor (building wear) that PRUNplanner's list omits. Extractors: 0.9993 = condition only (no COGC on resource extraction).
|
||||
- Company cash lives at `/company/code/{ticker}` Balances (AIC 21,950 on 2026-09-18). Permits: `/sites` InvestedPermits 1, MaximumPermits 3 (not 2).
|
||||
- Use `tools/state.py sync` to refresh `state/company.yaml`; it needs the FIO extension to have uploaded recently.
|
||||
@@ -0,0 +1,22 @@
|
||||
# Roadmap
|
||||
|
||||
Legend: [ ] todo, [x] done. Build order matters; each step is usable on its own.
|
||||
|
||||
1. [x] Repo skeleton, git (master), venv, CLAUDE.md, mechanics from PRUNplanner.
|
||||
2. [x] `puga/fio.py`: cached FIO client (TTL per endpoint, keys from `.env`), plus `puga/prunplanner.py` for `api.prunplanner.org/data/*`. Inspect what `exchanges/` adds (VWAP?) vs FIO `/exchange/all`.
|
||||
3. [x] (price + book tools done; cxpc trend history not needed, PRUNplanner has vwap7/30) `puga/market.py` + `tools/price.py`, `tools/book.py`: prices across all CX, trends from cxpc, order-book walk for real fill price at quantity N.
|
||||
4. [x] `puga/econ.py` (22 tests pass, expected values from PRUNplanner's suite): efficiency stack, workforce consumption, hab LP, extraction (port the formulas from `docs/mechanics.md`, with tests against PRUNplanner values).
|
||||
5. [x] (v1 done; see saturation-design.md for refinements) `tools/scan.py` (replaces prun_scan.py): depth-aware ROI. Per recipe report: buildings the market can absorb (output demand + traded volume, input supply), ROI at fill price for N buildings, absorbable profit/day. Filter `--min-buildings`. Both CX-local and universe.
|
||||
5b. [ ] `tools/arb.py` (replaces prun_cxarb.py): inter-CX arbitrage on `market.walk` at real fill size; capital required, fuel/shipping cost from state, profit per trip within cash. Reason: old script uses top-of-book spread x min(supply,demand); on 2 of 4 top hits it overstated profit 7 to 11x (WAI, SCN).
|
||||
6. [x] `tools/chain.py`: full bill of materials, make-vs-buy per node.
|
||||
7. [ ] `tools/whatif.py`: marginal ROI of adding a building to the actual state (uses `state/company.yaml`, efficiency stack, imports).
|
||||
8. [ ] `tools/planet.py`, `tools/found.py`: rank planets for a resource; founding cost including environment extras.
|
||||
9. [ ] `tools/route.py`, `tools/haul.py`: jump graph, fuel, profit per trip.
|
||||
9b. [x] (dry-run default, --apply after user yes) `tools/plan_push.py`: create/update `[PuGa]` plans in PRUNplanner from YAML (Api-Key auth; see decisions.md for guardrails).
|
||||
10. [x] `tools/state.py sync` (sites, production efficiency, storage, ships, cash, permits): inventory, production, ships into `state/`.
|
||||
11. [ ] Docs to fill: `docs/apex.md`, `docs/fio.md`, `docs/playbook.md` (question type -> tool), `docs/decisions.md`.
|
||||
|
||||
## Open questions
|
||||
- PRUNplanner auth is known (`Authorization: Api-Key <key>`). FIO REST and FIO API are separate services with separate keys (Dominik; possibly separate accounts; my earlier "one API" reading was wrong). Keys are in `.env`. Verified 2026-09-18: FIO_REST_KEY works on rest.fnar.net as `Authorization: <key>` (own /sites, /storage etc. readable); FIO_API_KEY gives 401 there, host unknown. PRUNplanner key works (plans 0, empires 1, cx prefs 1 on his account). Still unknown: the OpenAPI spec at https://doc.fnar.net/api.json has no securitySchemes. Probe with read-only calls.
|
||||
- (resolved) PRUNplanner `exchanges/` has vwap_daily/7d/30d and traded volume; merged into `puga/market.py`. Trend history via cxpc still todo.
|
||||
- Extraction: concentration to daily rate formula.
|
||||
@@ -0,0 +1,50 @@
|
||||
# Saturation model design (v1 as implemented; v0 draft below superseded where marked)
|
||||
|
||||
Problem: PRUNplanner's ROI Overview (and our old scan) rank recipes as if the market absorbs unlimited output at top-of-book prices. Result: recipes whose market fits 1 to 2 buildings rank first with absurd ROI (e.g. 0.25 day). We need, per recipe and per CX (or universe), a number of buildings N the market can realistically support, and profit computed at prices you would actually get at that N.
|
||||
|
||||
## Inputs per material and CX (from `puga/market.py`)
|
||||
- Book totals: ask, bid, supply (units on sell side), demand (units on buy side).
|
||||
- Flow: `traded7`, `traded30` = average units traded per day; `vwap7`, `vwap30`.
|
||||
- Live order book (per order price, quantity) via `market.walk`.
|
||||
- MM (market maker) prices `mm_buy` (floor: MM buys at this) and `mm_sell` (cap: MM sells at this), when present. Treat as unlimited depth at that price.
|
||||
|
||||
## Per-building daily quantities
|
||||
q_out[m], q_in[m] per building per day at efficiency e (from `econ.production_io`), including wages/upkeep costs per building.
|
||||
|
||||
## Capacity: how many buildings can each side support
|
||||
1. **Flow cap** (steady state): a producer cannot take more than a share s of the market's traded flow without moving price. `N_flow_out[m] = s * traded_ref[m] / q_out[m]`, with traded_ref = min(traded7, traded30) (conservative), s default 0.25 (parameter). Inputs identical: `N_flow_in[m] = s * traded_ref[m] / q_in[m]`.
|
||||
2. **Stock cap** (short horizon): standing book absorbs a one-time batch: bids for outputs, asks for inputs. Over hold horizon H days (default 7), `N_stock = book_units / (q * H)`. Stock refills through flow, so the effective cap per side is `max(N_flow, N_stock)`? To be decided (flow is the steady-state truth; stock only helps ramp-up). Proposal: cap = N_flow; report N_stock separately as ramp-up buffer.
|
||||
3. **MM override**: if the output has `mm_buy` (floor with unlimited depth) then N_out is unbounded but priced at mm_buy; if an input has `mm_sell` then its price is capped at mm_sell, unbounded depth.
|
||||
4. **N* = floor(min over all outputs and inputs of the capacity)**. If N* < 1: flag "thin", still report ROI at N=1 but exclude from default ranking.
|
||||
|
||||
## Price at N buildings (price impact)
|
||||
- Selling: two modes. `instant`: walk bids for the quantity N*q_out*H, avg price. `patient`: price = vwap7 with a discount d(N) that grows with our share of flow: `d = k * (N*q_out/traded_ref)` (k calibrated from book slope, default so that at share s the discount equals the walk-price deficit). Report both; default ranking uses patient.
|
||||
- Buying inputs: mirror (asks, or vwap7 + premium).
|
||||
- Net per building n(N) = revenue(N) - inputs(N) - wages - amortised capex (optional). Profit curve for N in 1, 2, 4, ... N*. Report N_opt = argmax total profit N * n(N) with n(N) >= a minimum ROI.
|
||||
|
||||
## Output columns
|
||||
recipe, building, N*, limiting material (which side caps), ROI/day at N=1, ROI/day at N_opt, total profit/day at N_opt, capex at N_opt, price used (mode), thin flag.
|
||||
|
||||
## Known weaknesses / questions for review
|
||||
1. Is flow-share s the right primitive? traded volume is noisy and includes our own competitors' equilibrium; what better estimate of "room for a new producer"?
|
||||
2. Existing producers: a market with big standing supply relative to flow signals saturation on the producer side (price pressure). Should supply/flow ratio adjust the price or cap?
|
||||
3. Stock vs flow double counting; horizon H arbitrary.
|
||||
4. Input side and output side are coupled through prices (our buying raises input prices): first-order only.
|
||||
5. Patient price discount model is hand-wavy; alternatives.
|
||||
6. Universe scope: with `--cross` across CX, shipping costs ignored; how to bound.
|
||||
7. Intermediate goods we produce ourselves (chains) are not modelled here (see `tools/chain.py`).
|
||||
|
||||
|
||||
## Review outcome (Opus, 2026-09-18) and what was implemented in `puga/saturation.py` + `tools/scan.py`
|
||||
Verdict: flow-share alone is half right. The standing sell queue (supply / flow, in days) is the dominant signal; order-book walking is a red herring for saturation (selling one day of output at N* barely moves the price); what costs money is the bid vs vwap7 haircut. Implemented:
|
||||
- `tref = min(traded7, traded30)`, with a Poisson lower bound `traded30*(1 - 1.96/sqrt(30*traded30))` when traded30 < 20.
|
||||
- `N_out = (s*tref/q_out) * min(1, T_q*tref/supply) * min(1, demand/(T_d*tref))`, s=0.25, T_q=T_d=7 days. Limiting output reported.
|
||||
- Thin flag: `tref < 3*q_out or demand < 7*q_out` (hard exclude; `--show-thin` overrides). NOTE: borderline. HWP BHP 7.2h variant (13.3/day vs tref 39.2) is flagged thin at exactly this threshold while the 8.4h variant passes; the 3x rule is arbitrary and should be revisited.
|
||||
- Inputs: no flow cap; priced by ask-walk of N*q_in (1 day) and profit falls out negative if the book is shallow.
|
||||
- Output price: `p_patient` = highest ask level whose units-ahead <= T_w*(tref - produced), clamped to [bid, min(vwap7, vwap30, ask)], T_w = 3 days; falls to the bid when we out-produce flow.
|
||||
- MM override only when `mm_buy >= 0.9*bid`: unlimited depth at mm_buy.
|
||||
- Bug fixed: `market.walk` dropped MM orders (`ItemCount: null` means unlimited).
|
||||
Later refinements (not built): supply-feedback fixpoint (our N raises supply), daily snapshot cache and d(supply)/dt, seller-count crowding (distinct `CompanyCode` per side), use `NarrowPriceBand*`/`WwidePriceBand*` to bound prices, 149/370 AI1 materials have traded7 < 5/day so confidence handling matters, cross-CX with freight, chains. MM-priced materials (SP, AIR, CCD, CBS, RED...) trade AT mm_buy so their volume is the MM absorbing, not player demand.
|
||||
|
||||
## Addendum: effective supply (implemented)
|
||||
Stage 1 of `tools/scan.py` uses flow + demand only; stage 2 (shortlist) fetches the ask book and counts only standing sell orders priced <= 1.25 x vwap7 (`saturation.effective_supply`). Reason: DEC at AI1 showed 2,013 units 'queue' of which 1,501 sat at 50,000 (1.5x vwap), which made the raw queue penalty call the market saturated (N=0.38) when the effective queue gives about 1.7.
|
||||
Reference in New Issue
Block a user