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

[abhinavk0220]

Summary

Adds 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 fixed stochastic transition
probabilities.

How this differs from similar epidemic models (e.g. #359)

PR #359 adds a deterministic pathogen model with fixed quarantine
and compliance rules agents follow predefined behavioral rules
based on parameters.

This model takes a fundamentally different approach: agents have
no fixed rules. Instead they use LLM Chain-of-Thought reasoning
to decide whether to isolate, move freely, or seek treatment at
each step based on what they observe around them.

The distinction matters because:

• Fixed-rule models are faster and reproducible
• LLM-reasoning models produce emergent behavioral heterogeneity
  that fixed parameters cannot capture

Both approaches are valid — they answer different research questions.

What makes this different from a classical SIR model

In a standard SIR model, infection and recovery are governed by fixed
probabilities (β and γ). Here, agents reason about their situation
at each step observing neighbor health states, weighing personal risk
against community responsibility and choose an action:

• isolate : Stay home, reduce infection risk, slower social life
• move_freely : Normal activity, higher transmission risk
• seek_treatment : If infected, accelerate recovery

This produces epidemic curves shaped by emergent behavioral responses
rather than fixed parameters, demonstrating how LLM-powered agents can
model nuanced human decision-making during crises.

Visualization

• Spatial grid with agents color-coded by health state:
  • 🔵 Blue = Susceptible
  • 🔴 Red = Infected
  • 🟢 Green = Recovered
  • ○ Circle = moving freely, □ Square = isolating
• Real-time SIR plot tracking population counts over time

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.
A .env.example is included for easy setup.

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.