Appendix C — Setting Up the Companion Code

The code in this book is meant to be run, not admired. Every load-bearing listing in the text is a faithful excerpt of a module that lives, in full and runnable, in the companion repository:

https://github.com/bloo-mind/masact-code

This appendix is the practical companion to that repository — how it is organised, how to run it, and where each of the book’s listings comes from. Like everything else here it is a snapshot of a moving target: the book is written in public, and the repository fills in alongside it, so treat the state described below as the state at the time of going to press, and the repository’s own README as the current truth.

C.1 The Three Layers

The repository is organised in three layers, and the division is the same one the preface drew — deliberately, so that the durable content depends on as little as possible and the perishable content is quarantined where it can rot without taking the rest down with it.

Table C.1: The three layers of the companion repository, from the durable standard-library core to the deliberately perishable frontier. The division is the point — each layer carries exactly as much churn as it must, so a vendor’s rename is the frontier’s problem and never the theory’s.

Layer	Install	Needs	What it demonstrates
Foundations (`foundations/`)	`uv sync`	Nothing — the standard library alone; no model, no network	Transparent implementations behind every printed listing — the Chapter 20 runtime, the classical algorithms, Chapter 18’s simulations
Systems (`systems/`)	`uv sync --extra systems`	LangGraph and one model-provider key, read from `.env`	The same ideas at production scale — Chapter 23’s hardened team, Chapter 24’s triple experiment
Frontier (`frontier/`)	`uv sync --extra frontier`	Vendor accounts, keys, and current SDKs	Dated laboratories on live platforms — Chapter 19’s scorecard, Chapter 21’s census, Chapter 22’s bench, Chapter 27’s scaling lab

The foundations layer (foundations/) contains small, transparent implementations of the algorithms and mechanisms the book discusses, with dependencies kept to a minimum — in fact, to nothing at all: it runs on the Python standard library alone. This is where the from-scratch runtime of Chapter 20 lives, module for module, and where the classical algorithms named across the book — Lamport clocks, the jury theorem, Dung’s grounded extension, the exact Shapley value, and the rest — are set down in a form you can read in one sitting and, more to the point, import and run. It is the layer that backs the listings printed in the text, and the only layer this appendix asks you to be able to run today.

The systems layer (systems/) contains larger projects built with a modern orchestration framework — principally LangGraph — demonstrating typed state, persistence, streaming, human approval, tracing, evaluation, and deployment. Where the foundations layer shows what the framework is doing on your behalf in plain Python, the systems layer shows the same ideas at production scale in the framework itself; Chapter 23 builds each dependability mechanism both ways on purpose, and the correspondence is the lesson. These projects are substantial enough to fail in educationally useful ways.

The frontier layer (frontier/) contains versioned online laboratories involving current commercial and open-source agent platforms, including coding-agent teams. Because these platforms rename their APIs at leisure, the laboratories are dated and maintained separately from the conceptual core, so that a vendor’s next reorganisation is an afternoon’s maintenance rather than a correction to the theory.

C.2 Getting Started

The toolchain is the one the book itself is built with: a recent Python and uv for environments and dependencies.

Python 3.12 or newer. The code uses modern type hints (list[str], X | None), structural pattern matching, and dataclasses throughout.
uv, for a reproducible environment without ceremony.

The foundations layer needs nothing else. Clone the repository, sync the environment, and run the tests:

git clone https://github.com/bloo-mind/masact-code.git
cd masact-code
uv sync
uv run pytest

A green suite means the standard-library core — the runtime and every classical algorithm the book prints — works on your machine exactly as it does in the text. To watch the book’s running example actually run, invoke the software- engineering team on a toy task:

uv run python -m foundations.demo_team

Every model in that demonstration is a FakeClient replaying a script, so it is deterministic and spends no tokens; swap in a real client that calls a provider, and the same harness drives a live team.

C.3 Keys, Environments, and the Upper Layers

Nothing in foundations/ calls a model or the network, so it needs no keys. The systems and frontier layers do, and they declare their extra dependencies separately so that the core stays light:

uv sync --extra systems     # LangGraph and friends, for systems/
uv sync --extra frontier    # the vendor SDKs and MCP as well, for frontier/

Model-provider keys are read from the environment; copy the repository’s .env.example to .env and fill in the providers you intend to use. Which layer needs what is the Needs column of Table C.1; the repository’s README carries the current, exact list.

C.4 From the Page to the Repository

The listings in the book are not toys reprinted for effect; each is an excerpt or a core of a real module here. Chapter 20’s runtime excerpts — the model client, the agent loop, context assembly, the journal, the messages, the merge gate — are verbatim slices of the files under foundations/, so a line you copy from the chapter is a line that runs in the repository. The smaller standalone listings — the speedup model of Chapter 1, the retrieval score of Chapter 7, the jury sum of Chapter 13, the grounded extension of Chapter 14, the exact Shapley value of Chapter 16, the dependability cores of Chapter 23, and the rest — each open a module under foundations/algorithms/, surrounded there by the tests that pin their behaviour and the extensions the chapter left as an exercise. The emergence simulations of Chapter 18 — Schelling’s segregation, the naming game, the information cascade — live under foundations/emergence/, seeded so that a run is reproducible.

What is not in the book is the labs: the LLM-agent harnesses, the experiments, the stress tests, and the plotting, all of which live in the repository because they are too large, too dependent on a live model, or too quick to date for the page. The per-chapter exercises point to them, and the repository’s directory structure follows the book’s parts, so finding the code for a chapter is a matter of following the chapter number.

C.5 A Repository Under Construction

The book is a live manuscript, and so is its code — but the code has caught up with the manuscript. The foundations layer is complete and tested, since the text depends on it; the systems layer builds Chapter 23’s hardened team and Chapter 24’s triple experiment on LangGraph; and the frontier layer runs the laboratories the later chapters argue for — the framework scorecard of Chapter 19, the interoperability bench of Chapter 22, the pattern census of Chapter 21, and the capstone scaling lab of Chapter 27 — each an instrument over one shared measurement rig, all exercised by a hermetic test suite that needs no model or key. What keeps this section’s title honest is the frontier layer’s standing condition: its laboratories are dated, plugged into vendor SDKs that rename their APIs at leisure, so they are maintained apart from the conceptual core and are expected to need updating — a construction site not because the building is unfinished but because the ground keeps moving. A reader who finds a lab out of step with a platform’s latest rename has found not a defect but the frontier behaving as advertised, and is warmly invited to mind the scaffolding, run what is there, and open an issue — or better, a pull request — about what has drifted. A book about collective intelligence should, at the very least, accept one.