Add Epstein Civil Violence Model full Tutorial

[niteshver]

Summary

This PR adds a simplified, beginner-friendly tutorial for the Epstein Civil Violence model

The goal is to help new users understand how LLM-powered agents work in an agent-based simulation, focusing on reasoning, tool usage, and agent interaction.

Key Features

• Demonstrates LLM-powered agents (Citizen and Cop)
• Shows how to create and use custom tools with ToolManager
• Explains agent reasoning using ReActReasoning

Improvements over Original Example

• Reduced number of agents for simplicity
• Removed SolaraViz UI to focus on core logic
• Added detailed explanations of:
  • Agent behavior
  • Arrest probability logic
  • Tool execution flow

This tutorial is designed to:

• Help beginners understand Mesa-LLM concepts
• Demonstrate hybrid modeling (rule-based + LLM reasoning)
• Provide a foundation for building more complex simulations
• Show how tool-based actions integrate with LLM agents

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 9fd4be94-07ab-4528-82b7-beb1d4290eaf

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 80f8d0f025

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Define cop tool manager before using arrest tool

The tutorial registers arrest_citizen with @tool(tool_manager=cop_tool_manager) but only initializes citizen_tool_manager earlier, so running this code as written raises a NameError at import time and prevents the example from starting. Add cop_tool_manager = ToolManager() alongside the citizen manager before this decorator.

Useful? React with 👍 / 👎.

[niteshver]

i have added

[chatgpt-codex-connector]

Enforce active-only precondition in arrest tool

arrest_citizen unconditionally sets the target to ARRESTED without checking that the target is an active citizen, which contradicts the model rule and can corrupt outcomes whenever the LLM selects this tool for a quiet citizen (the Cop LLM path still exposes arrest_citizen). This should validate both existence/type and CitizenState.ACTIVE before applying arrest effects.

Useful? React with 👍 / 👎.

[niteshver]

Hi @wang-boyu , @colinfrisch

I’ve created a PR adding a tutorial for the Epstein Civil Violence Model
Could you please take a look and share your feedback when you get time?

Thanks!

[gamal1osama]

Hi @niteshver, @wang-boyu I wanted to mention that I had a previous PR #87 that covered the same thing.

@colinfrisch just flagging this for visibility, since PR #87 was closed partly due to focus priorities at the time. Happy to collaborate or contribute if any part of my work is useful here!

if it ok we can reopen the pr again

[niteshver]

Hi @gamal1osama

I’ve created an advanced tutorial that includes adding custom tools. It’s aimed at helping new contributors understand Mesa-LLM concepts and learn how to effectively build and use tools.

I’d recommend taking a look at the negotiation_model tutorial as well before contributing. There are still a few Mesa-LLM concepts missing in this tutorial, so it would be great if you could help improve and expand it.

If you’re interested in contributing to this PR, feel free to collaborate and enhance it further. Any improvements or suggestions would be greatly appreciated!

[niteshver]

Hi @gamal1osama,

I reviewed your PR #87 and noticed that it primarily focuses on adding another model, but it doesn’t include explanations of core Mesa-LLM concepts or related components. Since tutorials are often the first touchpoint for new users, it would be beneficial to include more foundational explanations and structure it from a beginner’s perspective.

This could make the tutorial more accessible and helpful for newcomers to Mesa-LLM.