mesa / mesa/mesa-examples

Call for examples: Mesa's new event-driven behavior APIs

Open
#492 2 comments 0 reactions 0 assignees View on GitHub
help wanted new_example
Dominant language
Python
Stars
252
Forks
279
Avg merge
8d 9h
Merged PRs (30d)
2

Description

Mesa core has been growing a set of experimental APIs for event-driven agent behavior, and I think mesa-examples should have some models showing them off. Opening this issue to collect ideas and coordinate who works on what.

### Quick background

Mesa 4 runs on continuous time and a single event list, there are no ticks anymore. Two experimental toolkits sit on top of that:

- `mesa.experimental.states` (projectmesa/mesa#3766): `ContinuousState` stores a base value + rate and extrapolates the value when you read it, and `Threshold` computes analytically when a state will cross a limit and schedules exactly one event there. Limits are reactive, so rewriting one re-arms the threshold on its own.
- `mesa.experimental.actions` (projectmesa/mesa#3801, projectmesa/mesa#3805, projectmesa/mesa#3833): timed, interruptible actions with start/completion requirements and a FAILED state, priority based preemption through `should_interrupt`, and an `on_idle` hook that wakes the agent whenever its action ends so it can decide what to do next.

The overall design is tracked in projectmesa/mesa#3798 if you want the rationale. Also note the agent-side API is currently moving behind a `HasActions` mixin (projectmesa/mesa#3851), check where that stands before you start.

### The reference example

Have a look at the [Tram Route Model](https://mesa.readthedocs.io/latest/examples/experimental/tram_model.html) ([source](https://github.com/projectmesa/mesa/tree/main/mesa/examples/experimental/tram_model)). The tram accelerates, cruises, brakes and dwells along its route, and every one of those transitions is a threshold crossing. There is no step logic at all, `step()` only samples data for plotting, and you can delete it without changing the tram's timings. New examples should aim for that style.

### Ideas

Note: I drafted this list with help from Claude, so review an idea properly before building it, some details may need adjusting against the actual API. And please comment here before starting so we avoid duplicate work, then wait for a go-ahead in the thread before opening a PR.

1. **EV charging station.** Battery as a `ContinuousState` that drains while driving and charges while docked, thresholds at empty/full, chargers as contested resources claimed through start requirements.
2. **Machine shop with breakdowns.** Jobs are actions with durations, machines fail mid job, repair preempts via priority, and `on_idle` pulls the next job from the queue.
3. **Elevator bank.** Position and speed as chained states, thresholds at floor boundaries, call buttons rewriting the reactive limits. Basically the tram mechanics in a different setting.
4. **Predator stalking.** Stalk/chase/flee as actions, with `should_interrupt` encoding temperament and threat levels as callable priorities.
5. **Thermostat house.** Room temperature as a state, heating and cooling as rates, thermostat thresholds flipping between them. Probably the smallest possible demo, good first contribution.
6. **Ferry or bus line.** Extends the tram pattern with passengers whose boarding is an interruptible action.

OR ANYTHING.

### Practical stuff

- Usual example layout: `model.py`, `agents.py`, `app.py` plus a README. Copy the tram's structure.
- These are `mesa.experimental.*` APIs, they can change without deprecation, so mention which mesa commit you built against in your PR.
- One example per PR, small and clear beats big and clever.
- Using an LLM to help is fine. Submitting its output unverified is not. Run your example yourself, understand every API it touches, and say in the PR description what you personally tested. PRs that look generated and unverified will be closed without review.
- Questions welcome here, design level discussion belongs in projectmesa/mesa#3798.

Contributor guide

Open the contributing guide

Research direction

Start by reading and running the experimental tram model in mesa/examples/experimental/tram_model, then check the current mesa.experimental.states and mesa.experimental.actions APIs and the HasActions status. Comment with one proposed idea and wait for approval before creating the usual model.py, agents.py, app.py, and README. Done means one small, self-contained example runs correctly, explains its Mesa commit, and demonstrates the selected event-driven behavior without step logic.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
developer-experience
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.