Using the Companion

The companion in examples/capacity_portfolio follows the constructed planning cycle from the book, so you can change an assumption and see how far its consequences travel. You need Python 3.9 or later and the standard library; you can run it without cloud credentials, paid services, or a production account.

The companion is published under the Apache License 2.0 at https://github.com/withoutsurprise/scale-without-surprise-companion. Clone the repository or download it as a ZIP archive, then, from the directory that contains examples/, run:

python3 examples/capacity_portfolio/run.py

The report appears in examples/capacity_portfolio/output/report.md. The same directory contains a detailed JSON report and CSV files for forecasts, backtests, and decision responsibilities. The companion’s README describes every input and the limits of the example.

I would start with fixtures/portfolio.json, which defines the service, resource pools, prices, failure groups, and supply assumptions, then read fixtures/observations.csv alongside fixtures/events.json. Pay attention to the observation date, the date each value became available (available_on), and the event revision: they let the program distinguish what happened from what a planner could have known when making the decision.

Try changing the supply readiness date first. In portfolio.json, new_supply_ready_days puts the new failure group’s qualified-ready date at day 42; Chapter 22 works through moving it to day 56. Then try a different rollout increment or a lower qualified worker rate. Edit gross_increment in revision 1 of the rollout event; revision 2 becomes known only after the June 28 forecast, so the program keeps it out. If tested_requests_per_worker_second falls from 250 to 220, the staged plan with transferred workers is 120 requests per second short after a group loss. The report’s decision section is a proposal declared in the fixture and will not change, so read the supply table and revise the proposal yourself. Changing one assumption at a time makes it easier to see why an answer moved, while keeping the distinction between a scenario you can explore and a service whose behavior you would have to measure.

Run the companion’s checks with:

python3 -m unittest discover \
  -s examples/capacity_portfolio -p 'test_*.py'

A passing run ends with OK. These checks cover time boundaries, information leakage, duplicate events, incompatible units, failure-group arithmetic, cost reconciliation, the AI examples, Volume I, Chapter 1’s ledger, and Volume I, Chapter 5’s search mix. They do not certify a real forecast or service configuration.

Two smaller scripts reproduce the rest of the constructed arithmetic. The first covers Volume I, Chapter 1’s ledger in all five views, Volume I, Chapter 5’s search mix, and the portfolio examples in Volume I, Chapter 5 and Volume II, Chapter 15; the second covers the database arithmetic in Volume I, Chapter 12:

python3 examples/portfolio_math.py
python3 examples/data_capacity_math.py

The figures in Volume I, Chapter 4 and Volume II, Chapter 14 can be regenerated with:

python3 examples/capacity_portfolio/figures.py

The script replaces both figures’ SVG sources in manuscript/figures, next to examples/, so work in a copy if you want to keep the shipped versions.

The mathematical core stays separate from provider collection. Volume I, Chapter 6 supplies read-only Azure inventory, monitoring, and recommendation examples, together with a cost-export example. They illustrate how measured inputs could be collected; they are not an installed adapter and were checked against documentation rather than run against a live cloud account. Database and AI benchmark references point to specialist tools, not measurements performed for this manuscript.

If you extend the project, the interesting work will be bringing in measured inputs, dated demand intelligence, and evidence that the relevant specialists have examined. Keep the old decision when you revise it, so that you can understand what changed and why. The software gives us a way to keep that history and expose contradictions; we still have to obtain the evidence and help the people affected decide what to do with it.