Compare commits

...
6 Commits
Author SHA1 Message Date
dodoxandClaude Sonnet 5 12d26c5d68 Docs: register today's fixes, prune completed roadmap items
CLAUDE.md/docs/library.md updated to match the sell.py/parkcash.py/
scan.py changes in the preceding commits. docs/decisions.md gets the
full reasoning trail: the Black-Scholes closed form marked superseded,
the actual backtest entry (BHP/AL touch-probability table) that both
sell.py and library.md already cited but was never written, the
discretization-bias caveat on that backtest, the price-impact-cap and
demolition-value decisions. docs/roadmap.md pruned back to open items
only - finished work is discoverable from CLAUDE.md/library.md/
decisions.md instead of staying listed as a done backlog entry.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-10 23:07:02 +02:00
dodoxandClaude Sonnet 5 3ee26e5a85 Fix wording/tests: marginal_freight docstring, structural simulate() check
- marginal_freight()'s docstring claimed small additions "cost ~0" if
  they fit in slack - the code is actually a continuous amortized rate
  with no such threshold. Fixed the wording to match the real behavior.
- The one known failing test asserted fixed money values from a 2026-09-18
  screenshot against live, drifting market prices - removed that
  assertion (it was testing market drift, not code correctness) but kept
  the exact area check. Replaced with a structural, price-independent
  regression check instead of just deleting: degradation == prod_cost/180
  and plan_cost == prod_cost+infra_cost+cm_cost, asserted directly from
  simulate()'s own fields, holds at any price.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-10 23:06:55 +02:00
dodoxandClaude Sonnet 5 3f67cc7ed5 scan.py: real bid-depth liquidity flag, real-variance flow bound, profit/area
- max_units_at_impact(): walks the LIVE bid book for a genuine, ticker-
  specific instant-exit liquidity check, replacing a flat 25%-of-flow
  guess (a price-vs-volume elasticity regression was tried first and
  abandoned - confounded by demand-driven volume on real data). Surfaced
  as an [exit-thin] WARNING flag, not a hard cap - a single order-book
  snapshot is less reliable than the 30-day flow aggregate that still
  drives n_lim/filtering (using it as a hard cap once silently zeroed
  out a real recipe from one noisy snapshot).
- tref_precise(): real variance of daily traded volume instead of a
  Poisson unit-independence bound, wired into stage 2 only (bounded
  candidate set, cached). Also fixed: was averaging only over trading
  days, overstating flow ~3x for sparse tickers.
- n_out(): dropped the demand-coverage term, which penalized thin
  resting-bid books even though production sells via patient asks taken
  by walk-up buyers with no resting bid at all.
- --sort area: profit/day per tile of TOTAL footprint, now including the
  single-tier hab area a building's workforce drags along (was building
  area only).
- --deprec/--reclaim-frac: amortizes unreclaimed capex, not full capex -
  real FIO reclaim data showed 50-86% returned even at near-100%
  condition, contradicting a 100%->0 decay-curve assumption.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-10 23:06:49 +02:00
dodoxandClaude Sonnet 5 11f54276b3 Add tools/parkcash.py: idle-cash park/flip scan using the empirical model
Where to park idle cash in a buy-low/sell-high position while it has no
better use - scans every ticker for real bid/ask spread and liquidity,
scoring round-trip (buy-dip, sell-recovery) via the same empirical
first-passage model as sell.py's optimal-ask fix, instead of an assumed
random walk. Dropped the universe's top pick from ~94%/day to ~1%/day
with real waits of 19-194+ days under the corrected model. Default
--rate 0.0 matches the tool's own idle-cash premise (sell.py's rate of
0.05 assumes cash is earmarked, which isn't this tool's case).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-10 23:06:40 +02:00
dodoxandClaude Sonnet 5 c4bcc8f42c sell.py: optimal-ask model via empirical first-passage, not random walk
A driftless-random-walk closed form was tried first and backtested wrong
against 3 years of real exchange history (overstated touch probability
2-4x, confounded by discrete daily-VWAP sampling and real mean-reversion).
Replaced with puga.history.empirical_touch(): a non-parametric estimator
measuring first-passage directly from a ticker's own history, conditioned
on current state (trailing-60d z-score) since mean reversion's effect
depends on where price is now, not just move size. Queue-depth (existing
resting quantity) folds in as a deterministic shift of the hitting time,
not a max, ranking by the resulting hit_factor rather than a point
estimate of median days (which created a false cliff at the 50%-touched
threshold). Optional fixed-horizon right-censoring avoids recency bias
in "never reached" samples.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-10 23:06:34 +02:00
dodoxandClaude Sonnet 5 b9b3b9bf4e Document remote-exchange CX order mechanic
Confirmed live: placing a BUY order at a remote exchange (tested NC2/Hubur)
works with no local base, storage, or warehouse rental there beforehand -
the default "Storage Location: Warehouse" option is usable without a
prerequisite rental. Storage fee and FX conversion fee size remain unconfirmed.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-10 23:06:28 +02:00
15 changed files with 804 additions and 91 deletions
+4 -3
View File
@@ -43,12 +43,12 @@ Run as `puga <tool> ...` (e.g. `puga scan --min-n 3`, `puga plan pull <uuid>`);
- `tools/state.py sync|show` refreshes `empire/state/company.yaml` from live FIO (cash, permits, buildings, real production efficiency, storage, ships). - `tools/state.py sync|show` refreshes `empire/state/company.yaml` from live FIO (cash, permits, buildings, real production efficiency, storage, ships).
- `tools/plan_push.py` builds/validates PRUNplanner plans from YAML specs (`plans/examples/`, `empire/plans/`). Dry run by default; `--apply` only after the player says yes; only `[PuGa]`-named plans are created/updated/deleted (`delete <uuid>`, only when asked); `list` shows the account's plans, `pull <uuid> -o file.yaml` reads a plan back into a YAML spec including edits made in the PRUNplanner UI. Workflow: push a plan, the player refines it in the UI and saves, then `pull` / `simulate --uuid` read it back and you continue from there. - `tools/plan_push.py` builds/validates PRUNplanner plans from YAML specs (`plans/examples/`, `empire/plans/`). Dry run by default; `--apply` only after the player says yes; only `[PuGa]`-named plans are created/updated/deleted (`delete <uuid>`, only when asked); `list` shows the account's plans, `pull <uuid> -o file.yaml` reads a plan back into a YAML spec including edits made in the PRUNplanner UI. Workflow: push a plan, the player refines it in the UI and saves, then `pull` / `simulate --uuid` read it back and you continue from there.
- `tools/simulate.py <spec.yaml | --uuid U> [--off EXT,SME] [--basis real|uni30|vwap30|ask|...]` replica of PRUNplanner's simulator (efficiency, workforce, material I/O, profit). Flows and efficiency verified exact vs screenshots; profit within ~2%. The NEW CAPEX line = planned minus already built (from state), the honest payback; ignore the plan-level ROI (PRUNplanner always adds a core module). `--uuid` reads the SAVED plan from the account (UI edits must be saved first). - `tools/simulate.py <spec.yaml | --uuid U> [--off EXT,SME] [--basis real|uni30|vwap30|ask|...]` replica of PRUNplanner's simulator (efficiency, workforce, material I/O, profit). Flows and efficiency verified exact vs screenshots; profit within ~2%. The NEW CAPEX line = planned minus already built (from state), the honest payback; ignore the plan-level ROI (PRUNplanner always adds a core module). `--uuid` reads the SAVED plan from the account (UI edits must be saved first).
- `tools/scan.py` DEPTH-AWARE recipe scan (use this): buildings the market could absorb, ROI for our own size, patient prices, ask-walked inputs. Fully staffed AND understaffed variants by default (`--staffing`), freight netted out (`--trip-cost`, `--cargo`), HQ/COGC/experts/faction, `--planet ID` adds that planet's extraction, fertility and COGC (a planet not in state is a new base: no HQ, permits+1), `--deprec 60` prices demolish-later. `--min-n` is ONLY a noise filter on market capacity (use 3, ideally 10); ROI is always for our own size (`--own`, default 1 building), never at the filtered scale. Below 1 lets sub-building junk in. `--json rows.json` feeds `persistence.py`. Library: `puga/saturation.py`. - `tools/scan.py` DEPTH-AWARE recipe scan (use this): buildings the market could absorb, ROI for our own size, patient prices, ask-walked inputs. Fully staffed AND understaffed variants by default (`--staffing`), freight netted out (`--trip-cost`, `--cargo`), HQ/COGC/experts/faction, `--planet ID` adds that planet's extraction, fertility and COGC (a planet not in state is a new base: no HQ, permits+1), `--deprec 60 [--reclaim-frac 0.65]` prices demolish-later: amortizes the UNRECLAIMED capex (not full capex - real FIO reclaim data shows 50-86% comes back even at near-100% condition, see `docs/decisions.md`) over the holding period. `--min-n` is ONLY a noise filter on market capacity (use 3, ideally 10); ROI is always for our own size (`--own`, default 1 building), never at the filtered scale. Below 1 lets sub-building junk in. `--json rows.json` feeds `persistence.py`. `--sort area` ranks by profit/day per tile of BUILDING area (FIO `AreaCost`, not hab area) - once an existing base's area cap binds, this is the real allocation criterion, not %-yield/payback (a higher-%% recipe needing much more area can lose to a lower-%% one that fits more densely). `--max-impact 10` (stage 2 only) flags `[exit-thin]` when the LIVE bid book can't absorb even 1 day of 1 building's output within that %% (`puga.saturation.max_units_at_impact`) - an INSTANT-DUMP/panic-exit liquidity check, not production price impact (that's what `market`/`lim` already measure via real 30-day flow); a single snapshot (orders change constantly), so it's a WARNING, not folded into `market`/`lim`. Library: `puga/saturation.py`.
- `tools/history.py TICKER` monthly margin history of the recipe producing TICKER; `tools/persistence.py rows.json` re-prices scan rows over history (mean ROI 7/14/30/90/180d, payback, net gain over 7 and 14 days, % days profitable). ALWAYS check persistence before recommending: current margins are often a spike. - `tools/history.py TICKER` monthly margin history of the recipe producing TICKER; `tools/persistence.py rows.json` re-prices scan rows over history (mean ROI 7/14/30/90/180d, payback, net gain over 7 and 14 days, % days profitable). ALWAYS check persistence before recommending: current margins are often a spike.
- `tools/buy.py <spec.yaml|--uuid U> --days N` cash-aware shopping list: construction gap (plan vs empire state's built buildings) plus N days of the plan's NET operating stock (via `simulate()`, so self-produced inputs like AL net against consumption), priced at real fill cost, checked against cash/reserve. Pass a plan covering the WHOLE base for restocking, not just a new addition (see `docs/library.md`). - `tools/buy.py <spec.yaml|--uuid U> --days N` cash-aware shopping list: construction gap (plan vs empire state's built buildings) plus N days of the plan's NET operating stock (via `simulate()`, so self-produced inputs like AL net against consumption), priced at real fill cost, checked against cash/reserve. Pass a plan covering the WHOLE base for restocking, not just a new addition (see `docs/library.md`).
- `tools/sell.py TICKER QTY [--tight]` where to post an ask, expected hours to clear, and a self-contained tranche split: aggressive (undercut) tranche capped at the median 30d-volume quantile (or 80th pct with `--tight`, for when a payment is imminent and stockout risk outweighs a few points of margin), patient tranche priced just under the next competitor tier. `--show-bid` for the instant-bid comparison (off by default; usually worse). - `tools/sell.py TICKER QTY [--tight]` where to post an ask, expected hours to clear, and a self-contained tranche split: aggressive (undercut) tranche capped at the median 30d-volume quantile (or 80th pct with `--tight`, for when a payment is imminent and stockout risk outweighs a few points of margin), patient tranche priced just under the next competitor tier. `--show-bid` for the instant-bid comparison (off by default; usually worse). `--tiers [--rate R]` answers "is it ever worth pricing above the current market": combines queue-depth days (real resting quantity, within the traded range) with an EMPIRICAL first-passage estimate from the ticker's own multi-year price history (no random-walk assumption - a driftless-walk closed form was tried first and backtested wrong, see `docs/decisions.md`'s "Optimal ask price" entry), via max (the binding constraint). `rate` should be the player's REALIZED capital growth rate (read off their equity-growth chart, default 0.05), not a theoretical build ROI. Library: `puga/history.py::empirical_touch()`.
- `tools/network.py <chain.yaml>` models a MULTI-BASE chain (e.g. mine LST at Nike, ship it, make BSE at Deimos): simulates each base, nets a transferred material's producer-surplus against consumer-need, charges real freight only on what's moved (`puga/network.py`). Spec and worked example in `plans/chains/`. `cm_free: true` per base for a new founding covered by a Core Module Kit. profit/day per base is the WHOLE plan, not the marginal addition - diff against the base's plan without the addition for a true marginal ROI. - `tools/network.py <chain.yaml>` models a MULTI-BASE chain (e.g. mine LST at Nike, ship it, make BSE at Deimos): simulates each base, nets a transferred material's producer-surplus against consumer-need, charges real freight only on what's moved (`puga/network.py`). Spec and worked example in `plans/chains/`. `cm_free: true` per base for a new founding covered by a Core Module Kit. profit/day per base is the WHOLE plan, not the marginal addition - diff against the base's plan without the addition for a true marginal ROI.
- `tools/whatif.py <before.yaml> [--add BUILDING:AMOUNT[:RECIPE]] [--infra HB1:+1] [--after after.yaml]` marginal payback of adding to a base you already run (whole-plan diff, same rule as buy/runway - pass the WHOLE base, not just the addition). `--add` mutates a copy of `before` in-memory (reuses an existing building's recipe if omitted, e.g. `--add POL:1`); `--after` takes a second full spec instead. Flags any workforce tier the addition newly overloads (vs. a pre-existing one, which it won't flag) - this is what caught the PP2/pioneer-housing and 2nd-CHP/pioneer-housing surprises by hand before this tool existed. Charges marginal freight too (real fuel model, CX-to-planet, via `puga.shipping`): only the EXTRA round trips this addition needs beyond the base's existing traffic, so a small addition riding along on already-necessary hauls correctly costs ~0, while one that meaningfully adds to shipped tonnage doesn't get a free pass - this is what would catch a recipe whose ROI looks great only because its freight cost was left out. - `tools/whatif.py <before.yaml> [--add BUILDING:AMOUNT[:RECIPE]] [--infra HB1:+1] [--after after.yaml]` marginal payback of adding to a base you already run (whole-plan diff, same rule as buy/runway - pass the WHOLE base, not just the addition). `--add` mutates a copy of `before` in-memory (reuses an existing building's recipe if omitted, e.g. `--add POL:1`); `--after` takes a second full spec instead. Flags any workforce tier the addition newly overloads (vs. a pre-existing one, which it won't flag) - this is what caught the PP2/pioneer-housing and 2nd-CHP/pioneer-housing surprises by hand before this tool existed. Charges marginal freight too (real fuel model, CX-to-planet, via `puga.shipping`): a CONTINUOUS amortized rate (extra tonnage/cargo-hold x round-trip cost), scaling with the addition's own tonnage, not a step function - a small addition adds a small continuous freight cost, not exactly zero, and a recipe whose ROI looks great only because its freight cost was left out still gets caught.
- `tools/runway.py <spec.yaml|--uuid U> [--no-inbound]` days of runway per material before a base stalls: real NET consumption via `simulate()` (self-produced inputs excluded), base storage, PLUS (by default) any ship currently flying to that planet, auto-detected from live flight data (`tools/state.py` tags each ship with its flight origin/destination). Pass the WHOLE base plan (see `docs/library.md`). - `tools/runway.py <spec.yaml|--uuid U> [--no-inbound]` days of runway per material before a base stalls: real NET consumption via `simulate()` (self-produced inputs excluded), base storage, PLUS (by default) any ship currently flying to that planet, auto-detected from live flight data (`tools/state.py` tags each ship with its flight origin/destination). Pass the WHOLE base plan (see `docs/library.md`).
- `tools/undervalued.py [--cx AI1] [--min-vol 5] [--top 20]` manufactured goods currently priced below implied production cost - buy-and-hold-for-reversion candidates, not build candidates. **Expected ROI is much lower than production builds** (~0.10-0.24%/day backtested, vs 14-29%/day for the builds this toolkit recommends) - only worth it for excess idle capital once better-yielding builds are exhausted. Library: `puga/undervalued.py`. - `tools/undervalued.py [--cx AI1] [--min-vol 5] [--top 20]` manufactured goods currently priced below implied production cost - buy-and-hold-for-reversion candidates, not build candidates. **Expected ROI is much lower than production builds** (~0.10-0.24%/day backtested, vs 14-29%/day for the builds this toolkit recommends) - only worth it for excess idle capital once better-yielding builds are exhausted. Library: `puga/undervalued.py`.
- `tools/chain.py TICKER` make-vs-buy cost tree plus sourcing depth of inputs. `--consumers` flips it: what recipes EAT this ticker as an input, with each output's market depth - for "is there a deeper downstream product worth chaining into" questions (e.g. checking BOR/BSE/BBH for further processing). - `tools/chain.py TICKER` make-vs-buy cost tree plus sourcing depth of inputs. `--consumers` flips it: what recipes EAT this ticker as an input, with each output's market depth - for "is there a deeper downstream product worth chaining into" questions (e.g. checking BOR/BSE/BBH for further processing).
@@ -56,6 +56,7 @@ Run as `puga <tool> ...` (e.g. `puga scan --min-n 3`, `puga plan pull <uuid>`);
- `tools/route.py <from planet/system> <to planet/system>` jump-distance route (not a PRUNplanner feature - built from FIO's `/systemstars` graph, Dijkstra by straight-line ly since that's what FTL fuel/time scale with, jump count reported alongside). Accepts planet natural IDs, system natural IDs, or names. Library: `puga/route.py`. - `tools/route.py <from planet/system> <to planet/system>` jump-distance route (not a PRUNplanner feature - built from FIO's `/systemstars` graph, Dijkstra by straight-line ly since that's what FTL fuel/time scale with, jump count reported alongside). Accepts planet natural IDs, system natural IDs, or names. Library: `puga/route.py`.
- `tools/shiptrip.py SHIP FROM TO [--v0 X --v1 Y]` the simple ship-trip tool: give a ship registration + start + stop, it works out jumps/charges/landing fuel itself via `tools/route.py`'s jump graph and reports fuel cost (defaults to max sliders). Direct-jump routes only - an unconnected pair means gateway-only, and it tells you exactly what to read off the live APEX Ship Flight Control screen (the LOCK fee - genuinely not available via FIO/PRUNplanner, confirmed by inspecting both) and what to run instead (`tools/shipcost.py`). Warns if the given ship's live specs (FIO `/ship/ships/{user}`) don't match the calibrated hull/reactor. - `tools/shiptrip.py SHIP FROM TO [--v0 X --v1 Y]` the simple ship-trip tool: give a ship registration + start + stop, it works out jumps/charges/landing fuel itself via `tools/route.py`'s jump graph and reports fuel cost (defaults to max sliders). Direct-jump routes only - an unconnected pair means gateway-only, and it tells you exactly what to read off the live APEX Ship Flight Control screen (the LOCK fee - genuinely not available via FIO/PRUNplanner, confirmed by inspecting both) and what to run instead (`tools/shipcost.py`). Warns if the given ship's live specs (FIO `/ship/ships/{user}`) don't match the calibrated hull/reactor.
- `tools/shipcost.py [--jumps N --charges N] [--v0 X --v1 Y] [--gateways N --lock-fee AMOUNT:CURRENCY] [--to PLANET]` the explicit/manual version: fuel/AIC cost of a ship trip from physics parameters you already know (jump count, slider values, gateway LOCK fees read off the live game) - use `tools/shiptrip.py` instead if you just want "ship X from A to B". Landing fuel is a measured-planet lookup via `--to`, independent of whether the route used jumps or gateways. Both tools scoped to this account's one hull/reactor (blueprint BP-STRT-0000, shared by both ships AVI-07JFB/AVI-07JFC); open caveats (v0 relative to current fuel load, landing fuel confounded with gravity/distance, no second hull to cross-check) are in `puga/shipping.py`'s module docstring - don't trust magnitudes beyond what's there. Raw calibration data (APEX DOM reads, 2026-10-09): `empire/data/shipping_calibration/`. Also wired into `tools/network.py`'s freight cost (direct-jump transfers use the real model; gateway transfers need an explicit `trip_cost` in the chain YAML, else a 9250 AIC fallback). Library: `puga/shipping.py` (`trip_fuel()`, `round_trip_cost()`). - `tools/shipcost.py [--jumps N --charges N] [--v0 X --v1 Y] [--gateways N --lock-fee AMOUNT:CURRENCY] [--to PLANET]` the explicit/manual version: fuel/AIC cost of a ship trip from physics parameters you already know (jump count, slider values, gateway LOCK fees read off the live game) - use `tools/shiptrip.py` instead if you just want "ship X from A to B". Landing fuel is a measured-planet lookup via `--to`, independent of whether the route used jumps or gateways. Both tools scoped to this account's one hull/reactor (blueprint BP-STRT-0000, shared by both ships AVI-07JFB/AVI-07JFC); open caveats (v0 relative to current fuel load, landing fuel confounded with gravity/distance, no second hull to cross-check) are in `puga/shipping.py`'s module docstring - don't trust magnitudes beyond what's there. Raw calibration data (APEX DOM reads, 2026-10-09): `empire/data/shipping_calibration/`. Also wired into `tools/network.py`'s freight cost (direct-jump transfers use the real model; gateway transfers need an explicit `trip_cost` in the chain YAML, else a 9250 AIC fallback). Library: `puga/shipping.py` (`trip_fuel()`, `round_trip_cost()`).
- `tools/parkcash.py [--min-spread X] [--min-trade-days N] [--rate R] [--top N]` where to park idle cash as a buy-low/sell-high position (not a build) while ships are busy or cash has no better use right now - scans every ticker for a big bid/ask spread AND real trading liquidity (trade-days/gap over a calendar window - a huge spread with few trading days is a stale-quote trap, confirmed by hand: AST showed a 130% spread but its resting ask had gone stale after a 60% real price crash). Round-trip wait/value is EMPIRICAL (`puga.history.empirical_touch`, same model as `tools/sell.py --tiers`), not an assumed random walk - a driftless-walk version was tried and backtested wrong (overstated reachability 2-4x vs 3 years of real data, see `docs/decisions.md`). This dropped the whole universe's top pick from ~94%/day to ~1%/day with real waits of 19-194+ days - treat any number from the old model as stale. `--rate` defaults to 0.0 (matches the idle-cash premise; pass your realized growth rate if this cash IS earmarked) and shows up as a separate `discounted_pct` column (margin% x real odds both legs ever happen) alongside the simple non-compounding `daily_pct` used for ranking. Library: `puga/parkcash.py`.
- `tools/lmscan.py PLANET [--direction source|destination] [--min-margin X]` live Local Market hauling-ad scan (FIO, public/no-auth - real player-posted freight jobs, not the CONTD player-contract system), ranked by margin after real fuel cost (`puga.shipping.leg_cost`). One-way cost only - margin assumes the next job is picked up near the destination, not an empty flight home. A small measured gateway-fee table covers ANT<->HRT/BEN; other gateway routes can't be priced (LOCK fee isn't available via any API). Library: `puga/contracts.py`. - `tools/lmscan.py PLANET [--direction source|destination] [--min-margin X]` live Local Market hauling-ad scan (FIO, public/no-auth - real player-posted freight jobs, not the CONTD player-contract system), ranked by margin after real fuel cost (`puga.shipping.leg_cost`). One-way cost only - margin assumes the next job is picked up near the destination, not an empty flight home. A small measured gateway-fee table covers ANT<->HRT/BEN; other gateway routes can't be priced (LOCK fee isn't available via any API). Library: `puga/contracts.py`.
- `tools/price.py` prices across exchanges with VWAP, volume, fill price for a quantity; `tools/book.py` order-book ladder. - `tools/price.py` prices across exchanges with VWAP, volume, fill price for a quantity; `tools/book.py` order-book ladder.
- `tools/prun_scan.py`, `tools/prun_cxarb.py` legacy top-of-book scans; overstate thin markets. Baseline only. `tools/arb.py` replacement is on the roadmap. - `tools/prun_scan.py`, `tools/prun_cxarb.py` legacy top-of-book scans; overstate thin markets. Baseline only. `tools/arb.py` replacement is on the roadmap.
+138
View File
@@ -17,6 +17,144 @@
- If a bigger-model spawn is refused, tell the player and ask them to run the review. - If a bigger-model spawn is refused, tell the player and ask them to run the review.
- Routine tool building is not reviewed by a bigger model. - Routine tool building is not reviewed by a bigger model.
## 2026-10-10 Optimal ask price: first-passage-time (Black-Scholes), not order-book depth
**SUPERSEDED same day - see "Black-Scholes model backtested wrong" below. The closed form here
(`daily_log_vol()`, a driftless-random-walk assumption) is no longer what `tools/sell.py --tiers`
uses; kept for the reasoning trail, not as current guidance.**
- The naive model ("units ahead of me in the book ÷ historical daily volume = days to clear")
is WRONG: it assumes the book is static (no one else reprices, cancels, or adds orders while
you wait) and that historical trade volume at normal prices still applies at a resting ask far
outside the recently-traded range. Tried first, broke immediately: fed a fat-finger 1,000,000
AIC ask the same reachability as the real book, "confirming" it as optimal.
- Correct model: whether the market ever pays price P is governed by price DIFFUSION, not queue
depth. Model ln(price) as a driftless random walk with the ticker's own measured daily
log-return volatility sigma (deliberately no drift - same "don't model trend" rule as
`puga/parkcash.py`), and ask for the discounted value of the first time it diffuses up to P.
Closed form (standard Brownian-motion hitting-time Laplace transform):
y = ln(P/s0), rho = ln(1 + rate), D(P) = P * exp(-(y/sigma) * sqrt(2*rho)) for P > s0
D(P) = P for P <= s0
`rate` is the player's own REALIZED capital growth rate (opportunity cost of the delay - see
below), not a theoretical marginal-build ROI.
- ln(D) is LINEAR in y, so there is no interior optimum: D is strictly decreasing past the
current price (sell near top of book / at the last traded price wins) whenever
`sigma < sqrt(2*rho)`, and rises without bound (a degenerate corner case, not real free money)
otherwise. Checked against this account's real tickers (AL 2.5%/day, BHP 8.1%/day, DEC
10.8%/day vol, all against a 5%/day rate -> threshold ~31%/day): every one is comfortably in
the "sell now dominates" regime. Treat a result where climbing pays as a signal to double
check sigma/rate inputs, not as license to post a speculative high ask.
- Implementation: `puga.history.daily_log_vol()` (pooled variance estimator, scales each
consecutive trading-day gap's squared log-return by its elapsed days so sparse tickers don't
understate how far price can move between trades) + `tools/sell.py --tiers --rate R`.
- This also resolved the earlier "what discount rate" question: use the player's REALIZED equity
growth rate (read off their own in-game equity-growth chart, ~5%/day as of 2026-10-10), not the
scan/build tools' marginal per-building ROI figures (14-29%/day) - those are a ceiling on one
marginal building at current scale (capped by permits, workforce-arrival delay, and market-
depth saturation the moment you scale), not what a freed-up dollar actually compounds at. The
realized rate already nets out all of that friction, which is exactly what a discount rate for
"should I wait for a better price" needs to reflect.
## 2026-10-10 Black-Scholes closed form backtested wrong - empirical model instead
- Tested the driftless-random-walk assumption above against this account's real exchange history
(BHP: 802 trading days, sigma 7.39%/day; AL: 995 days, sigma 4.42%/day). Model predicts
P(touch level k*sigma*sqrt(T)) = 2*(1-Phi(k)), independent of T - the scale-invariance signature
of a true random walk. Measured the real empirical touch frequency for the same (k, T) pairs:
| k | model pred | BHP empirical (T=7/14/30/60d) | AL empirical (T=7/14/30/60d) |
|-----|-----------:|----------------------------------|-----------------------------------|
| 0.5 | 61.7% | 16.6% / 18.0% / 17.5% / 20.1% | 32.6% / 33.9% / 32.4% / 40.1% |
| 1.0 | 31.7% | 8.8% / 8.0% / 8.2% / 7.9% | 9.2% / 10.2% / 10.8% / 16.7% |
| 1.5 | 13.4% | 4.1% / 3.8% / 0.1% / 0.0% | 3.9% / 3.9% / 4.4% / 2.7% |
| 2.0 | 4.6% | 2.0% / 1.2% / 0.0% / 0.0% | 1.9% / 1.5% / 2.0% / 0.0% |
| 3.0 | 0.3% | 0.5% / 0.0% / 0.0% / 0.0% | 0.7% / 0.5% / 0.0% / 0.0% |
Model overstates touch probability by roughly 2-4x at low-moderate k, consistently across both
tickers. Scale-invariance partially holds at low k (flat across T, locally random-walk-like
short-term) but breaks down at higher k/longer T (empirical rate COLLAPSES faster than the model
past k=1.5, instead of staying flat) - the signature of mean reversion: real prices are anchored
to production cost/supply-demand equilibrium, not free-floating, so they wander less far over
longer horizons than a pure random walk would.
- The 2-4x figure overstates how much of this is mean reversion specifically: touches were
measured on daily VWAPs, a discrete sample of a continuous path, and the model's prediction
assumes continuous monitoring. Discrete sampling can only miss touches (an intraday spike that
reverts before the next VWAP looks like "no touch"), biasing the measured gap upward especially
at short horizons (k=0.5, T=7 - standard discrete-barrier corrections put this at roughly
0.58*sigma*sqrt(step) per sampling interval, shrinking as the horizon grows). The k>=1.5/T>=30
COLLAPSE is not explained by discretization (a roughly constant/shrinking effect, not a
progressive one) - that part is real mean reversion.
- Consequence: the model's absolute numbers are upper bounds, not honest estimates - directionally
conservative (it already said "don't climb the book," and the true probability of ever
profitably climbing is even lower than it claimed) but not quantitatively trustworthy.
- Replaced with `puga.history.empirical_touch()`: a non-parametric estimator measuring first-
passage directly from the ticker's own full multi-year history (every historical start day,
first time the price actually moved by the target amount, right-censored samples contribute 0
rather than being excluded) - no assumed distribution, so whatever mean-reversion/fat-tails/etc.
the real data has shows up directly. Inherits the same daily-VWAP discretization conservatism as
the backtest above (a resting ask can fill on an intraday high the VWAP series never shows) - so
it also leans a little more toward "sell now" than fully warranted, not corrected for. Used by
`tools/sell.py --tiers` (combined with queue-depth as a deterministic shift of the hitting time,
not a max - ranking by the resulting hit_factor, not a point estimate of median days) and
`puga/parkcash.py` (two sequential legs: buy-dip,
sell-recovery).
- Refined further: the unconditional version above still averages over EVERY historical start day,
which answers "how often does this ticker move by y from an arbitrary day" - but mean reversion
specifically means the answer depends on where price is NOW relative to its own recent trend.
Conditioned on state instead (`empirical_touch(..., condition_on_state=True)`, the default):
only start days whose z-score against a trailing 60-day mean is within +/-0.5 of TODAY's are
used, falls back to every start day if there's not enough history to compute today's z-score or
the match band is empty. Stays non-parametric (no fitted mean-reversion speed/strength). Real
effect confirmed on DEC (`tools/parkcash.py`): round-trip wait dropped from 19 days
(unconditional) to 3 days once conditioned on DEC's actual current state - a big, real
difference, not a rounding adjustment.
## 2026-10-10 Price-impact cap: real book depth, not a flat 25%-of-flow guess
- `puga/saturation.py`'s `S_SHARE=0.25` capped planned output at a flat 25% of a ticker's traded
flow, regardless of how deep or thin that specific market's standing bid book actually is -
never estimated how much price actually falls as supply rises, flagged by review.
- Tried first: a day-over-day regression of d(log price) on d(log volume) per ticker, the
textbook first-order elasticity estimate. Real data killed it: BHP -0.009, AL +0.004,
DEC +0.038, KV +0.007 - near zero and inconsistently signed. Cause: daily volume spikes in this
market are mostly DEMAND-driven (more buyers -> more volume AND flat/higher price), which
swamps and often reverses the sign of the SUPPLY-side effect we actually want. Shipping this
would have been worse than the flat guess (could tell you adding supply raises price).
- Fix: `puga.saturation.max_units_at_impact()` walks the LIVE bid book (same mechanics as
`puga.market.walk()`) and returns how many units you could sell before the realized price
degrades more than `--max-impact`%% (default 10) below vwap7/bid - a real, ticker-specific
measure, no regression, no confounding.
- Caveat, caught immediately when first wired as a hard `min()` cap alongside the flow-based
check: a live order book is a SINGLE SNAPSHOT - standing bids get added/withdrawn constantly,
same class of problem already found and fixed twice this session (`sell.py`'s queue model,
`parkcash.py`'s driftless walk), and we have no historical book-snapshot log to tell a
structurally-thin book from an unlucky instant. Using it as a hard cap let one noisy snapshot
silently zero out `n_lim` and hide a recipe entirely (happened to KV: flow-based n_lim 10.6 ->
0.0 purely from the snapshot). The 30-day flow figure (`tref_precise`) is the more reliable
signal precisely because it aggregates many real days, not one instant.
- Final design: `n_lim`/filtering stays flow-only (unchanged, reliable). `max_units_at_impact()`
surfaces as an `[exit-thin]` WARNING flag instead (can the live book absorb an instant dump of 1
day of 1 building's output right now, if cash were needed immediately?) - a panic-exit liquidity
check, NOT a production price-impact measure (that's `market`/`lim`, which price via patient
asks, the real selling mechanism) - visible, not silently filtering. Caught real signal on
several recipes (KV, SC, HER, TRN, NL, RG all flagged) without hiding any of them.
## 2026-10-10 Demolition value: flat reclaim fraction, not a time-decay curve
- `tools/scan.py --deprec` assumed building value decays LINEARLY to 0 over ~60 days (a guess,
never checked against real data). Checked it: pulled this account's live FIO reclaimables
(`/rain/userplanetbuildingreclaimables/{user}`) for all 8 owned building types, normalized by
built-count, and compared to real construction cost (FIO `BuildingCosts` at live ask prices).
- Result: reclaim fraction is 50-86% (CHP 68.7, EXT 86.5, HB1 58.3, HB2 50.9, HWP 73.1, POL 78.0,
SME 74.6; CM a low outlier at 7.4%, likely a core-module-specific rule) - but EVERY one of these
buildings is at ~99.7-99.9% live condition (this account's base is young). If reclaim really
decayed from ~100% toward 0 over 60 days, a near-perfect-condition building should reclaim close
to 100%, not 50-86%. This contradicts the decay-curve premise and is more consistent with a
roughly FLAT, material-dependent reclaim fraction that doesn't move much with condition in the
normal operating range.
- Can't fully settle the shape - no aged/low-condition building exists in this account to check
the other end of the curve, so this is suggestive, not conclusive (single base, narrow condition
range, small sample).
- Fix: `scan.py --deprec` now amortizes `capex * (1 - --reclaim-frac)` (the UNRECLAIMED portion)
over the holding period, not full capex. `--reclaim-frac` defaults to 0.65 (the mean of the 7
non-CM observations) - still a rough placeholder, not a calibrated curve; re-check once an aged
building exists to compare against.
## 2026-10-09 Drop "ROI/day %" terminology ## 2026-10-09 Drop "ROI/day %" terminology
- `profit/day ÷ new_capex` (what tools were calling "ROI/day X%") is just 1/payback_days rewritten as a percentage. It is NOT a compoundable rate of return - there's no reinvestment mechanism, and every opportunity here is capacity/market-limited (saturation), so it can't be extrapolated or annualized like an interest rate. - `profit/day ÷ new_capex` (what tools were calling "ROI/day X%") is just 1/payback_days rewritten as a percentage. It is NOT a compoundable rate of return - there's no reinvestment mechanism, and every opportunity here is capacity/market-limited (saturation), so it can't be extrapolated or annualized like an interest rate.
- Report **payback in days** as the primary number everywhere. A "%/day" figure, if shown at all, must be labelled as simple/non-compounding and never compared to a real yield/interest rate. - Report **payback in days** as the primary number everywhere. A "%/day" figure, if shown at all, must be labelled as simple/non-compounding and never compared to a real yield/interest rate.
+28 -3
View File
@@ -39,9 +39,15 @@ EOF
per-tier need table), `HAB_CAP`/`HAB_AREA`, `TIERS`. This is what you use for "what if I per-tier need table), `HAB_CAP`/`HAB_AREA`, `TIERS`. This is what you use for "what if I
understaff this building" or "what's the real wage bill for N heads" — the CLI tools only understaff this building" or "what's the real wage bill for N heads" — the CLI tools only
expose fixed slices of this. expose fixed slices of this.
- **`puga.saturation`** — `tref`, `n_out`, `p_patient`, `effective_supply`, `is_thin`: the - **`puga.saturation`** — `tref` (cheap, Poisson-bounded, for stage-1 screening), `tref_precise`
depth/persistence primitives behind `scan.py`. Reuse these instead of re-deriving a "how many (real daily-volume variance, for a bounded candidate set), `n_out` (flow x queue, NO demand
buildings can the market take" estimate by hand. term - thin resting-bid books don't disqualify a market sold into via patient asks), `p_patient`,
`effective_supply`, `is_thin` (demand still checked here, independently), `max_units_at_impact`
(real live bid-book depth cap - how many units before realized price degrades past a threshold;
replaced a flat 25%-of-flow guess after a naive price-vs-volume elasticity regression on real
data came back near-zero/wrong-signed, see `docs/decisions.md`): the depth/persistence
primitives behind `scan.py`. Reuse these instead of re-deriving a "how many buildings can the
market take" estimate by hand.
- **`puga.simulate`** — `simulate(plan, recipes, buildings, resources, fertility, price, ...)`: - **`puga.simulate`** — `simulate(plan, recipes, buildings, resources, fertility, price, ...)`:
the PRUNplanner-simulator replica. Reuse this for anything plan-shaped rather than reimplementing the PRUNplanner-simulator replica. Reuse this for anything plan-shaped rather than reimplementing
efficiency/workforce/flows again. efficiency/workforce/flows again.
@@ -63,6 +69,25 @@ EOF
(ship+from+to, auto-computes everything via `puga.route`), `tools/shipcost.py` (explicit (ship+from+to, auto-computes everything via `puga.route`), `tools/shipcost.py` (explicit
jumps/sliders/gateway-fees, for when you already know the breakdown). Raw calibration data: jumps/sliders/gateway-fees, for when you already know the breakdown). Raw calibration data:
`empire/data/shipping_calibration/`. `empire/data/shipping_calibration/`.
- **`puga.parkcash`** — `scan(cx="AI1", min_spread_pct=20.0, days=30, rate=0.05)`: every ticker
with a live quote and a big bid/ask spread, scored on real trading liquidity
(`puga.history.trading_days()`/`trade_gaps_days()`) and an EMPIRICAL round-trip estimate
(`puga.history.empirical_touch()`, two sequential legs: dip to bid, recover to ask) - no
random-walk assumption. CLI: `tools/parkcash.py`. See the module docstring for open gaps (no fee
data; the two legs are treated as independent, an approximation).
- **`puga.history`** — `daily_prices(tk, cx)`, `trading_days(tk, cx, days)` (real calendar-window
trading days, not "last N rows" - a sparse ticker needs this distinction), `trade_gaps_days(dates)`,
`full_series(tk, cx)` (all available history, ascending), `empirical_touch(series, y, rate)`
(non-parametric first-passage stats for a target log-move `y` - hit_factor/touched_frac/
median_days, estimated directly from how often/fast the ticker's own real history has made
moves of that size, by default only drawing on historical days in a similar state to today
(trailing-60d z-score within +/-0.5, `condition_on_state=True`) since mean reversion's effect
depends on where price is now, not just the move size. Optional `horizon` (days, off by
default): bounds both eligibility and the search window to a fixed number of days so every
start-day sample gets the same fair window, instead of recent start days being biased by
running out of data to search. Replaced an earlier driftless-random-walk formula that
backtested wrong, see `docs/decisions.md`). Shared by `tools/history.py`, `tools/sell.py`, `tools/undervalued.py`,
`puga.parkcash`.
- **`puga.contracts`** — `scan(planet, direction, sf_price, ff_price, v0=1.0, v1=1.0)`: live - **`puga.contracts`** — `scan(planet, direction, sf_price, ff_price, v0=1.0, v1=1.0)`: live
Local Market hauling ads (FIO `/localmarket/shipping/{source,destination}`), each enriched with Local Market hauling ads (FIO `/localmarket/shipping/{source,destination}`), each enriched with
real one-way fuel cost (`puga.shipping.leg_cost`) and margin. CLI: `tools/lmscan.py`. real one-way fuel cost (`puga.shipping.leg_cost`) and margin. CLI: `tools/lmscan.py`.
+9
View File
@@ -66,6 +66,15 @@ Sources: our own live APEX Ship Flight Control DOM reads (`empire/data/shipping_
- No fuel or time model for GTW duration exists yet in `puga/shipping.py` (fuel-only); this is a documented fact for whoever builds that next, not wired into any tool. - No fuel or time model for GTW duration exists yet in `puga/shipping.py` (fuel-only); this is a documented fact for whoever builds that next, not wired into any tool.
- Per the handbook: LOCK fees have no public formula (gateway-operator-set, displayed in SFC); some gateway links are one-way; each gateway has its own max per-jump cargo volume (m3), separate from ship hold size - none of these are modelled anywhere in this project yet. - Per the handbook: LOCK fees have no public formula (gateway-operator-set, displayed in SFC); some gateway links are one-way; each gateway has its own max per-jump cargo volume (m3), separate from ship hold size - none of these are modelled anywhere in this project yet.
## Placing CX orders at a remote exchange with no base/warehouse there (confirmed 2026-10-10)
Player confirms: placing a BUY order at a remote exchange (tested: NC2, Hubur Station) works with
no local base, storage, or warehouse rental there beforehand - the "Storage Location: Warehouse"
option in the Place Order panel is usable by default, not something you need to build/rent first.
Still UNCONFIRMED: whether holding the resulting inventory there afterward incurs any ongoing
storage fee - this only confirms placing the order doesn't require a prerequisite warehouse, not
that storage itself is free. Also still unconfirmed: FX conversion fee size (a forum thread titled
"remove FX transaction fee entirely" implies one exists, but no amount confirmed).
## HQ in game vs PRUNplanner's "HQ" flag (observed 2026-09-21) ## HQ in game vs PRUNplanner's "HQ" flag (observed 2026-09-21)
- The HQ screen (level 1, base permits 1 / 2) shows "Efficiency gains: Electronics 20.0%", and 23.3% for the next level (permits 1 / 3). That is exactly the faction bonus formula (Antares electronics 5% x 2 x (3 - 2 x used/total)), so the HQ display is the faction bonus. - The HQ screen (level 1, base permits 1 / 2) shows "Efficiency gains: Electronics 20.0%", and 23.3% for the next level (permits 1 / 3). That is exactly the faction bonus formula (Antares electronics 5% x 2 x (3 - 2 x used/total)), so the HQ display is the faction bonus.
- PRUNplanner's plan flag "HQ" (x1.1 on every building) is NOT visible in live efficiencies (smelters 1.3361, HWP 1.0696 both match the model without it). Keep it off. The HQ upgrade adds a base permit and raises the faction bonus. - PRUNplanner's plan flag "HQ" (x1.1 on every building) is NOT visible in live efficiencies (smelters 1.3361, HWP 1.0696 both match the model without it). Keep it off. The HQ upgrade adds a base permit and raises the faction bonus.
+40 -28
View File
@@ -1,34 +1,46 @@
# Roadmap # Roadmap
Legend: [ ] todo, [x] done. Build order matters; each step is usable on its own. Open work only - what's already built/fixed is discoverable from `CLAUDE.md`'s Tools list,
`docs/library.md`, `docs/decisions.md`, and module docstrings, not repeated here.
1. [x] Repo skeleton, git (master), venv, CLAUDE.md, mechanics from PRUNplanner. ## Todo
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`. - [ ] `tools/arb.py`: inter-CX arbitrage at real fill size (replaces `prun_cxarb.py`, which
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. overstated profit 7-11x on 2/4 top hits).
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). - [ ] `tools/haul.py`: fuel cost / profit per trip (route.py has the jump graph).
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. - [ ] `tools/portfolio.py`: profit-maximizing set of 1-building opportunities under shared
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). housing/capex/permits. Ties into backlog #2 (profit/permit ranking, needs this tool to mean
6. [x] `tools/chain.py`: full bill of materials, make-vs-buy per node. anything - permits bind at the whole-base level, not per-recipe).
7. [x] `tools/whatif.py`: marginal ROI of adding a building to a base you already run (whole-plan diff via `simulate()`, built dict from `state/company.yaml`; flags newly-caused workforce overloads). - [ ] Docs to fill: `docs/apex.md`, `docs/fio.md`, `docs/playbook.md`.
8. [x] `tools/planet.py`: rank planets for a resource (FIO bulk `Resources`/`BuildRequirements` data), founding cost from real environment-extras materials, jump distance via `tools/route.py`. `tools/found.py` (full founding workflow/writeback) still todo.
13b. [x] `puga/network.py` + `tools/network.py`: multi-base chain modelling (per-base simulate, net transfers against real freight, `cm_free` for kits). Worked example: `plans/chains/nike_deimos_lst.yaml` (Nike LST -> Deimos PP2/BSE). Known gap: reports whole-plan profit per base, not the marginal addition; caller must diff manually.
9. [x] `tools/route.py`: jump graph (FIO `/systemstars`, Dijkstra by straight-line ly, jump count alongside). `tools/haul.py` (fuel cost, profit per trip) still todo.
9c. [x] `puga/shipping.py` + `tools/shipcost.py` (explicit params) + `tools/shiptrip.py` (just ship/from/to) + `puga.shipping.round_trip_cost()` wired into `tools/network.py`'s freight cost: real ship flight fuel/cost model (STL cruise + FTL jump/charge, linear in the fuel-usage/reactor-usage sliders, additive/no cross-term; gateway hops free-fuel + manual LOCK fee read off the live game, not lookupable via any FIO/PRUNplanner endpoint - checked; landing fuel a measured per-planet lookup). Calibrated 2026-10-09 on this account's one hull/reactor (blueprint BP-STRT-0000, shared by both ships AVI-07JFB/AVI-07JFC, confirmed identical specs via FIO) via a controlled 4x4-slider-grid sweep across 5 real destinations, read from the live APEX Ship Flight Control DOM. Raw data: `empire/data/shipping_calibration/`. Open gaps (see `puga/shipping.py` docstring): departure-side gravity dependence untested (every calibration DEP left the same origin), landing fuel vs gravity/distance confounded (n=3), no second hull/reactor to cross-check generalization. `tools/scan.py --trip-cost` still uses the flat 9250 AIC placeholder (not yet wired to the real model - needs a per-recipe destination planet, not just a CX code).
9d. [x] `puga/contracts.py` + `tools/lmscan.py`: live Local Market hauling-ad scan (FIO `/localmarket/shipping/{source,destination}`, public/no-auth - real player-posted freight jobs, not the CONTD player-contract system) ranked by margin after real fuel cost (`puga.shipping.leg_cost`, one-way, with a small measured gateway-fee table `KNOWN_GATEWAY_ROUTES` for ANT<->HRT/BEN). Ship cargo hold confirmed 500t/500m3 via FIO for both ships.
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`.
13. [x] `tools/buy.py`: cash-aware shopping list (construction gap vs empire state's built count, plus N days of net operating stock via simulate(), priced at real fill cost, checked against cash/reserve). ## Backlog: review findings, still open (spot-checked against code)
14. [x] `tools/sell.py`: ask-post-price + expected-clear-time advisor from 30d traded-volume percentiles, vs hitting the bids now. 1. [ ] `scan.py` payback ignores working capital (input stock/output inventory/consumables) - can
rival building capex for smelting-type recipes. `buy.py` already computes this number.
15. [x] `tools/runway.py`: days-of-runway per material from simulate()'s net consumption, base storage plus auto-detected inbound ship cargo (tools/state.py now tags each ship with its live flight origin/destination, and each STORE with its planet, needed once a 2nd base existed). 2. [ ] No profit/permit ranking (permits bind at the base level, not per-recipe) - needs
`tools/portfolio.py`'s cross-recipe/whole-base view.
12. [ ] `tools/portfolio.py`: choose the set of 1-building opportunities for one base that maximises total profit given shared whole-building housing (HB1/HB2/...), capex, permits and (for demolish-later) 60-day value decay. Persistence check exists (`tools/persistence.py`); wire it into the ranking. 3. [ ] `scan.py` doesn't charge degradation (capex/180/day) like `simulate.py` does - small but real
14. [x] `tools/undervalued.py`: trading (not building) strategy - manufactured goods priced below implied production cost, candidates for a buy-and-hold-for-reversion bet. Backtested 2026-10-09 (326 output tickers, 287 deduplicated dip-onset episodes, 112 distinct tickers): +3mo forward return mean +21.3%/median +8.9%/73.2% hit rate at >=10 units/day volume - roughly 0.10-0.24%/day, far below the 14-29%/day marginal ROI on production builds found this session. Only worth excess idle capital, not a primary strategy. inconsistency between tools ranking the same thing.
4. [ ] No input-side flow cap (buying a big share of an input's flow should price-impact like
selling output does) - documented as absent, not modelled.
5. [ ] `persistence.py --lag 3` default is too low given `docs/mechanics.md`'s weekly workforce
distribution - real lag is 3-10 days.
6. [ ] Possible forward-fill bias if any tool reindexes `daily_prices()` onto a full calendar grid
(it only emits trade days) - would understate volatility for sparse tickers. Not yet confirmed
whether `persistence.py`/`undervalued.py` actually do this.
7. [ ] `undervalued.py`'s backtest (+21.3%/3mo) has no control group - meaningless without the
universe's unconditional return over the same window.
8. [ ] `persistence.py` measures past margin variance of a market we were NOT in - can't see the
dominant real risk (our own entry + the next player's compressing margin).
9. [ ] `undervalued.py::manufacturing_candidates()` keeps the first recipe seen per output, not
the cheapest (`seen.setdefault`).
10. [ ] `scan.py` hab cost ignores combined habs (HBB/HBC/HBM/HBL), which can be cheaper per head.
11. [ ] `scan.py --trip-cost` still defaults to the flat 9250 placeholder despite the real
`puga/shipping.py` model existing and already used by `whatif.py`.
12. [ ] `sell.py`'s `s0` is the day's VWAP, not its high - `--tiers` touch probability is slightly
pessimistic (same discretization conservatism as `empirical_touch()`, see `docs/decisions.md`).
13. [ ] `empirical_touch()`'s optional `horizon` (fixed-window right-censoring) exists but isn't
wired into any tool's default call yet.
## Open questions ## Open questions
- PRUNplanner auth is known (`Authorization: Api-Key <key>`). FIO REST and FIO API are separate services with separate keys (separate services with separate keys; an 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. - FIO REST and FIO API are separate services/keys (`.env`). FIO_REST_KEY works on rest.fnar.net;
- (resolved) PRUNplanner `exchanges/` has vwap_daily/7d/30d and traded volume; merged into `puga/market.py`. Trend history via cxpc still todo. FIO_API_KEY's host is unknown; PRUNplanner's Api-Key works. `doc.fnar.net/api.json` has no
- Extraction: concentration to daily rate formula. securitySchemes.
- (resolved 2026-09-25) Real price-band filtering (`NarrowPriceBandLow/High`, `WidePriceBandLow/High`) implemented in `puga/saturation.py` (`in_band`, `effective_demand`, `effective_supply` band param) and wired into `tools/scan.py` stage 2. Was flagged as an unimplemented refinement in saturation-design.md since day one; the player noticed a stale out-of-band bid in a live screenshot and asked the right question.
+126 -3
View File
@@ -1,6 +1,6 @@
"""Daily exchange price/volume series from FIO's cxpc candles, shared by tools/history.py and """Daily exchange price/volume series from FIO's cxpc candles, shared by tools/history.py,
tools/undervalued.py.""" tools/undervalued.py, tools/sell.py and puga/parkcash.py."""
import datetime import datetime, math, statistics
from . import fio from . import fio
@@ -11,3 +11,126 @@ def daily_prices(tk: str, cx: str) -> dict:
if e.get("Interval") == "DAY_ONE" and e.get("Traded"): if e.get("Interval") == "DAY_ONE" and e.get("Traded"):
out[datetime.datetime.fromtimestamp(e["DateEpochMs"] / 1000, datetime.timezone.utc).date()] = (e["Volume"] / e["Traded"], e["Traded"]) out[datetime.datetime.fromtimestamp(e["DateEpochMs"] / 1000, datetime.timezone.utc).date()] = (e["Volume"] / e["Traded"], e["Traded"])
return out return out
def trading_days(tk: str, cx: str, days: int = 30) -> list[tuple[datetime.date, float]]:
"""(date, units traded) for actual trading days in the last `days` CALENDAR days - fio.cxpc
only emits a row when a trade happened, so a sparse ticker needs a real calendar cutoff here,
not "last N rows" (that would silently reach back far more than `days` actual days)."""
cutoff = datetime.datetime.now(datetime.timezone.utc).date() - datetime.timedelta(days=days)
return sorted((d, v) for d, (_, v) in daily_prices(tk, cx).items() if d >= cutoff)
def trade_gaps_days(dates: list[datetime.date]) -> list[int]:
return [(b - a).days for a, b in zip(dates, dates[1:])]
def full_series(tk: str, cx: str) -> list[tuple[datetime.date, float]]:
"""Full traded-price history (all available days, not windowed) ascending by date - for the
empirical first-passage estimator below, which needs as much real history as exists rather
than a 30d window, especially for distant target prices."""
return sorted((d, p) for d, (p, _) in daily_prices(tk, cx).items())
def _trailing_zscores(logp: list[float], trail: int = 60, min_window: int = 10) -> list[float | None]:
"""z-score of each day's log-price against its own trailing `trail`-day mean/stdev (None where
there isn't `min_window` days of history yet). A flat window (stdev 0) scores 0, not None -
the price IS exactly at its own flat mean, that's a real, defined state, not missing data."""
z = [None] * len(logp)
for i in range(len(logp)):
window = logp[max(0, i - trail + 1):i + 1]
if len(window) < min_window:
continue
m = statistics.mean(window)
sd = statistics.stdev(window) if len(window) > 1 else 0.0
z[i] = (logp[i] - m) / sd if sd > 1e-12 else 0.0
return z
def empirical_touch(series: list[tuple[datetime.date, float]], y: float, rate: float,
condition_on_state: bool = True, trail: int = 60, z_tol: float = 0.5,
horizon: int | None = None) -> dict:
"""Non-parametric first-passage stats for a target log-move `y` = ln(target_price/start_price),
estimated directly from how often and how fast this ticker's REAL price history has made moves
of that size - no random-walk/GBM assumption, so real mean-reversion shows up directly in the
result instead of being assumed away (see docs/decisions.md for the evidence that real prices
here do mean-revert).
Mean reversion means the answer depends on WHERE price is now relative to its own recent
trend, not just on the move size - a 20% rise is more/less likely depending on whether today
is already above or below the recent mean. With `condition_on_state` (default), only historical
start days whose z-score against a trailing `trail`-day mean are within `z_tol` of TODAY's
z-score (the series' last point) are used - keeping the estimate non-parametric (no fitted
mean-reversion speed/strength) while still making it state-aware. Falls back to using every
start day if there isn't enough history to compute today's z-score, or if the z_tol band is
empty (too little data to condition on, not a real "always/never" signal).
For each eligible historical day i, scan forward for the first day j>i where the cumulative
log-return reaches y (>= y if y>0, <= y if y<0). Contributes e^(-rho*dt) to the discount-factor
average, where dt is the elapsed calendar days and rho = ln(1+rate); a day that NEVER reaches y
within the observed history contributes 0 (not excluded - excluding right-censored samples
would bias the estimate toward only the easy cases, since the hard/slow/never cases are exactly
the ones that get cut off by the data running out).
CAVEAT: `series` is daily VWAP (one point per day), a discrete sample of a continuous price
path. Discrete monitoring can only miss touches, never invent them - an intraday spike that
crosses the target and reverts before the next day's VWAP is computed shows up as "not
touched" here even though a resting ask would genuinely have filled on it. So this estimator
is systematically conservative: real touch probability/hit_factor is at least this high, likely
somewhat higher, and the resulting "sell now" lean (tools/sell.py --tiers) is a bit stronger
than fully warranted. Standard discrete-monitoring barrier corrections (e.g. Broadie-Glasserman-
Kou) put the gap at roughly 0.58*sigma*sqrt(step) per sampling interval for a short horizon -
real at short horizons, shrinking as the horizon grows. Not corrected for here.
Without `horizon`, "never reached" means "not reached before the series ends" - which gives
start days near the end of history much less time to ever register a hit than start days near
the beginning, purely from running out of data, not economics. With `horizon` (days), only
start days with at least that much real history remaining are used, and the search for day j
is capped at `horizon` days past i for all of them - every sample gets the same fixed window,
so touched_frac/hit_factor are comparable across samples instead of recency-biased. Off by
default (every caller currently omits it) since it discards the most recent `horizon` days of
start-day samples entirely - a real tradeoff, not a strict improvement on small histories.
Returns: hit_factor (empirical E[e^-rho*tau], the discounted-value multiplier), touched_frac
(share of start days that ever reached y at all within their remaining history), median_days
(None if touched_frac < 0.5 - can't report a median that was never reached more than half the
time), n (sample count - note: these are heavily OVERLAPPING windows, not independent draws,
so n overstates the effective sample size; same caveat as the backtest this reuses).
"""
n = len(series)
if y == 0 or n < 2:
return {"hit_factor": 1.0, "touched_frac": 1.0, "median_days": 0.0, "n": n}
dates = [d for d, _ in series]
logp = [math.log(p) for _, p in series if p > 0]
rho = math.log(1 + rate)
eligible = range(n - 1)
if horizon is not None:
eligible = [i for i in eligible if (dates[-1] - dates[i]).days >= horizon]
if condition_on_state:
z = _trailing_zscores(logp, trail)
z_today = z[-1]
if z_today is not None:
matched = [i for i in eligible if z[i] is not None and abs(z[i] - z_today) <= z_tol]
if matched:
eligible = matched
discount_sum, hit_days, count = 0.0, [], 0
for i in eligible:
target = logp[i] + y
found = None
for j in range(i + 1, n):
if horizon is not None and (dates[j] - dates[i]).days > horizon:
break
if (y > 0 and logp[j] >= target) or (y < 0 and logp[j] <= target):
found = j
break
count += 1
if found is not None:
dt = (dates[found] - dates[i]).days
discount_sum += math.exp(-rho * dt)
hit_days.append(dt)
touched_frac = len(hit_days) / count if count else 0.0
median_days = statistics.median(hit_days) if touched_frac >= 0.5 else None
return {"hit_factor": discount_sum / count if count else 0.0, "touched_frac": touched_frac,
"median_days": median_days, "n": count}
+82
View File
@@ -0,0 +1,82 @@
"""Where to park idle cash as a buy-low/sell-high position (not a build) while ships are busy or
cash has no better immediate use - the market-making tactic worked out by hand in-session before
this existed. A big bid/ask spread alone is a trap (see OPEN GAPS below); this scores candidates
on spread, real trading liquidity, and an EMPIRICAL round-trip estimate from the ticker's own
price history - no random-walk/mean-reversion assumption (an earlier driftless-random-walk
version of this kind of model was built for tools/sell.py and backtested WRONG against 3 years of
real data - see docs/decisions.md's 2026-10-10 entries - so this one measures directly instead).
Method per ticker:
- spread_pct: (ask - bid) / bid at the live quote.
- liquidity: trading_days()/trade_gaps_days() over the last `days` calendar days - trades on most
days with a short gap is real liquidity; a huge spread with few trading days is the trap this
project already got burned by once (AST: 130% spread, 19/30 trading days, but the resting ask
was stale - real last-traded price had already crashed 60% below it).
- round trip = two sequential empirical first-passage legs (puga.history.empirical_touch), using
the ticker's own full multi-year history, not an assumed distribution:
buy leg: y = ln(bid/latest) - how often/fast has a move of this size (usually downward)
actually happened, ever, in this ticker's real history?
sell leg: y = ln(ask/bid) - same question for the recovery back up to ask.
combined_days = buy.median_days + sell.median_days (both must happen, in sequence)
combined_hit = buy.hit_factor * sell.hit_factor (treats the two legs as independent - an
approximation, not exact, but each factor is itself a real empirically-measured expectation,
not a parametric guess).
- daily_pct: (ask-bid)/bid pessimistic margin over combined_days, as a SIMPLE (non-compounding)
rate - see docs/decisions.md's "Drop ROI/day %" entry. For ranking by speed, not a yield.
- discounted_pct: margin_pct x combined_hit - the SAME margin, discounted by both legs' real odds
of ever happening at all (`--rate`'s only effect on the output; a low/near-0 default matches
this tool's "idle cash, no better use" premise - pass a higher rate if this money actually IS
earmarked for something and waiting has a real opportunity cost). A big gap between daily_pct
and discounted_pct means the raw speed number is flattering a trade that may just never clear.
OPEN GAPS:
- No CX transaction/fee field in FIO's exchange data (checked) - can't confirm or rule out a fee
eating into the spread; not modelled.
- Treating buy-leg and sell-leg as independent (multiplying hit factors, adding median days) is an
approximation - the real joint distribution of "time to dip to bid, THEN time to recover to ask
starting from wherever it actually dipped to" isn't computed exactly.
"""
import math, statistics
from . import market
from .history import daily_prices, trading_days, trade_gaps_days, full_series, empirical_touch
def scan(cx: str = "AI1", min_spread_pct: float = 20.0, days: int = 30, rate: float = 0.0):
"""Every (ticker, cx) with a live quote and spread_pct >= min_spread_pct, scored by pessimistic
simple daily-equivalent return from the empirical round-trip model. Returns a list of dicts,
unsorted (sort by 'daily_pct' - or let the caller filter on 'trade_days'/'gap_days' first,
since those are what separate a real opportunity from a stale-quote trap)."""
snap = market.snapshot()
rows = []
for (tk, q_cx), q in snap.items():
if q_cx != cx or not q.ask or not q.bid or q.bid <= 0:
continue
spread_pct = 100 * (q.ask - q.bid) / q.bid
if spread_pct < min_spread_pct:
continue
dp = daily_prices(tk, cx)
if len(dp) < 2:
continue
td = trading_days(tk, cx, days)
gaps = trade_gaps_days([d for d, _ in td])
gap_days = statistics.median(gaps) if gaps else None
if not gap_days or gap_days <= 0:
continue
series = full_series(tk, cx)
latest = series[-1][1]
if latest <= 0:
continue
buy = empirical_touch(series, math.log(q.bid / latest), rate)
sell = empirical_touch(series, math.log(q.ask / q.bid), rate)
if buy["median_days"] is None or sell["median_days"] is None:
continue # one leg has never reliably happened in this ticker's real history
combined_days = buy["median_days"] + sell["median_days"]
combined_hit = buy["hit_factor"] * sell["hit_factor"]
margin_pct = 100 * (q.ask - q.bid) / q.bid
rows.append(dict(tk=tk, cx=cx, bid=q.bid, ask=q.ask, spread_pct=spread_pct, latest=latest,
margin_pct=margin_pct, trade_days=len(td), window_days=days, gap_days=gap_days,
buy_touch=buy["touched_frac"], sell_touch=sell["touched_frac"],
wait_days=combined_days, hit_factor=combined_hit,
daily_pct=margin_pct / combined_days if combined_days else 0.0,
discounted_pct=margin_pct * combined_hit))
return rows
+71 -9
View File
@@ -1,34 +1,96 @@
"""Saturation model v1 (docs/saturation-design.md, after Opus review 2026-09-18). Pure functions. """Saturation model v1 (docs/saturation-design.md, after Opus review 2026-09-18). Pure functions.
Idea: N buildings is limited by (a) share of the market's steady traded flow, (b) the queue of existing Idea: N buildings is limited by (a) share of the market's steady traded flow and (b) the queue of
sell orders (supply days) and (c) whether buy-side stock covers it. Price is a haircut model, not a book walk.""" existing sell orders (supply days). Price is a haircut model, not a book walk.
import math
is_thin() checks demand depth as an independent red flag (a genuinely dead bid book is worth
knowing about); n_out() does not multiply by it (see n_out's own docstring for why)."""
import math, statistics
from .history import trading_days
S_SHARE = 0.25 # max share of traded flow one producer takes S_SHARE = 0.25 # max share of traded flow one producer takes
T_Q = 7 # days of flow the standing sell queue is compared against T_Q = 7 # days of flow the standing sell queue is compared against
T_D = 7 # days of flow standing demand should cover T_D = 7 # days of flow standing demand should cover (used by is_thin only)
T_W = 3 # patient-selling window (days) T_W = 3 # patient-selling window (days)
def tref(traded7: float, traded30: float) -> float: def tref(traded7: float, traded30: float) -> float:
"""Conservative daily flow: min(7d, 30d); with a Poisson lower bound when 30d volume is small.""" """Conservative daily flow: min(7d, 30d); with a Poisson lower bound when 30d volume is small.
CAVEAT: the Poisson term treats each traded UNIT as an independent event, which overstates
confidence for lumpy real trades (one 500-unit trade is one event, not 500) - see
`tref_precise()` for the real-variance version, used once a candidate reaches stage 2 (this
cheap version stays for stage-1 screening across every recipe, where fetching daily history
for every ticker would be too expensive)."""
t = min(traded7, traded30) t = min(traded7, traded30)
if 0 < traded30 < 20: if 0 < traded30 < 20:
t = min(t, max(0.0, traded30 * (1 - 1.96 / math.sqrt(30 * traded30)))) t = min(t, max(0.0, traded30 * (1 - 1.96 / math.sqrt(30 * traded30))))
return max(0.0, t) return max(0.0, t)
def tref_precise(tk: str, cx: str, traded7: float, traded30: float, days: int = 30) -> float:
"""Like tref(), but the lower bound comes from the REAL variance of daily traded volume
(`puga.history.trading_days`) instead of a Poisson unit-independence assumption - one 500-unit
trade is one data point here, not 500 independent ones. Falls back to tref() if there's too
little real history to estimate variance from (<=2 trading days).
`trading_days()` only returns days with a trade - zero-volume days are absent, not zero - so
the volume list is padded with explicit zeros for the missing calendar days before computing
mean/stdev, and `days` (not the trading-day count) is used as n. Averaging only over the rows
that have a trade would compute the mean volume ON TRADING DAYS, overstating real
per-CALENDAR-day flow by 1/(fraction of days traded) - worst precisely for the sparse tickers
this function exists to protect."""
td = trading_days(tk, cx, days)
if len(td) <= 2:
return tref(traded7, traded30)
vols = [v for _, v in td] + [0.0] * (days - len(td))
mean = statistics.mean(vols)
sd = statistics.stdev(vols)
bound = max(0.0, mean - 1.96 * sd / math.sqrt(days))
return max(0.0, min(tref(traded7, traded30), bound))
def max_units_at_impact(bids: list[tuple[float, float]], ref_price: float, max_impact_pct: float = 10.0) -> float:
"""Real, ticker-specific price-impact cap, replacing the flat S_SHARE guess for THIS check:
how many units could be sold into the LIVE bid book before the price paid degrades more than
`max_impact_pct` below `ref_price`. Walks bids highest-first (puga.market.walk's own
mechanics) and stops at the first tier priced below the threshold.
A day-over-day price-vs-volume regression does not give a usable general elasticity estimate
here: volume and price co-move mostly from DEMAND bursts (more buyers -> more volume AND
steady/higher price), which swamps and often reverses the sign of the SUPPLY-side effect
actually wanted (does MY added output push price down). Walking the real book sidesteps that
confounding, but only captures the static liquidity snapshot, not how the market reprices
over weeks of sustained extra output (nothing in available data answers that cleanly). See
docs/decisions.md."""
if not ref_price or ref_price <= 0:
return 0.0
threshold = ref_price * (1 - max_impact_pct / 100)
cum = 0.0
for price, qty in sorted(bids, key=lambda x: -x[0]):
if price < threshold:
break
cum += qty
return cum
def is_thin(tr: float, demand: float, q_out: float) -> bool: def is_thin(tr: float, demand: float, q_out: float) -> bool:
return tr < 3 * q_out or demand < 7 * q_out return tr < 3 * q_out or demand < 7 * q_out
def n_out(tr: float, supply: float, demand: float, q_out: float) -> float: def n_out(tr: float, supply: float, q_out: float) -> float:
"""Buildings the output market absorbs: flow share x queue penalty x demand coverage. 0 if no flow.""" """Buildings the output market absorbs: flow share x queue penalty. 0 if no flow.
Deliberately has NO resting-bid-depth term: production sells via patient ASKS (`p_patient()`)
that get taken by buyers crossing the spread, including walk-up buyers with no resting bid at
all - a thin resting bid book doesn't mean they won't show up, since `tr` (real traded flow,
already in `base`) is the actual evidence they do. A market with healthy ask-side flow and
thin standing bids is normal (most buyers don't leave a bid sitting around), not evidence of
absent demand. Real resting-bid demand is still checked independently by `is_thin()` as a red
flag, not folded into this score."""
if tr <= 0 or q_out <= 0: if tr <= 0 or q_out <= 0:
return 0.0 return 0.0
base = S_SHARE * tr / q_out base = S_SHARE * tr / q_out
queue = min(1.0, T_Q * tr / supply) if supply > 0 else 1.0 queue = min(1.0, T_Q * tr / supply) if supply > 0 else 1.0
cover = min(1.0, demand / (T_D * tr)) return base * queue
return base * queue * cover
def p_patient(asks: list[tuple[float, float]], tr: float, produced_per_day: float, bid: float, vwap7: float | None, def p_patient(asks: list[tuple[float, float]], tr: float, produced_per_day: float, bid: float, vwap7: float | None,
+72
View File
@@ -0,0 +1,72 @@
import datetime, math
from puga.history import empirical_touch, _trailing_zscores
def _series(jump_idx, n=20, jump_price=220.0, base_price=100.0):
base = datetime.date(2026, 1, 1)
return [(base + datetime.timedelta(days=i), jump_price if i >= jump_idx else base_price) for i in range(n)]
def test_hit_factor_has_no_cliff_at_the_50pct_touched_threshold():
"""median_days flips from a number to None the instant touched_frac crosses 50% - that's
fine as a reported diagnostic, but ranking by it (as sell.py's --tiers used to) creates a
fake cliff: a tier touched 47% of the time would be valued at exactly 0, one touched 53% of
the time at near-full value, even though hit_factor (the real E[e^-rho*tau]) moves smoothly
between them. This is what tools/sell.py's --tiers ranks by instead."""
y = math.log(2.0)
below = empirical_touch(_series(jump_idx=9), y, rate=0.05, condition_on_state=False)
above = empirical_touch(_series(jump_idx=10), y, rate=0.05, condition_on_state=False)
assert below["median_days"] is None and above["median_days"] is not None
assert below["touched_frac"] < 0.5 <= above["touched_frac"]
# hit_factor must not have fallen off a cliff just because median_days did
assert below["hit_factor"] > 0.5 * above["hit_factor"]
def test_empirical_touch_trivial_for_zero_move():
r = empirical_touch(_series(jump_idx=5), 0.0, rate=0.05)
assert r == {"hit_factor": 1.0, "touched_frac": 1.0, "median_days": 0.0, "n": 20}
def test_conditioning_on_state_uses_only_similar_regime_days():
"""Mean reversion means the answer should depend on whether today looks like the ticker's
readily-rising early regime or its since-flattened plateau - not blend both in unconditionally.
Series: 20 flat days, then a steady climb, then 10 more flat days at the new high (today is
in the plateau, not the climb)."""
base = datetime.date(2026, 1, 1)
prices = [100] * 20 + [100 + i * 5 for i in range(1, 11)] + [150] * 10
series = [(base + datetime.timedelta(days=i), float(p)) for i, p in enumerate(prices)]
y = math.log(1.1)
uncond = empirical_touch(series, y, rate=0.05, condition_on_state=False)
cond = empirical_touch(series, y, rate=0.05, condition_on_state=True)
assert uncond["touched_frac"] > 0.5 # blends in the climb regime, looks like it moves readily
assert cond["touched_frac"] < uncond["touched_frac"] # today's plateau regime moves less
def test_trailing_zscores_flat_window_is_zero_not_none():
logp = [math.log(100.0)] * 15
z = _trailing_zscores(logp, trail=60, min_window=10)
assert z[:9] == [None] * 9 # not enough window yet
assert z[9:] == [0.0] * 6 # flat price is exactly at its own mean - a real, defined state
def test_horizon_removes_recency_bias_from_right_censoring():
"""Without a fixed horizon, start days near the end of history get an unfairly short (or
long) remaining window to register a touch, purely from running out of data. A flat series
with a late jump looks like it "touches" readily only because the jump happens to sit right
next to the end-of-history start days; a fixed horizon gives every sample the same window."""
base = datetime.date(2026, 1, 1)
prices = [100.0] * 30 + [220.0] * 5
series = [(base + datetime.timedelta(days=i), p) for i, p in enumerate(prices)]
y = math.log(2.0)
uncapped = empirical_touch(series, y, rate=0.05, condition_on_state=False)
capped = empirical_touch(series, y, rate=0.05, condition_on_state=False, horizon=5)
assert capped["touched_frac"] < uncapped["touched_frac"]
assert capped["n"] < uncapped["n"] # the last `horizon` days of start days are dropped
def test_empirical_touch_never_reached_is_zero_not_excluded():
# a move far beyond anything the series ever does should look like "basically never"
r = empirical_touch(_series(jump_idx=19, jump_price=101.0), math.log(50.0), rate=0.05)
assert r["touched_frac"] == 0.0
assert r["hit_factor"] == 0.0
assert r["median_days"] is None
+24 -5
View File
@@ -1,3 +1,4 @@
import datetime
import math import math
from puga import saturation as s, market, fio from puga import saturation as s, market, fio
@@ -8,12 +9,22 @@ def test_tref_uses_min_and_poisson_floor():
assert s.tref(0, 0) == 0 assert s.tref(0, 0) == 0
def test_n_out_penalises_queue_and_thin_demand(): def test_tref_precise_pads_missing_calendar_days_not_just_trading_days(monkeypatch):
free = s.n_out(100, 0, 10_000, 5) # no queue, ample demand # 10 trading days out of 30, each with volume 30 -> real per-calendar-day mean is 10, not 30.
# The original bug averaged only over the 10 trading-day rows (mean 30), overstating the
# bound 3x for exactly the sparse tickers it's meant to protect.
base = datetime.date(2026, 1, 1)
fake_td = [(base + datetime.timedelta(days=i * 3), 30.0) for i in range(10)]
monkeypatch.setattr(s, "trading_days", lambda tk, cx, days: fake_td)
bound = s.tref_precise("FAKE", "AI1", traded7=30, traded30=30, days=30)
assert bound < 15.0 # well below the naive trading-day mean of 30, reflecting real sparsity
def test_n_out_penalises_queue():
free = s.n_out(100, 0, 5) # no queue
assert math.isclose(free, 0.25 * 100 / 5) assert math.isclose(free, 0.25 * 100 / 5)
assert s.n_out(100, 7000, 10_000, 5) < free # 70 days of queue cuts it assert s.n_out(100, 7000, 5) < free # 70 days of queue cuts it
assert s.n_out(100, 0, 100, 5) < free # demand only 1 day of flow cuts it assert s.n_out(0, 0, 5) == 0
assert s.n_out(0, 0, 100, 5) == 0
def test_thin_flag(): def test_thin_flag():
@@ -57,3 +68,11 @@ def test_effective_demand_excludes_stale_bids_below_the_band():
bids = [(4550, 8), (4200, 250), (2810, 8), (334, 19)] bids = [(4550, 8), (4200, 250), (2810, 8), (334, 19)]
assert s.effective_demand(bids, band=(663, 16575)) == 8 + 250 + 8 # the 334 bid is stale, excluded assert s.effective_demand(bids, band=(663, 16575)) == 8 + 250 + 8 # the 334 bid is stale, excluded
assert s.effective_demand(bids, band=None) == 8 + 250 + 8 + 19 assert s.effective_demand(bids, band=None) == 8 + 250 + 8 + 19
def test_max_units_at_impact_stops_at_the_price_threshold():
bids = [(100, 10), (95, 20), (85, 1000)] # ref 100, 10% floor = 90
assert s.max_units_at_impact(bids, 100, max_impact_pct=10.0) == 30 # 100 and 95 tiers only
assert s.max_units_at_impact(bids, 100, max_impact_pct=20.0) == 1030 # all three tiers now qualify
assert s.max_units_at_impact([], 100) == 0.0
assert s.max_units_at_impact(bids, 0) == 0.0
+16 -9
View File
@@ -57,23 +57,30 @@ def test_switched_off_recipes_produce_nothing_but_keep_workforce(sim):
assert r["flows"]["AL"]["inp"] == pytest.approx(42.78, abs=0.01) assert r["flows"]["AL"]["inp"] == pytest.approx(42.78, abs=0.01)
def test_cost_degradation_area_match_screenshots(): def test_area_matches_screenshots():
"""Screenshots: full plan area 237, degradation 2,141.74, plan cost 737,076; HWP-only area 102, degradation 373.60, cost 418,812. """Screenshots (2026-09-18): full plan area 237, HWP-only area 102 - exact, no price dependency.
Prices drift, so 3% tolerance on money values; area is exact.""" Degradation/plan_cost were checked against the same screenshots (2,141.74/737,076 and
from puga import market 373.60/418,812) at the time and matched within rounding; not asserted here with those fixed
money values since they're priced in live material costs that drift with the market - a fixed
expected money value from one point in time isn't a meaningful regression check against an
input that never stops moving (a fresh screenshot would be, this isn't that). The formula
relationship itself (not tied to any particular price) is asserted instead, below."""
try: try:
recipes, blds = pp.recipes(), pp.buildings() recipes, blds = pp.recipes(), pp.buildings()
planet = pp._g("/data/planet/ZV-759c/", 3600) planet = pp._g("/data/planet/ZV-759c/", 3600)
snap = market.snapshot()
except Exception as e: except Exception as e:
pytest.skip(f"offline: {e}") pytest.skip(f"offline: {e}")
price = lambda t, side='both': market.uni30(snap, t) for fname, area in (("base_plus_hwp.yaml", 237), ("hwp_only.yaml", 102)):
for fname, area, degr, cost in (("base_plus_hwp.yaml", 237, 2141.74, 737076.53), ("hwp_only.yaml", 102, 373.60, 418811.91)):
plan = plan_push.build_payload(yaml.safe_load((ROOT / "plans" / "examples" / fname).read_text()), recipes, {b["building_ticker"] for b in blds}) plan = plan_push.build_payload(yaml.safe_load((ROOT / "plans" / "examples" / fname).read_text()), recipes, {b["building_ticker"] for b in blds})
plan["plan_corphq"] = False plan["plan_corphq"] = False
r = simulate(plan, recipes, blds, planet["resources"], planet["fertility"], price) r = simulate(plan, recipes, blds, planet["resources"], planet["fertility"], lambda t, side='both': 100.0)
assert r["area"] == area assert r["area"] == area
assert r["degradation"] == pytest.approx(degr, rel=0.03) and r["plan_cost"] == pytest.approx(cost, rel=0.03) # Structural, price-independent regression check (puga/simulate.py): degradation is
# production-building cost only (infra/CM excluded) divided by 180 days; plan cost is
# production + infrastructure + one core module kit. Holds at any price, including this
# constant-100 lambda - catches a formula regression without depending on live prices.
assert r["degradation"] == pytest.approx(r["prod_cost"] / 180)
assert r["plan_cost"] == pytest.approx(r["prod_cost"] + r["infra_cost"] + r["cm_cost"])
def test_hq_multiplies_every_building_by_1_1(sim): def test_hq_multiplies_every_building_by_1_1(sim):
+47
View File
@@ -0,0 +1,47 @@
#!/usr/bin/env python3
"""Where to park idle cash as a buy-low/sell-high position while ships are busy or cash has no
better immediate use. Scans every ticker for a big spread AND real trading liquidity, scored by
an EMPIRICAL round-trip estimate from the ticker's own price history (no random-walk assumption -
see puga/parkcash.py's docstring for the method and open gaps).
tools/parkcash.py # AI1, default filters, top 25 by pessimistic daily %
tools/parkcash.py --min-trade-days 15 # require real liquidity (half the window trading)
"""
import argparse, sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
from puga import config, parkcash
def main():
ap = argparse.ArgumentParser()
ap.add_argument("--cx", default=config.DEFAULT_CX)
ap.add_argument("--min-spread", type=float, default=20.0, help="minimum bid/ask spread %% to consider")
ap.add_argument("--min-trade-days", type=int, default=10, help="minimum trading days out of the window - filters stale-quote traps")
ap.add_argument("--days", type=int, default=30, help="calendar-day window for liquidity stats (the empirical round-trip model itself uses full history)")
ap.add_argument("--rate", type=float, default=0.0, help="opportunity cost of waiting on this cash - default 0.0 matches this tool's premise (idle cash, no better use right now); pass your realized capital growth rate (e.g. 0.05, see tools/sell.py --rate) if this money IS earmarked for something and waiting has a real cost")
ap.add_argument("--max-wait", type=float, help="drop anything with a combined round-trip median wait above this many days")
ap.add_argument("--top", type=int, default=25)
a = ap.parse_args()
rows = parkcash.scan(a.cx, a.min_spread, a.days, a.rate)
rows = [r for r in rows if r["trade_days"] >= a.min_trade_days]
if a.max_wait is not None:
rows = [r for r in rows if r["wait_days"] <= a.max_wait]
rows.sort(key=lambda r: -r["daily_pct"])
print(f"# {a.cx} spread>={a.min_spread:.0f}% trade_days>={a.min_trade_days}/{a.days}d rate={100*a.rate:.1f}%/day "
f"(round trip = empirical buy-dip + sell-recovery from real history, see puga/parkcash.py)")
print(f"{'daily%':>7} {'disc%':>6} {'margin%':>8} {'spread%':>8} {'days':>5} {'buy%':>5} {'sell%':>5} {'wait(d)':>7} {'bid':>9} {'ask':>9} tk")
for r in rows[:a.top]:
print(f"{r['daily_pct']:7.1f} {r['discounted_pct']:6.1f} {r['margin_pct']:8.1f} {r['spread_pct']:8.0f} {r['trade_days']:5d} "
f"{100*r['buy_touch']:5.0f} {100*r['sell_touch']:5.0f} {r['wait_days']:7.1f} {r['bid']:9.0f} {r['ask']:9.0f} {r['tk']}")
print("\nNOTE: disc% = margin% x real odds both legs ever happen (at --rate; a big gap from daily% "
"means the speed number is flattering a trade that may never clear). buy%/sell% are each leg's "
"real historical frequency. Not a compoundable rate - see docs/decisions.md. See puga/parkcash.py's "
"OPEN GAPS (no fee data; legs treated as independent).")
if __name__ == "__main__":
main()
+40 -19
View File
@@ -33,7 +33,9 @@ def main():
ap.add_argument("--cargo", type=float, default=500.0, help="t and m3 per trip (starter ship)") ap.add_argument("--cargo", type=float, default=500.0, help="t and m3 per trip (starter ship)")
ap.add_argument("--no-hq", action="store_true", help="ignore HQ from state (new base without the HQ)") ap.add_argument("--no-hq", action="store_true", help="ignore HQ from state (new base without the HQ)")
ap.add_argument("--permits-used", type=int, help="override permits used (affects faction bonus multiplier), e.g. 2 for a second base") ap.add_argument("--permits-used", type=int, help="override permits used (affects faction bonus multiplier), e.g. 2 for a second base")
ap.add_argument("--deprec", type=float, default=0, help="demolish-later mode: building value decays linearly to 0 over this many days (game: ~60); subtracts capex/deprec per day") ap.add_argument("--deprec", type=float, default=0, help="demolish-later mode: assumed holding days before demolition; amortizes the UNRECLAIMED portion of capex (capex x (1 - --reclaim-frac)) over that period, NOT full capex - real FIO reclaimables data (this account's own buildings, 2026-10-10) showed ~50-86%% returned even at near-100%% condition, contradicting a 100%%->0 time-decay story. See docs/decisions.md.")
ap.add_argument("--reclaim-frac", type=float, default=0.65, help="fraction of capex recovered on demolition - real observed range 50-86%% across 7 owned building types (CM a low outlier at ~7%%, excluded); single base/age, small sample, treat as a rough placeholder not a calibrated curve")
ap.add_argument("--max-impact", type=float, default=10.0, help="max %% the realized price may degrade below vwap7/bid when walking the LIVE bid book for your planned daily output (puga.saturation.max_units_at_impact) - feeds the [exit-thin] warning flag: can you instantly DUMP a day of output into resting bids if you needed cash now, not whether your patient asks clear (that's the market/lim columns). See docs/decisions.md")
ap.add_argument("--input", help="only recipes consuming this ticker as an input, e.g. --input AL for recipes built on top of your own AL chain") ap.add_argument("--input", help="only recipes consuming this ticker as an input, e.g. --input AL for recipes built on top of your own AL chain")
ap.add_argument("--planet", help="planet natural id: adds extraction (EXT/COL/RIG) from its resources, uses its fertility and active COGC; new base (not in state) => no HQ, permits+1") ap.add_argument("--planet", help="planet natural id: adds extraction (EXT/COL/RIG) from its resources, uses its fertility and active COGC; new base (not in state) => no HQ, permits+1")
ap.add_argument("--own", type=int, default=1, help="how many buildings WE would run; yield/payback is measured at this size (default 1). --min-n is only a market-size filter") ap.add_argument("--own", type=int, default=1, help="how many buildings WE would run; yield/payback is measured at this size (default 1). --min-n is only a market-size filter")
@@ -45,7 +47,7 @@ def main():
ap.add_argument("--max-n", type=int, default=50, help="cap N* (capital/attention limit)") ap.add_argument("--max-n", type=int, default=50, help="cap N* (capital/attention limit)")
ap.add_argument("--budget", type=float, help="capital limit in AIC: caps N and drops recipes whose single-building capex exceeds it") ap.add_argument("--budget", type=float, help="capital limit in AIC: caps N and drops recipes whose single-building capex exceeds it")
ap.add_argument("--mcg", type=float, default=4.0, help="MCG per area (4 on normal planets)") ap.add_argument("--mcg", type=float, default=4.0, help="MCG per area (4 on normal planets)")
ap.add_argument("--sort", default="roi", choices=["roi", "total", "roi1"]) ap.add_argument("--sort", default="roi", choices=["roi", "total", "roi1", "area"])
ap.add_argument("--top", type=int, default=30) ap.add_argument("--top", type=int, default=30)
ap.add_argument("--k", type=int, default=80, help="candidates refined with order books") ap.add_argument("--k", type=int, default=80, help="candidates refined with order books")
ap.add_argument("--show-thin", action="store_true") ap.add_argument("--show-thin", action="store_true")
@@ -83,10 +85,11 @@ def main():
return None return None
return sum(n * p for n, p in parts) + a.mcg * b["AreaCost"] * mcg return sum(n * p for n, p in parts) + a.mcg * b["AreaCost"] * mcg
hab_head = {} hab_head, hab_area = {}, {}
for tier, hab in (("pioneer", "HB1"), ("settler", "HB2"), ("technician", "HB3"), ("engineer", "HB4"), ("scientist", "HB5")): for tier, hab in (("pioneer", "HB1"), ("settler", "HB2"), ("technician", "HB3"), ("engineer", "HB4"), ("scientist", "HB5")):
c = bcost(hab) c = bcost(hab)
hab_head[tier] = None if c is None else c / econ.HAB_CAP[hab][tier] hab_head[tier] = None if c is None else c / econ.HAB_CAP[hab][tier]
hab_area[tier] = econ.HAB_AREA[hab] / econ.HAB_CAP[hab][tier]
def wage(tier): # per worker per day, both luxuries supplied, at ask def wage(tier): # per worker per day, both luxuries supplied, at ask
tot = 0.0 tot = 0.0
@@ -156,7 +159,7 @@ def main():
mm[t] = x.mm_buy # market maker floor: unlimited depth at mm_buy mm[t] = x.mm_buy # market maker floor: unlimited depth at mm_buy
continue continue
thin |= sat.is_thin(tr, x.demand, qo) thin |= sat.is_thin(tr, x.demand, qo)
n = sat.n_out(tr, 0, x.demand, qo) # stage 1: flow + demand only; queue penalty applied in stage 2 with the book n = sat.n_out(tr, 0, qo) # stage 1: flow only; queue penalty applied in stage 2 with the book
if n < n_lim: if n < n_lim:
n_lim, lim = n, t n_lim, lim = n, t
if n_lim == float("inf"): if n_lim == float("inf"):
@@ -170,7 +173,8 @@ def main():
rough = sum(io["out"][t] * price0[t] for t in io["out"]) - sum(io["in"][t] * ask(t) for t in io["in"]) - wcost rough = sum(io["out"][t] * price0[t] for t in io["out"]) - sum(io["in"][t] * ask(t) for t in io["in"]) - wcost
staff = "".join(TIER_CODE[t] for t in keep) + ("" if len(keep) == len(need) else "-") staff = "".join(TIER_CODE[t] for t in keep) + ("" if len(keep) == len(need) else "-")
cands.append(dict(rec=rec, b=b, io=io, eff=eff, capex=capex, wcost=wcost, n_lim=n_lim, lim=lim, thin=thin, mm=mm, cands.append(dict(rec=rec, b=b, io=io, eff=eff, capex=capex, wcost=wcost, n_lim=n_lim, lim=lim, thin=thin, mm=mm,
rough_roi=100 * rough / capex, top=top, staff=staff, ins=ins, outs=outs)) rough_roi=100 * rough / capex, top=top, staff=staff, ins=ins, outs=outs,
hab_area_per_bld=sum(heads[t] * hab_area[t] for t in keep)))
cands.sort(key=lambda c: c["rough_roi"], reverse=True) cands.sort(key=lambda c: c["rough_roi"], reverse=True)
rows = [] rows = []
@@ -184,6 +188,9 @@ def main():
def asks_of(t): def asks_of(t):
return sorted((o["ItemCost"], (o["ItemCount"] or 0)) for o in raw_book(t)["SellingOrders"]) return sorted((o["ItemCost"], (o["ItemCount"] or 0)) for o in raw_book(t)["SellingOrders"])
def bids_of(t):
return [(o["ItemCost"], (o["ItemCount"] or 0)) for o in raw_book(t)["BuyingOrders"] if o.get("ItemCost")]
def band_of(t): def band_of(t):
if t not in bandcache: if t not in bandcache:
ob = raw_book(t) ob = raw_book(t)
@@ -192,21 +199,29 @@ def main():
bandcache[t] = (lo, hi) bandcache[t] = (lo, hi)
return bandcache[t] return bandcache[t]
def demand_of(t):
bids = ((o["ItemCost"], o["ItemCount"] or 0) for o in raw_book(t)["BuyingOrders"])
return sat.effective_demand(bids, band_of(t))
for c in cands[:a.k]: for c in cands[:a.k]:
io, mm = c["io"], c["mm"] io, mm = c["io"], c["mm"]
# stage 2: queue penalty from competing asks near market price only, and demand within the tradeable band # stage 2: queue penalty from competing asks near market price, flow from REAL daily-volume
n2 = float("inf") # variance (tref_precise) now that we're down to a bounded candidate set worth the extra fetch
n2, bid_thin = float("inf"), False
for t, qo in io["out"].items(): for t, qo in io["out"].items():
if t in mm: if t in mm:
continue continue
x = Q(t) x = Q(t)
se = sat.effective_supply(asks_of(t), x.vwap7 or x.ask, band=band_of(t)) se = sat.effective_supply(asks_of(t), x.vwap7 or x.ask, band=band_of(t))
n2 = min(n2, sat.n_out(sat.tref(x.traded7, x.traded30), se, demand_of(t), qo)) n2 = min(n2, sat.n_out(sat.tref_precise(t, a.cx, x.traded7, x.traded30), se, qo))
# Bid-book depth is a single LIVE SNAPSHOT (orders get added/withdrawn constantly) -
# not reliable enough to use as a hard cap like the flow-based n_out above, which
# aggregates real traded volume over 30 days. Surfaced as a warning flag instead, and
# measures a DIFFERENT thing than market/lim: not "can my patient asks clear" (that's
# p_patient()/n_out, ask-side, the real production-selling mechanism), but "could I
# instantly dump a day of output into resting BIDS right now if I needed cash" - panic-
# exit liquidity, not production price impact. A "yes" here doesn't guarantee it holds
# up over time, and a "no" might just be an unlucky instant - re-check before acting.
depth_units = sat.max_units_at_impact(bids_of(t), x.vwap7 or x.bid, a.max_impact)
bid_thin |= depth_units < qo
c["n_lim"] = float(a.max_n) if n2 == float("inf") else n2 c["n_lim"] = float(a.max_n) if n2 == float("inf") else n2
c["bid_thin"] = bid_thin
if c["n_lim"] < a.min_n and not a.show_thin: if c["n_lim"] < a.min_n and not a.show_thin:
continue continue
@@ -217,7 +232,7 @@ def main():
if t in mm: if t in mm:
p = mm[t] p = mm[t]
else: else:
p = sat.p_patient(asks_of(t), sat.tref(x.traded7, x.traded30), N * qo, x.bid, x.vwap7, x.vwap30, x.ask, band_of(t)[1]) p = sat.p_patient(asks_of(t), sat.tref_precise(t, a.cx, x.traded7, x.traded30), N * qo, x.bid, x.vwap7, x.vwap30, x.ask, band_of(t)[1])
rev += N * qo * p rev += N * qo * p
cost = 0.0 cost = 0.0
for t, qi in io["in"].items(): for t, qi in io["in"].items():
@@ -232,7 +247,7 @@ def main():
c["tons"] = max(wi, wo) c["tons"] = max(wi, wo)
frt = max(wi, wo, vi, vo) / a.cargo * a.trip_cost frt = max(wi, wo, vi, vo) / a.cargo * a.trip_cost
c["frt"] = frt c["frt"] = frt
dep = N * c["capex"] / a.deprec if a.deprec else 0.0 # value lost per day if demolished after holding dep = N * c["capex"] * (1 - a.reclaim_frac) / a.deprec if a.deprec else 0.0 # unreclaimed capex lost per day if demolished after holding
return rev - cost - N * c["wcost"] - frt - dep return rev - cost - N * c["wcost"] - frt - dep
if a.budget and c["capex"] > a.budget: if a.budget and c["capex"] > a.budget:
@@ -247,22 +262,28 @@ def main():
netN = evaluate(n_star) netN = evaluate(n_star)
if netN is None: if netN is None:
continue continue
area = n_star * ((c["b"].get("AreaCost") or 0) + c.get("hab_area_per_bld", 0.0))
rows.append(dict(roi1=100 * net1 / c["capex"], roiN=100 * netN / n_star / c["capex"], total=netN, n=n_star, rows.append(dict(roi1=100 * net1 / c["capex"], roiN=100 * netN / n_star / c["capex"], total=netN, n=n_star,
n_lim=c["n_lim"], lim=c["lim"], capex=c["capex"] * n_star, eff=c["eff"], bld=c["b"]["Ticker"], n_lim=c["n_lim"], lim=c["lim"], capex=c["capex"] * n_star, eff=c["eff"], bld=c["b"]["Ticker"],
top=c["top"], staff=c["staff"], tons=c.get("tons", 0), frt=c.get("frt", 0), h=c["rec"]["TimeMs"] / 3.6e6, thin=c["thin"], top=c["top"], staff=c["staff"], tons=c.get("tons", 0), frt=c.get("frt", 0), h=c["rec"]["TimeMs"] / 3.6e6,
thin=c["thin"], bid_thin=c.get("bid_thin", False),
area=area, profit_area=netN / area if area else 0.0,
rec=" ".join(f"{v:g}{k}" for k, v in c["ins"].items()) + " -> " + " ".join(f"{v:g}{k}" for k, v in c["outs"].items()))) rec=" ".join(f"{v:g}{k}" for k, v in c["ins"].items()) + " -> " + " ".join(f"{v:g}{k}" for k, v in c["outs"].items())))
key = {"roi": "roiN", "roi1": "roi1", "total": "total"}[a.sort] key = {"roi": "roiN", "roi1": "roi1", "total": "total", "area": "profit_area"}[a.sort]
rows.sort(key=lambda r: r[key], reverse=True) rows.sort(key=lambda r: r[key], reverse=True)
if a.json: if a.json:
import json import json
Path(a.json).write_text(json.dumps(rows)) Path(a.json).write_text(json.dumps(rows))
print(f"# {a.cx} tier<={a.tier or 'any'} cogc={a.cogc or '-'} faction={faction or '-'} ({pu}/{pt} permits) min-n>={a.min_n} sorted by {a.sort}") print(f"# {a.cx} tier<={a.tier or 'any'} cogc={a.cogc or '-'} faction={faction or '-'} ({pu}/{pt} permits) min-n>={a.min_n} sorted by {a.sort}")
print("# yld/d is profit/day / capex as a %, for OUR size (--own buildings, default 1) incl. our own price impact; this is NOT a compoundable rate (1/payback, see docs/decisions.md) - pback is the number to actually reason about. market = buildings the market could absorb (--min-n filters on it, nothing else). Net of freight. Patient asks near VWAP, inputs ask-walked; all estimates") print("# yld/d is profit/day / capex as a %, for OUR size (--own buildings, default 1) incl. our own price impact; this is NOT a compoundable rate (1/payback, see docs/decisions.md) - pback is the number to actually reason about. market = buildings the market could absorb (--min-n filters on it, nothing else). Net of freight. Patient asks near VWAP, inputs ask-walked; all estimates")
print(f"{'yld/d':>6} {'pback':>6} {'own':>3} {'market':>6} {'lim':4} {'profit/d':>11} {'capex':>9} {'eff':>4} {'bld':4} {'staff':5} {'t/d':>5} {'frt/d':>6} {'h':>5} recipe") print("# profit/area ranks by AIC/day per tile of TOTAL footprint - production building AreaCost PLUS the single-tier hab area its own workforce drags along (heads/100 x hab area, e.g. a 100-head pioneer building pulls a full HB1) - once a base's area cap binds (not cash), this is the real allocation criterion, not yld/d. --sort area to rank by it.")
print("# [exit-thin] = INSTANT-DUMP liquidity check, not production price impact: right now, the LIVE bid book can't absorb even 1 day of 1 building's output within --max-impact%% if you needed to sell immediately. A single snapshot (orders change constantly), NOT folded into market/lim (which measures patient ask-side selling via real 30d flow, the actual production mechanism). Re-check before acting on it.")
print(f"{'yld/d':>6} {'pback':>6} {'own':>3} {'market':>6} {'lim':4} {'profit/d':>11} {'capex':>9} {'area':>5} {'$/area':>7} {'eff':>4} {'bld':4} {'staff':5} {'t/d':>5} {'frt/d':>6} {'h':>5} recipe")
for r in rows[:a.top]: for r in rows[:a.top]:
pback = f"{100/r['roiN']:6.1f}" if r['roiN'] > 0 else " inf" pback = f"{100/r['roiN']:6.1f}" if r['roiN'] > 0 else " inf"
print(f"{r['roiN']:6.1f} {pback} {r['n']:3d} {r['n_lim']:6.1f} {r['lim']:4} {r['total']:11.0f} {r['capex']:9.0f} {r['eff']*100:4.0f} {r['bld']:4} {r['staff']:5} {r['tons']:5.0f} {r['frt']:6.0f} " flags = (' [thin]' if r['thin'] else '') + (' [exit-thin]' if r['bid_thin'] else '')
f"{r['h']:5.1f} {r['rec']}{' [thin]' if r['thin'] else ''}") print(f"{r['roiN']:6.1f} {pback} {r['n']:3d} {r['n_lim']:6.1f} {r['lim']:4} {r['total']:11.0f} {r['capex']:9.0f} {r['area']:5.0f} {r['profit_area']:7.1f} {r['eff']*100:4.0f} {r['bld']:4} {r['staff']:5} {r['tons']:5.0f} {r['frt']:6.0f} "
f"{r['h']:5.1f} {r['rec']}{flags}")
if __name__ == "__main__": if __name__ == "__main__":
+101 -8
View File
@@ -10,11 +10,27 @@ having cash in time) matters more than a few points of margin.
puga sell BHP 8 --cx AI1 puga sell BHP 8 --cx AI1
puga sell BHP 11 --tight # cash-tight: bias the split toward the aggressive tranche puga sell BHP 11 --tight # cash-tight: bias the split toward the aggressive tranche
puga sell BHP 8 --tiers # is pricing above the current market ever worth the wait?
--tiers answers "should I price above the current market" with TWO combined mechanisms, since
they are separate necessary conditions, not alternatives to average:
- queue-depth days: existing resting quantity ahead of you has to actually sell, at the real
historical trade-volume rate - valid only WITHIN the recently-traded price range (extrapolating
it past that would make a fat-finger outlier ask look "reachable").
- empirical first-passage probability: for a price with no resting quantity (above the whole
book, or outside the traded range), the market's own price level has to actually move up to
it - estimated directly from how often/how fast THIS ticker's real multi-year history has made
moves of that size (puga.history.empirical_touch), not assumed from a random-walk formula
(real prices mean-revert; see docs/decisions.md).
The two combine as: hit_factor (the empirical probability-and-timing-weighted value) shifted by
queue_days as a fixed extra delay (exp(-rho*queue_days)), since clearing the queue and waiting for
the price move are sequential, not alternative, requirements.
""" """
import argparse, datetime, statistics, sys import argparse, datetime, math, statistics, sys
from pathlib import Path from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent.parent)) sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
from puga import config, fio, market from puga import config, fio, market
from puga.history import trading_days, trade_gaps_days, daily_prices, full_series, empirical_touch
def quantile(xs: list[float], q: float) -> float: def quantile(xs: list[float], q: float) -> float:
@@ -28,10 +44,24 @@ def tranche_split(qty: float, trades: list[float], tight: bool) -> tuple[float,
return aggressive, qty - aggressive return aggressive, qty - aggressive
def daily_traded(tk: str, cx: str, days: int = 30) -> list[float]: def tier_table(prices: list[float], qty: float, s0: float, series: list, rate: float) -> list[dict]:
rows = [(datetime.datetime.fromtimestamp(e["DateEpochMs"] / 1000, datetime.timezone.utc).date(), e["Traded"]) """Discounted value of posting at each candidate price, using the EMPIRICAL first-passage
for e in fio.cxpc(tk, cx) if e.get("Interval") == "DAY_ONE" and e.get("Traded")] distribution of this ticker's own real multi-year price history (puga.history.empirical_touch),
return [t for _, t in rows[-days:]] not an assumed random-walk formula (real prices mean-revert; see docs/decisions.md). Has no
built-in monotonicity: if the real history shows diminishing willingness to move further, a
genuine interior optimum can appear instead of being forced by the model's shape.
"""
rows = []
for p in prices:
y = math.log(p / s0) if s0 else 0.0
if y <= 0:
stats = {"hit_factor": 1.0, "touched_frac": 1.0, "median_days": 0.0, "n": len(series)}
else:
stats = empirical_touch(series, y, rate)
rows.append({"price": p, "y": y, "hit_factor": stats["hit_factor"], "touch_frac": stats["touched_frac"],
"median_days": stats["median_days"], "n": stats["n"],
"revenue": p * qty, "discounted": p * qty * stats["hit_factor"]})
return rows
def main(): def main():
@@ -42,6 +72,8 @@ def main():
ap.add_argument("--undercut", type=float, default=10, help="AIC to undercut the current best ask by") ap.add_argument("--undercut", type=float, default=10, help="AIC to undercut the current best ask by")
ap.add_argument("--tight", action="store_true", help="cash-tight: bias the tranche split toward the aggressive (undercut) tranche") ap.add_argument("--tight", action="store_true", help="cash-tight: bias the tranche split toward the aggressive (undercut) tranche")
ap.add_argument("--show-bid", action="store_true", help="also show instant-bid revenue (usually worse than the tranche split; off by default)") ap.add_argument("--show-bid", action="store_true", help="also show instant-bid revenue (usually worse than the tranche split; off by default)")
ap.add_argument("--rate", type=float, default=0.05, help="your REALIZED daily capital growth rate (opportunity cost of waiting), not a theoretical build ROI - default 0.05 matches this account's observed equity-growth curve as of 2026-10-10; pass your own if it's moved")
ap.add_argument("--tiers", action="store_true", help="show discounted value (price*qty discounted at --rate over the implied wait) across all existing ask tiers, to check whether climbing the book is ever worth it")
a = ap.parse_args() a = ap.parse_args()
t = a.ticker.upper() t = a.ticker.upper()
ob = fio.order_book(t, a.cx) ob = fio.order_book(t, a.cx)
@@ -50,16 +82,28 @@ def main():
post = round((best_ask - a.undercut) if best_ask else (ob.get("Ask") or 0)) post = round((best_ask - a.undercut) if best_ask else (ob.get("Ask") or 0))
ahead = sum(u for p, u in asks if p < post) ahead = sum(u for p, u in asks if p < post)
trades = daily_traded(t, a.cx) days_window = 30
td = trading_days(t, a.cx, days_window)
trades = [v for _, v in td]
med = statistics.median(trades) if trades else 0 med = statistics.median(trades) if trades else 0
lo = sorted(trades)[int(0.2 * (len(trades) - 1))] if trades else 0 lo = sorted(trades)[int(0.2 * (len(trades) - 1))] if trades else 0
hi = sorted(trades)[int(0.8 * (len(trades) - 1))] if trades else 0 hi = sorted(trades)[int(0.8 * (len(trades) - 1))] if trades else 0
trade_frac = len(td) / days_window
gaps = trade_gaps_days([d for d, _ in td])
median_gap = statistics.median(gaps) if gaps else (days_window if len(td) <= 1 else 0)
print(f"{t}.{a.cx} best ask {best_ask} bid {ob.get('Bid')} vwap7 {ob.get('PriceAverage')}") print(f"{t}.{a.cx} best ask {best_ask} bid {ob.get('Bid')} vwap7 {ob.get('PriceAverage')}")
print(f"\npost {a.qty:g} at {post:.0f} ({ahead:.0f} units ahead of you at a lower price)") print(f"\npost {a.qty:g} at {post:.0f} ({ahead:.0f} units ahead of you at a lower price)")
print(f" revenue if filled: {post * a.qty:,.0f}") print(f" revenue if filled: {post * a.qty:,.0f}")
if med: if med:
print(f" expected clear time (last {len(trades)}d volume): busy day {24 * a.qty / hi:.1f}h | " print(f" trades on {len(td)}/{days_window} of the last {days_window} days ({100*trade_frac:.0f}%)"
+ (f", median gap between trading days: {median_gap:.0f}d" if gaps else ""))
if trade_frac < 0.5:
print(f" SPARSE TICKER: most days see no trade at all - don't expect a same-day fill by default. "
f"Once a trade happens, it tends to move: busy day {24 * a.qty / hi:.1f}h | median day {24 * a.qty / med:.1f}h | "
f"slow day {24 * a.qty / max(lo, 1):.1f}h for your quantity - but you may wait ~{median_gap:.0f}d first for a trade to happen at all")
else:
print(f" expected clear time (last {days_window}d volume): busy day {24 * a.qty / hi:.1f}h | "
f"median day {24 * a.qty / med:.1f}h | slow day {24 * a.qty / max(lo, 1):.1f}h") f"median day {24 * a.qty / med:.1f}h | slow day {24 * a.qty / max(lo, 1):.1f}h")
else: else:
print(" no recent trade history to estimate clear time") print(" no recent trade history to estimate clear time")
@@ -70,12 +114,61 @@ def main():
+ (f", SHORT: book only fills {hit['filled']:.0f}" if hit["short"] else "") + ")") + (f", SHORT: book only fills {hit['filled']:.0f}" if hit["short"] else "") + ")")
print(f" posting patiently gains {post * a.qty - hit['total']:,.0f} over this, at the cost of waiting") print(f" posting patiently gains {post * a.qty - hit['total']:,.0f} over this, at the cost of waiting")
if a.tiers:
dp = daily_prices(t, a.cx)
s0 = sorted(dp.items())[-1][1][0] if dp else (best_ask or ob.get("Ask") or 0)
series = full_series(t, a.cx)
rho = math.log(1 + a.rate)
tier_prices = sorted({p for p, _ in asks} | {post, s0})
rows = tier_table(tier_prices, a.qty, s0, series, a.rate)
# Queue-depth days: valid ONLY within the range this ticker has genuinely traded in -
# the mechanism it models (real buy flow eating through resting ahead-quantity) has no
# evidence to extrapolate beyond that (this is what made a fat-finger outlier ask look
# reachable before). Outside that range it's infinite (no constraint from this mechanism;
# the empirical median_days alone governs).
cutoff_date = datetime.datetime.now(datetime.timezone.utc).date() - datetime.timedelta(days=days_window)
recent_prices = [p for d, (p, _) in dp.items() if d >= cutoff_date]
cutoff_price = max(recent_prices + [best_ask or 0]) * 1.1 if recent_prices else float("inf")
med_vol = med or 1
for r in rows:
ahead = sum(u for p, u in asks if p < r["price"])
# Outside the recent-traded range the queue mechanism doesn't meaningfully apply (no
# real evidence that cumulative ahead-quantity, much of it itself unreachable junk
# asks, clears at the normal rate) - that means "not a binding constraint" (0), NOT
# "infinite constraint".
r["queue_days"] = (ahead + a.qty) / med_vol if r["price"] <= cutoff_price else 0.0
# Rank by hit_factor (the real empirical E[e^-rho*tau] from tier_table), with
# queue_days folded in as a FIXED, deterministic shift of tau: shifting a random delay
# by a constant multiplies its Laplace transform by exp(-rho*shift), which is exactly
# right when "clear the real resting queue, THEN wait for price to reach this tier"
# are sequential, not alternative, constraints. median_days (shown separately below)
# is not used for the value itself - plugging a point estimate into (1+rate)^-days
# would be biased by Jensen's inequality, and None (<50% touched) would wrongly zero
# out a tier that hit_factor still values smoothly.
r["combined_hit"] = r["hit_factor"] * math.exp(-rho * r["queue_days"])
r["discounted_combined"] = r["revenue"] * r["combined_hit"]
best = max(rows, key=lambda r: r["discounted_combined"]) if rows else None
print(f"\nTIER TABLE (last traded {s0:.0f}, {len(series)}d history, rate {100*a.rate:.1f}%/day - see --help):")
print(f" {'price':>10} {'queue(d)':>9} {'touched':>8} {'median(d)':>10} {'hit%':>6} {'revenue':>10} {'discounted':>11}")
for r in rows:
flag = " <- best" if best is r else ""
qd = f"{r['queue_days']:.1f}" if r["queue_days"] != float("inf") else "n/a"
md = f"{r['median_days']:.1f}" if r["median_days"] is not None else "never"
print(f" {r['price']:>10.0f} {qd:>9} {100*r['touch_frac']:>7.0f}% {md:>10} {100*r['combined_hit']:>5.1f}% "
f"{r['revenue']:>10,.0f} {r['discounted_combined']:>11,.0f}{flag}")
if best and best["price"] > s0:
print(f" climbing to {best['price']:.0f} beats selling now")
else:
print(f" selling at/near the current price ({s0:.0f}) dominates")
aggr_qty, patient_qty = tranche_split(a.qty, trades, a.tight) aggr_qty, patient_qty = tranche_split(a.qty, trades, a.tight)
if patient_qty > 0.01: if patient_qty > 0.01:
tiers_above = sorted({p for p, u in asks if p > post}) tiers_above = sorted({p for p, u in asks if p > post})
patient_price = round(tiers_above[0] - 1) if tiers_above else round(post + 2 * a.undercut) patient_price = round(tiers_above[0] - 1) if tiers_above else round(post + 2 * a.undercut)
q_label = "80th pct (tight)" if a.tight else "median" q_label = "80th pct (tight)" if a.tight else "median"
print(f"\nTRANCHE SPLIT ({q_label} volume quantile, {len(trades)}d):") print(f"\nTRANCHE SPLIT ({q_label} volume quantile, {len(trades)} trading days in the last {days_window}d):")
print(f" aggressive: {aggr_qty:.1f} @ {post:.0f} (confident to clear today)") print(f" aggressive: {aggr_qty:.1f} @ {post:.0f} (confident to clear today)")
print(f" patient: {patient_qty:.1f} @ {patient_price:.0f} (waits behind the next tier, higher margin)") print(f" patient: {patient_qty:.1f} @ {patient_price:.0f} (waits behind the next tier, higher margin)")
print(f" vs posting all {a.qty:g} at {post:.0f}: gains {patient_qty*(patient_price-post):,.0f} extra if the patient tranche fills") print(f" vs posting all {a.qty:g} at {post:.0f}: gains {patient_qty*(patient_price-post):,.0f} extra if the patient tranche fills")
+5 -3
View File
@@ -107,9 +107,11 @@ def trip_tonnage(flows: dict, mats: dict):
def marginal_freight(r_b, r_a, planet_id, cx, sf_price, ff_price, mats): def marginal_freight(r_b, r_a, planet_id, cx, sf_price, ff_price, mats):
"""AIC/day freight for the EXTRA trips this addition requires - not the base's whole freight """AIC/day freight for the EXTRA trips this addition requires - not the base's whole freight
bill. If the addition's materials fit in slack the base's existing traffic already has (the bill. Continuous amortized rate (extra tonnage/cargo-hold x round-trip cost), proportional to
common case for a small addition), this comes out to ~0: real freight cost only kicks in once the addition's own tonnage, not a step function - a small addition gets a small freight charge,
net t/m3 crosses into needing another round trip. Returns (freight_aic_per_day, note).""" not exactly zero (that would need a real per-trip ceiling/rounding this doesn't model). Still
catches a recipe whose ROI looks great only because its freight cost was left out. Returns
(freight_aic_per_day, note)."""
origin = shipping.cx_system(cx) origin = shipping.cx_system(cx)
if origin is None: if origin is None:
return 0.0, f"no station found for CX {cx!r} - freight not modelled" return 0.0, f"no station found for CX {cx!r} - freight not modelled"