Tool: SIR Epidemiological Model Simulator

[rmarcacini]

Objective

Develop a new Tool for the Agents4Gov (LABIC – ICMC/USP) project that implements a SIR (Susceptible–Infectious–Recovered) epidemiological model simulation, based on standard differential-equation formulations.

The goal is to enable users in public-service contexts to simulate disease spread scenarios under different parameters (infection rate, recovery rate, initial populations) and analyse outcomes such as peak infections, duration, and recovered count.

Optional: Based on the reference implementation described here:
https://scientific-python.readthedocs.io/en/latest/notebooks_rst/3_Ordinary_Differential_Equations/02_Examples/Epidemic_model_SIR.html

---

Description

The SIR Model Simulator Tool must support the following workflow:

1. Input Parameters

   • Total population size (N)
   • Initial number of infected individuals (I₀)
   • Initial number of recovered individuals (R₀)
   • Transmission rate (β)
   • Recovery rate (γ)
   • Simulation period (e.g., days)
   • Time step or resolution (optional)
   • Optional: intervention effect modifier (e.g., reduced β after a given day)

2. Model Execution

   • Use the classic SIR differential equations:

     dS/dt = –β * S * I / N  
     dI/dt = β * S * I / N – γ * I  
     dR/dt = γ * I
     

   • Integrate over the specified simulation period (e.g., using scipy.integrate.odeint or equivalent).
   • Compute time-series results for S(t), I(t), R(t).

3. Output / Analysis

   • Provide time-series data for each compartment (S, I, R) at each timestep.
   • Compute key metrics:
     • Peak number of infected and the time at which it occurs.
     • Total number recovered by end of simulation.
     • Duration until infection drops below a threshold (e.g., I(t) < 1).
   • Optional: Apply a simple scenario comparison (e.g., with and without intervention) and highlight differences.

4. Presentation

   • Return structured JSON output including parameter settings, key metrics, and optionally sampled time-series arrays.
   • Provide a brief interpretive summary text (e.g., “Under the given parameters, the epidemic peak occurs at day 35 with ~12 % of population infected.”).

---

Expected Behavior (User Flow)

1. User opens Open WebUI → Tools → SIR Model Simulator.
2. User enters the simulation parameters (N, I₀, R₀, β, γ, period) via LLM/Agent chat interaction.
3. The tool runs the model.
4. The tool returns:
   • JSON output with all metrics and time-series summary.
   • A short textual summary of key findings.
   • If enabled, a plot visualization.
5. User can modify parameters and rerun to compare scenarios.

---

Configuration

• Valve name: llm_sir_explainer
  • If configured, the Valve uses a local LLM to interpret the scenario results (e.g., describing what the parameters imply, recommending public-health ideas).
• Dependencies: numpy, scipy, matplotlib (or plotly), pandas (optional)
• Data size consideration: The time-series length should be suitable for UI performance (e.g., limit max timesteps to 1,000).
• Parameter validation: Ensure β, γ > 0, N > I₀ + R₀, etc. Provide informative error messages if invalid.

---

Deliverables

• New folder: tools/sir_model_simulator/
  • main.py – tool logic for SIR model simulation
  • README.md – usage and configuration guide
  • requirements.txt – dependencies (numpy, scipy, matplotlib)
  • Optional: test_sir_model.py – basic sanity tests
• Update docs/README.md with reference to this tool
• Add documentation explaining parameter definitions and assumptions (in tool README)

---

Acceptance Criteria

• The tool accepts user-defined parameters (N, I₀, R₀, β, γ, period) in Open WebUI
• Runs the SIR model and returns correct time-series and key metrics
• Returns JSON output suitable for downstream usage in UI or APIs
• (If enabled) Includes a plot/visualization of the epidemic curves
• Works when imported into Open WebUI and is accessible via Tools module
• Provides clear error handling and parameter validation

[rmarcacini]

@DeguShi , fiz um caso de teste na tool e parece ok. Pode verificar se está tudo certo com base na execução anexada?

chat-🛠️ SEIR Simulation Tools.pdf

Reabri a issue apenas para que possa avaliar se faz sentido a tool incorporar os gráficos via mermaid js (que é renderizado automaticamente no agents4gov, conforme dados enviados como um bloco markdown):
https://github.com/mermaid-js/mermaid

[DeguShi]

Boa tarde, Professor @rmarcacini!
Claro, assim que eu conseguir analisar melhor o que eu preciso mudar para incluir essa opção gráfica lhe dou um retorno. Quanto a execução que o senhor mandou, parece tudo certo. A ideia é que a tool também disponibilize o json completo, e não apenas o resumo, para permitir a plotagem com a implementação atual, mas isso pode ser melhorado caso necessário.

[rmarcacini]

O JSON completo vem sim, como respota da tool. O LLM que resumiu só pra mostrar na interface, mas em uma chamada via API, teria acesso normalmente. Não mudaria nada disso, pois ajudará na integração com outros módulos no futuro.

Sobre a parte de gráficos, no seu PR tinha gráficos interessantes resultantes da modelagem. Como há dificuldade em importar as imagens geradas por matplotlib da tool na interface web, uma opção seria gerar o gráfico em formato mermaid/markdown, que é nativamente gerado. No entanto, não é algo prioritário ou de fato requisito. Podemos fazer a tool gerar um relatório em PDF mesmo, com template pré-definido, registrar em algum serviço de documentos, obter o link e apresentar pro usuário, junto com o JSON também. Isso no futuro, por hora, não vejo necessidade.

[DeguShi]

Sim sim, eu realmente acho que colocar os gráficos é bastante importante. Inicialmente eu havia colocado diretamente na tool essa possibilidade de plotar, porém me deparei com a incompatibilidade entre as bibliotecas que eu usei e a interface web, como o senhor falou. Atualmente, eu estou usando um script separado para o plot, vou ver se consigo reproduzir ao máximo a saída dele com essa alternativa em markdown, acredito que até amanhã de tarde eu tenha algo funcionando nesse sentido, ai abro um PR para o senhor dar uma olhada.