mirror of
https://github.com/saymrwulf/crisis.git
synced 2026-05-14 20:37:54 +00:00
saymrwulf
54aae1a4dd
Three sweeping additions and one new file, reflecting how the project
has grown:
* Parent `README.md` rewritten. The architecture mermaid now shows
`crisis_agents` as a third sibling layer on top of the pure
protocol algorithms, alongside the CrisisNode TCP runtime and the
SimulatedNode in-process recorder. A fourth audience-shaped quick
start (🤖 "run the AI-agent coordination demo") joins the
protocol-pytest, simulation-CLI, and visualizer entries. The
repository-layout tree expands to enumerate `src/crisis_agents/`'s
modules. Test count corrected (~170).
* New `src/crisis_agents/README.md`. Comprehensive package
documentation:
- threat model + what's out of scope
- the two principles enforced by tests: no chokepoint, no clock
- mental-model mermaid (closed phase → boundary opens → async
loop → quorum vote → multi-signer proof)
- six-phase walkthrough matching the CLI output
- module-by-module reference table
- reuse map from `src/crisis/` (Message, LamportGraph,
find_mutations, ProofOfWorkWeight, etc.)
- build/run/test instructions including the `--live` Claude path
- quorum-threshold formula in LaTeX: ⌈2N/3⌉
- test taxonomy with the two sentinel files
(test_no_chokepoint, test_async_quiescence) highlighted
* `INSTALL.md` extended. New Section 4 covers running the
`crisis-agents demo`, both mocked-deterministic and `--live` with
real Claude sub-agents. Anthropic SDK shown as optional `[live]`
extras. Old sections renumbered (Section 5 → Section 6 for Swift,
6 → 7 for Troubleshooting). Two new troubleshooting entries for
live-mode failures.
* `CrisisViz/HANDOFF.md` gets a new Section 0. Brief notice that a
sibling Python sub-project (`crisis_agents`) now exists, what it
does, and — most importantly — that it doesn't share code with
CrisisViz: refactoring one cannot break the other. Cross-link to
the crisis_agents README so a future Swift-side agent has the
pointer without having to discover it via grep.
Source-of-truth corrections in the parent README:
- the "three audiences" framing becomes four
- the layout tree now lists `src/crisis_agents/`
- the architecture diagram explicitly marks the agent layer as
"decentralized, asynchronous" (the two principles the recent
refactors enforce)
CrisisViz code: still untouched by all this. Only its HANDOFF doc
gets a heads-up paragraph.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
179 lines
6.6 KiB
Markdown
179 lines
6.6 KiB
Markdown
# INSTALL — Crisis, CrisisViz, and crisis_agents
|
|
|
|
End-to-end setup on a fresh macOS box: from blank checkout to running protocol tests, the agent-coordination demo, and the SwiftUI visualizer. Follow top-to-bottom.
|
|
|
|
---
|
|
|
|
## 1. Prerequisites
|
|
|
|
| Tool | Minimum | How to install |
|
|
|---|---|---|
|
|
| **macOS** | 26 Tahoe | The Swift visualizer targets `.macOS(.v26)`. The Python side runs on any macOS with Python ≥3.11. |
|
|
| **Xcode** | 17 | `xcode-select --install` for command-line tools only, or the full Xcode app from the App Store. Provides Swift 6.2 + the macOS 26 SDK. |
|
|
| **Python** | 3.11 | Pre-installed on recent macOS; otherwise `brew install python@3.11`. |
|
|
| **git** | any | `xcode-select --install` installs it. |
|
|
| **Homebrew** | optional | Only needed if you don't already have Python 3.11. Install per [brew.sh](https://brew.sh). |
|
|
|
|
Verify:
|
|
|
|
```sh
|
|
sw_vers # ProductVersion: 26.x
|
|
xcodebuild -version # Xcode 17.x
|
|
swift --version # swift-driver version: 1.x (Apple Swift version 6.2)
|
|
python3.11 --version # Python 3.11.x
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Clone and verify
|
|
|
|
```sh
|
|
git clone https://github.com/saymrwulf/crisis.git
|
|
cd crisis
|
|
ls Crisis.mirco-richter-2019.pdf # the spec — must exist
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Python side — protocol PoC
|
|
|
|
Create a virtualenv and install the package in editable mode with dev extras:
|
|
|
|
```sh
|
|
python3.11 -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install --upgrade pip
|
|
pip install -e ".[dev]"
|
|
```
|
|
|
|
Run the unit tests to verify the algorithm implementations:
|
|
|
|
```sh
|
|
pytest -q
|
|
```
|
|
|
|
Expected: ~170 tests, all green in under a second. If any fail, stop and investigate before continuing — both the visualizer's data pipeline and the agent-coordination layer depend on these.
|
|
|
|
Try a deterministic in-process simulation:
|
|
|
|
```sh
|
|
python -m crisis.demo --nodes 3 --byzantine 0 --rounds 5
|
|
```
|
|
|
|
You should see consensus rounds advance and a total order emerge.
|
|
|
|
---
|
|
|
|
## 4. Run the AI-agent coordination demo
|
|
|
|
The `crisis-agents` CLI walks a six-phase scenario end-to-end: a closed honest team, a byzantine joiner who equivocates on a fact-check statement, an asynchronous gossip + detection event loop, quorum-ratified alarm, and a multi-signer proof JSON.
|
|
|
|
### 4a. Mocked agents (deterministic, no API costs)
|
|
|
|
```sh
|
|
crisis-agents demo --out-dir /tmp/crisis_demo
|
|
```
|
|
|
|
Output ends with `proof_<accused>_<statement>.json` in `--out-dir`. To self-verify a proof:
|
|
|
|
```sh
|
|
crisis-agents verify /tmp/crisis_demo/proof_*.json
|
|
```
|
|
|
|
### 4b. Real Claude sub-agents (`--live`)
|
|
|
|
Install the optional Anthropic SDK extras:
|
|
|
|
```sh
|
|
pip install -e ".[live]"
|
|
export ANTHROPIC_API_KEY=sk-ant-...
|
|
crisis-agents demo --live --model claude-haiku-4-5-20251001
|
|
```
|
|
|
|
This swaps the three scripted honest agents for `LiveClaudeAgent` instances backed by real Anthropic Messages API calls. The byzantine stays scripted so the equivocation is reliably reproducible. Costs API credits; output is non-deterministic.
|
|
|
|
Architecture reference: **[src/crisis_agents/README.md](src/crisis_agents/README.md)**.
|
|
|
|
---
|
|
|
|
## 5. Regenerate `crisis_data.json` (optional)
|
|
|
|
The repo ships with a pre-recorded `crisis_data.json` at the root and a bundled copy in `CrisisViz/Sources/CrisisViz/`. Regenerate when you change the protocol code or want a different simulation:
|
|
|
|
```sh
|
|
python -m crisis.export_json --steps 80 -o crisis_data.json
|
|
cp crisis_data.json CrisisViz/Sources/CrisisViz/crisis_data.json
|
|
```
|
|
|
|
The defaults (6 honest + 1 byzantine, 80 steps) produce full convergence from step 40 onward — the visualizer's chapters on total order and Byzantine detection depend on having a converged tail.
|
|
|
|
---
|
|
|
|
## 6. Swift side — the visualizer
|
|
|
|
### 6a. Quick dev loop
|
|
|
|
```sh
|
|
cd CrisisViz
|
|
swift build # ~4s on Apple Silicon
|
|
swift run CrisisViz # launches the dev binary
|
|
```
|
|
|
|
Note: the dev binary does not have a Dock icon and lives in `.build/`. For a real `.app` use `bundle.sh`.
|
|
|
|
### 6b. Build the `.app` bundle
|
|
|
|
```sh
|
|
./bundle.sh # build + assemble CrisisViz.app + open
|
|
./bundle.sh --no-launch # build only
|
|
```
|
|
|
|
`CrisisViz.app` is created in the current directory. Open it from Finder or the Dock to get the full activation-policy behavior.
|
|
|
|
### 6c. Build a DMG installer
|
|
|
|
```sh
|
|
./package-dmg.sh # produces CrisisViz.dmg in the current directory
|
|
```
|
|
|
|
The DMG is ad-hoc signed — on first open macOS Gatekeeper will refuse to launch the app directly. Right-click `CrisisViz` in `/Applications` → **Open** → **Open** in the confirmation dialog. macOS remembers your approval; subsequent launches behave normally.
|
|
|
|
Distribution flow for a new machine:
|
|
1. Copy `CrisisViz.dmg` to the target Mac.
|
|
2. Double-click to mount.
|
|
3. Drag `CrisisViz` onto the `Applications` symlink.
|
|
4. Eject the DMG; launch from `/Applications` (right-click → Open the first time).
|
|
|
|
### 6d. Run the QA testbed
|
|
|
|
```sh
|
|
swift run CrisisViz --testbed
|
|
```
|
|
|
|
Writes to `~/Desktop/CrisisViz_Testbed/`:
|
|
|
|
- `INVARIANTS.md` — 38 logical curriculum assertions
|
|
- `SOURCE_AUDIT.md` — forbidden-pattern scan (lane jitter, hardcoded palette, etc.)
|
|
- `VIDEO_CLIPS.md` — 36 MP4 clips at 8s / 30fps
|
|
- `MANIFEST.md` — PNG sweep across all scenes / time offsets
|
|
- `SANITY.md` — file-size and freeze-frame checks
|
|
|
|
All five should be green before shipping changes.
|
|
|
|
---
|
|
|
|
## 7. Troubleshooting
|
|
|
|
**`swift build` fails with “unsupported deployment target”.** Your Xcode does not provide the macOS 26 SDK. Update Xcode to ≥17, or downgrade `Package.swift` to your installed SDK (not recommended — visual features depend on macOS 26 Liquid Glass APIs).
|
|
|
|
**`swift run CrisisViz` shows a blank window.** The bundled `crisis_data.json` is missing or empty. Run `cp crisis_data.json CrisisViz/Sources/CrisisViz/crisis_data.json` and rebuild.
|
|
|
|
**Gatekeeper refuses to open the app from the DMG.** Right-click → **Open** the first time. Or remove the quarantine attribute manually: `xattr -dr com.apple.quarantine /Applications/CrisisViz.app`.
|
|
|
|
**`pytest` fails on `ModuleNotFoundError: crisis`.** Activate the venv (`source .venv/bin/activate`) and reinstall with `pip install -e ".[dev]"`. The `-e` (editable) flag is what makes `import crisis` resolve to `src/crisis/`.
|
|
|
|
**The visualizer freezes mid-chapter / animations are stuck.** You're running the unbundled `swift-run` binary while the Dock icon launches `CrisisViz.app`. Rebuild the bundle: `./bundle.sh --no-launch && open CrisisViz.app`.
|
|
|
|
**`crisis-agents --live` fails with `live mode requires the anthropic SDK`.** Install the optional extras: `pip install -e ".[live]"`. The mocked path doesn't need this dependency.
|
|
|
|
**`crisis-agents --live` fails with `ANTHROPIC_API_KEY`.** Export the key before running: `export ANTHROPIC_API_KEY=sk-ant-...`. The SDK reads it from the environment.
|