(mal)functioning prototype: https://wyrrdmaek.netlify.app/
flock/ is a population simulator for synthetic people, written to be tested against by AI agent
swarms. It is algorithmic: plain Python, standard library only, no model and no learning at runtime.
People have commitments, a bedtime and an alarm, minutes since their last meal, and a weighted
choice of free activities by hour band. Households and workplaces own the shared times, so commute
waves and the lunch peak come out of the population rather than being written down. Agents observe
people, ping them, request slots and send invites, and get replies delayed by what the person is
doing.
python -m flock day --person 17 --day tue
python -m flock histogram --day weekday
python -m flock checks --seed 1 --people 400 --weeks 4
python -m flock demo-swarm
There is a browser interface too. The site's landing page offers a choice between it and the earlier prototype's workbench; both run their Python in the browser under Pyodide.
| Page | What it is |
|---|---|
/ |
the choice between the two |
/flock/ |
flock: a person's day, the population's day, the agent API, the checks |
/workbench.html |
the earlier prototype, unchanged |
See flock/README.md for the commands and the agent API, and flock/NOTES.md for every decision taken, the numbers behind each claim, and the seeds and population sizes on which the realism checks fail.
checks runs 52 realism tests against published time-use figures. All 52 pass on seeds 1-5 at 400
people over 4 weeks and at 1000 people over 4 weeks, which takes about 12 seconds.
Everything below, and the code in engines/, modules/, rigs/, tes/ and web/, is the earlier
attempt. It generates a week of schedules per isolated person and is kept for reference. Its known
limits: durations were inflated by a multiplier applied to every activity including sleep, activities
were placed end to end so an overrun pushed later ones into the night, days were boxed at midnight so
sleep was truncated, and people were simulated independently of each other.
Procedural generation tools for believable synthetic schedules and environments.
Wyrd Engine provides deterministic and probabilistic generators that create minute-by-minute schedules across a full week. The modular design separates core algorithms (engines), reusable capabilities (modules), and integration layers (rigs) so teams can mix and match features without rewriting pipelines.
- MK1 deterministic core. A reproducible placement engine that fills schedules from explicit constraints.
- MK2 behavioural engine. Introduced friction, fatigue, and cultural context to generate varied yet realistic days.
- Modular rigs. Engines now plug into calendar, validation, and workforce rigs, letting applications swap features or extend the system with custom modules.
- Prepare a deterministic config (see
tests/fixtures/deterministic_sample_config.json). - Run:
python cli.py --engine mk1 --rig simple --config tests/fixtures/deterministic_sample_config.json --output mk1_simple.json
- Review the JSON schedule and printed activity totals.
- Choose an archetype (office, parent, freelancer).
- Run:
python cli.py --engine mk2 --rig calendar --archetype office --output mk2_calendar.json --seed 7
- Inspect the generated week; the calendar rig injects holidays and seasonal adjustments.
- Optionally customise the yearly budget (see
examples/yearly_budget_alice.json). - Run:
python cli.py --engine mk2 --rig workforce --archetype parent --yearly-budget examples/yearly_budget_alice.json --output mk2_workforce.json
- Check the diagnostics for friction effects, unique days, and validation results.
- Live site: https://wyrrdmaek.netlify.app/
- Browser UI supports MK2 directly. Run a script in the Test Console and switch back to the Calendar tab to regenerate the MK2 schedule with the engine dropdown.
- Generate a run in the Test Console. Switch to the Test Console tab, click Load Runtime, and pick Run MK2 quick test (or your own script). Update the Runner config JSON and execution inputs as needed, then hit Run. The Stdout/Stderr/Result panels capture the MK2 engine output.
- Load it in Visualisation. Return to the Calendar tab. Paste the same config you used in the Test Console into Configuration JSON, optionally set the start date, and press Generate schedule. The calendar, weekly totals, and MK2 replay wheel unlock once the run is recreated in the browser.
- Play the 5s recap. With a schedule loaded, press Replay GIF or Replay MP4. The radial visualisation animates a five second MK2 recap while the export renders.
- Inspect JSON ↔ arcs. Hover or tap arcs in the minute picker to highlight matching entries in the Event JSON list (and vice versa). The label above the wheel reports the current minute span, day, and activity.
- Export/share. Use Download JSON for the schedule, Frame PNG/SVG for stills, and the replay exports (GIF/MP4) to share the animated forensic view. Status messages confirm when each export is ready.
engines/ Core scheduling algorithms (MK1, MK2)
modules/ Optional capabilities (calendar, friction, validation)
rigs/ Composition layer combining engines + modules
web/ Static browser implementation
docs/ Extended documentation and design history
tests/ Unit and integration tests
- Architecture overview – High-level map of engines, modules, and rigs.
- Calendar generator history – Evolution notes and prototypes.
- Release notes – Highlights for the v3.0-modular release.
Run the test suite:
pytest tests/ -vAll generators produce validated schedules: exactly 1440 minutes per day with no overlaps.
MIT