add: LLM Epidemic (SIR) model using Chain-of-Thought reasoning

[abhinavk0220]

Summary

A classic SIR (Susceptible-Infected-Recovered) epidemic simulation where agents use LLM Chain-of-Thought reasoning to decide their behavior during an outbreak — instead of following fixed stochastic transition probabilities.

Unlike traditional SIR models, agents reason about their situation — weighing personal health risk, observed neighbor states, and community responsibility — before deciding to isolate, move freely, or seek treatment.

The Disease Dynamics

Each agent is in one of three states:

Color	State	Behavior
🔵 Blue	Susceptible	Healthy, can be infected by neighbors
🔴 Red	Infected	Sick, reasons about isolation vs. movement
🟢 Green	Recovered	Immune, moves freely

What makes this different from classical SIR

Classical SIR uses fixed β (transmission rate) and γ (recovery rate). The epidemic curve is fully determined by two numbers.

Here, agents reason at each step:

"I am infected. My neighbors include susceptible individuals. Continuing to move freely risks spreading the disease. I should isolate — even though it limits my mobility — to protect the community."

This produces behavioral heterogeneity: some agents isolate immediately, others rationalize continued movement. The macro curve still follows SIR dynamics, but its shape reflects individual decision-making.

Visualization

Step 0 — Initial seeding (3 infected, 17 susceptible):

Step 3 — Epidemic accelerating (curves crossing):

Step 13 — Full SIR arc complete (all recovered):

Step	Susceptible	Infected	Recovered	Event
0	~17	~3	0	Initial seeding
1–2	Falling fast	Rising	0	Epidemic accelerating
3	~5	~18	~0	Near-peak — curves cross
5–7	~0	~20	~0	Saturation — everyone infected
10+	0	Falling	Rising	Recovery phase begins
13	0	~0	~20	Full recovery — epidemic over

Why this matters: This is the Kermack-McKendrick (1927) SIR curve reproduced with zero hardcoded β or γ parameters. The epidemic arc — seed → spread → peak → recovery — emerges entirely from LLM reasoning about individual health decisions. Classical SIR cannot represent individual behavioral variation at all.

How to Run

cp .env.example .env  # fill in your API key
pip install -r requirements.txt
solara run app.py

Supported LLM Providers

Gemini, OpenAI, Anthropic, Ollama (local) — configured via .env.

Reference

Kermack, W. O., & McKendrick, A. G. (1927). A contribution to the mathematical theory of epidemics. Proceedings of the Royal Society of London. Series A, 115(772), 700–721.

---

GSoC contributor checklist

Context & motivation

The SIR epidemic model is a foundational model in mathematical epidemiology. Adding LLM agents replaces fixed β/γ parameters with genuine behavioral reasoning — agents decide whether to isolate based on their health state, neighbor states, and sense of community responsibility. This produces a more realistic behavioral epidemic model than stochastic rule-based SIR.

What I learned

LLM agents reproduce the full Kermack-McKendrick SIR bell curve through reasoning alone — no hardcoded transmission or recovery probabilities. The curve emerges from 20 agents individually deciding how to behave at each step. The behavioral heterogeneity (some isolate, some don't) shapes the curve in ways that purely stochastic models can only approximate with population-level parameters.

Learning repo

🔗 My learning repo: https://github.com/abhinavk0220/GSoC-learning-space
🔗 Relevant model(s): https://github.com/abhinavk0220/GSoC-learning-space/tree/main/models/llm_epidemic

Readiness checks

• This PR addresses an agreed-upon problem (linked issue or discussion with maintainer approval), or is a small/trivial fix
• I have read the contributing guide and deprecation policy
• I have performed a self-review: I reviewed my own PR
• Another GSoC contributor has reviewed this PR:
• Tests pass locally
• Code is formatted (ruff check . --fix)
• Screenshots added showing live run output (Step 0, Step 3, Step 13)

AI Assistance Disclosure

This PR was developed with AI assistance (Claude) for code generation and debugging. All code has been reviewed, tested, and understood by the contributor.

---

Mesa Examples Review Checklist (#390)

Does it belong?

• No significant overlap with existing examples
• Well-scoped simplest model that demonstrates the idea
• Showcases Mesa features not already well-covered
• Showcases interesting ABM mechanics (LLM behavioral reasoning in epidemics)

Is it correct?

• Uses current Mesa APIs
• Runs and visualizes out of the box (requires API key — see .env.example)
• Deterministic with fixed rng seed — LLM outputs are non-deterministic by nature
• Moved to llm/ directory

Is it clean?

• No dead code or unused imports
• Clear naming, logic readable
• README explains what it does, what it demonstrates, how to run it
• PR follows template, commits reasonably clean

[EwoutH]

Thanks for the PR, looks like a cool model.

Could you:

• Checkout the test failure
• Add a screenshot or gif of the visualisation to the PR description
• Request a peer-review (and maybe do one or two yourself)

[abhinavk0220]

Thanks for the PR, looks like a cool model.

Could you:

• Checkout the test failure
• Add a screenshot or gif of the visualisation to the PR description
• Request a peer-review (and maybe do one or two yourself)

Thanks @EwoutH! The test failure is ModuleNotFoundError: No module named 'mesa_llm' mesa_llm isn't installed in the CI environment.
Is the right fix to add it to the CI dependencies, or should LLM
examples be excluded from the standard test run like GIS examples?

Will add a screenshot and move to llm/ directory. Also just left
a peer review on #384 and looking for a reviewer in return.

[abhinavk0220]

Thanks for the PR, looks like a cool model.

Could you:

• Checkout the test failure
• Add a screenshot or gif of the visualisation to the PR description
• Request a peer-review (and maybe do one or two yourself)

Hi @EwoutH! Updates done:

• Screenshot added showing the spatial grid and SIR curves
• Moved to llm/ directory
• CI failure resolved
• Peer review done on Add misinformation spread model with LLM and rule-based agents #384

READY TO MERGE !!!!!

[savirpatil]

Hi @abhinavk0220,

Does it belong?
The LLM-reasoning angle is a genuine differentiator from classical SIR models and justifies its place in the repo. To my knowledge, the infection logic in _update_health checks all agents globally rather than using the spatial grid. The concept is strong, but this one intended mechanic is not fully used in the current implementation.

Is it correct and current?
The model uses current Mesa APIs throughout, OrthogonalMooreGrid, DataCollector, and SolaraViz are all up to date and no deprecated patterns were spotted.

Is it clean?
The code is well-named and straightforward to follow. The README is clear and well-written, with a proper citation to Kermack & McKendrick (1927). One loose end I found was that the vision=2 parameter is set but has no effect on the health logic.

Using LLM Chain-of-Thought reasoning to replace fixed SIR transition probabilities is a genuinely inventive idea, and the way it is framed shows real understanding of what makes this approach interesting. I also liked how the README clearly explains the motivation, draws a thoughtful distinction from classical models, and includes a proper academic reference. Once the few issues flagged above are resolved, this will definitely be a strong addition to the examples.

[abhinavk0220]

Thanks @savirpatil for the thorough review both points are accurate and I appreciate you catching them.

On global infection check vs. spatial proximity:

You're right _update_health was iterating over self.model.agents globally, making the spatial grid decorative. Fixed in the latest commit: infection now checks self.cell.connections.values() (immediate Moore neighbors, radius=1) instead of all agents. An isolating agent in one corner of the grid can no longer infect a susceptible agent on the other side.

The infection probability per neighbor was raised from 0.1 to 0.3 to maintain realistic epidemic dynamics with the smaller spatial neighbor count (max 8 cells vs. the full population).

On vision=2 being unused in health logic:

This is intentional by design vision=2 controls what the LLM observes (wider situational awareness for reasoning), while infection radius=1 reflects direct physical contact. An agent can see farther than it can infect, which is more realistic. The comment in the code now documents this distinction explicitly.

Both issues resolved in: b4bc7d2