Add first mesa-llm model tutorial #45

niteshver · 2025-12-20T18:31:42Z

This PR adds a new “first model” tutorial for mesa-llm, following the structure and level of detail of Mesa’s Creating Your First Model tutorial, but with content focused specifically on mesa-llm concepts.

What this tutorial covers

How mesa-llm integrates language-based reasoning into Mesa’s execution model
Defining a minimal language-driven agent that remains a standard Mesa agent
Using an LLM backend (Ollama with Llama 3) to replace rule-based decision logic
Keeping Mesa’s scheduling and lifecycle unchanged
Running and extending a simple language-reasoning model

Notes

Ollama is used as a lightweight local backend, but the design remains backend-agnostic.
The example is intentionally minimal to focus on core mesa-llm ideas rather than infrastructure.

I’ve addressed the feedback from the earlier review by:

aligning the structure and depth with Mesa’s first model tutorial,

I’d appreciate another review when you have time. Thanks!

coderabbitai · 2025-12-20T18:31:47Z

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.

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

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

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

niteshver · 2025-12-21T06:59:39Z

Hi @colinfrisch, I’ve created a Mesa LLM tutorial to help newcomers. Would appreciate you taking a look!

colinfrisch · 2025-12-25T16:00:36Z

Thanks a lot for your contribution, it's a very good start ! Could you make a model (and tutorial that would go with it) that would showcase the reasoning part a little more ?

Looking forward to review and merge this PR :)

niteshver · 2025-12-25T16:19:35Z

Hi @colinfrisch
Thanks a lot for the feedback, I’m glad the tutorial is heading in the right direction!

That makes sense — I’ll extend the model slightly to make the reasoning step more explicit (e.g. by prompting agents to reason about the situation before deciding on an action) and update the tutorial accordingly.

I’ll push an update shortly. Thanks again!

colinfrisch

Essentially, you have not used any code from the mesa-llm library here, please try to build a working model yourself to check out how this library works before contributing as this is supposed to be a tutorial for mesa-llm. Also please be careful what tools you use. An excessive use of AI can result in a temporary ban for the mesa ecosystem and have definitive consequences on GSoC.

colinfrisch · 2025-12-28T09:50:52Z

docs/first_model.md

+* OpenAI
+* Anthropic
+* xAI
+* Huggingface
+* Ollama
+* OpenRouter
+* NovitaAI
+* Gemini


Not necessary here, supported models are already in the docs

colinfrisch · 2025-12-28T09:57:14Z

docs/first_model.md

+```python
+import mesa_llm
+import mesa
+import ollama


We will add ollama dependency directly in mesa-llm. No need to put it here

colinfrisch · 2025-12-28T09:58:03Z

docs/first_model.md

+The generated response is treated as the agent’s reasoning output and printed directly, allowing us to observe how different agents interpret the same simulation context.
+The LanguageAgent class is created with the following code:
+```python
+class LanguageAgent(mesa.Agent):


The whole point of this tutorial is to use LLMAgent. Please refer to the existing example models to build your tutorial (also please do not use AI)

niteshver · 2026-01-02T05:32:42Z

Hi @colinfrisch
I’ve finalized the first model tutorial with a clear focus on LLMAgent and ReAct reasoning, keeping environments for later.
Please let me know if any further changes are needed

colinfrisch · 2026-01-02T18:58:04Z

Thank you, this is starting to look good ! Last step would be to make this a model that has a small purpose. What I suggest would be a small (and tutorial friendly) version of the negotiation model that you can find in the example folder of this repo

Of course, if you find something else that still showcases mesa-llm well and stays simple while being useful, I'm open to ideas :)

niteshver · 2026-01-03T04:11:50Z

Thank you for the feedback. I’ll go with a negotiation model, since I’m already familiar with this setup from the existing example and feel confident using it to clearly demonstrate how LLM agents reason and interact. I’ll keep the model small and tutorial-friendly while focusing on clarity and purpose

niteshver · 2026-01-06T05:48:19Z

Hi @colinfrisch
I’ve added a simplified negotiation tutorial inspired by the existing example.

Can I work on issue #31 while you review my PR?

colinfrisch · 2026-01-06T14:06:36Z

Yes of course, you can work on any subject you like (you can check out some prs that were opened and merged on #31). I'll review this one asap

colinfrisch

It's starting to look like something we could merge ! Little suggestions down below. Also, for the negotiation tutorial, I think that it would be the right place to demonstrate the messaging system between agents : if you can manage to make use of it and make it tutorial friendly, it would be great !

Last thing also : when you write code in your tutorials, don't hesitate to add a lot of comments to explain directly in the code the role of each function/method/attribute, etc.

colinfrisch · 2026-01-08T10:12:51Z

docs/first_model.md

+# Creating Your First mesa-llm Model
+
+## Tutorial Overview
+This tutorial introduces mesa-llm by walking through the construction of a simple language-driven agent model built on top of Mesa. Mesa-llm enables agents to reason using natural language while preserving Mesa’s standard execution model.


Suggested change

This tutorial introduces mesa-llm by walking through the construction of a simple language-driven agent model built on top of Mesa. Mesa-llm enables agents to reason using natural language while preserving Mesa’s standard execution model.

This tutorial introduces mesa-llm by walking through the construction of a simple language-driven agent model built on top of Mesa. Mesa-llm enables agents to reason using natural language while preserving Mesa’s standard execution model. If it's your first time using mesa, we suggest starting with the classic [creating your first model tutorials](https://mesa.readthedocs.io/latest/tutorials/0_first_model.html) before diving into mesa-llm.

colinfrisch · 2026-01-08T10:17:47Z

docs/first_model.md

+            selected_tools=[]
+        )
+
+        print(plan)
+```
+**Note on `selected_tools`:**  
+In this tutorial, `selected_tools=[]` indicates that the agent is reasoning
+without access to any external tools.


Since we don't use tools in this tutorial, we don't have to talk about it here. By default it's None so you can simply remove it. We will probably make a whole tutorial dedicated to it.

colinfrisch · 2026-01-08T10:21:53Z

docs/first_model.md

+## Create the Model
+The model manages agent creation and advances the simulation.
+
+mesa-llm provides the create_agents() helper, which correctly initializes agents and registers them with Mesa’s internal AgentSet. 


Mesa-LLM does not provide the create_agents() helper, it comes directly from the Mesa base ecosystem. LLMAgent is a wrapper of Agent (that is why we use super().__init__(*args, **kwargs) when initialising our agents). Also please use the ` quotes when you are talking about specific attributes or methods to explicitly show that it's code.

colinfrisch · 2026-01-08T10:24:22Z

docs/first_model.md

+- In this introductory tutorial, action suggestions are not executed.
+- Actions are shown only as part of the reasoning trace.
+- Environments and action execution are introduced in later tutorials.
+


could you maybe add a small exercise like in the mesa first model tutorial ?

thanks! I’ll add a small exercise section at the end of the tutorial, similar to Mesa’s first model tutorial.

docs/negotiation_model_tutorial.md

niteshver · 2026-01-08T14:40:55Z

Thanks for the clarification! I’ve updated the documentation to clearly state that create_agents() comes from Mesa, clarified the relationship between LLMAgent and Agent, and fixed code formatting using backticks.

niteshver added 5 commits December 19, 2025 10:34

created agent and model class

d0bd9c5

create agent and model with ollama

758fffe

correct terminal

e754392

some additional changes

04ba878

mesa_llm tutorial is now done

929aa45

Improve reasoning demonstration in introductory model tutorial

3e7bf45

colinfrisch requested changes Dec 28, 2025

View reviewed changes

finalize first mesa-llm model tutorial focused on LLMAgent

36e009d

niteshver added 3 commits January 6, 2026 11:07

Add tutorial-friendly negotiation model

ea40c3f

Minor cleanup

4af0212

Delete accidently created file

6868cc6

colinfrisch requested changes Jan 8, 2026

View reviewed changes

colinfrisch and others added 4 commits January 8, 2026 15:42

Update docs/negotiation_model_tutorial.md

74ae751

Add agent messaging and documentation fixes to negotiation tutor

ae71f9c

fix first_model & negotiation_model_tutorial

a808149

fix first model

5340c07

Uh oh!

Add first mesa-llm model tutorial #45

Are you sure you want to change the base?

Add first mesa-llm model tutorial #45

Conversation

niteshver commented Dec 20, 2025

What this tutorial covers

Notes

Uh oh!

coderabbitai bot commented Dec 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

niteshver commented Dec 21, 2025

Uh oh!

colinfrisch commented Dec 25, 2025

Uh oh!

niteshver commented Dec 25, 2025

Uh oh!

colinfrisch left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

niteshver commented Jan 2, 2026

Uh oh!

colinfrisch commented Jan 2, 2026

Uh oh!

niteshver commented Jan 3, 2026

Uh oh!

niteshver commented Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

colinfrisch commented Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

colinfrisch left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

niteshver commented Jan 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

coderabbitai bot commented Dec 20, 2025 •

edited

Loading

niteshver commented Jan 6, 2026 •

edited

Loading

colinfrisch commented Jan 6, 2026 •

edited

Loading