Add first mesa-llm model tutorial by niteshver · Pull Request #45 · mesa/mesa-llm

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.

🔍 Trigger a full review

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

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


Not necessary here, supported models are already in the docs

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

+```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

+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

+# 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

+            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

+## 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

+- 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.

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 · 2026-01-12T13:38:11Z

Hi @colinfrisch
I’ve updated the first model and negotiation tutorials following your suggestions, adding clearer explanations, more comments, and agent messaging.

niteshver · 2026-01-17T16:42:21Z

Hi @colinfrisch

I’m planning to work on a new mesa-llm example focused on opinion dynamics, where agents use language models to communicate while opinion updates.

The model would include:

Agents holding a numeric opinion on a single topic
LLM-generated messages exchanged between neighboring agents
Explicit trust updates (increase on agreement, decrease on disagreement)
A graph-based visualization showing opinion and trust evolution over time

Please let me know if this direction sounds appropriate before I start implementing it.

colinfrisch

Looks good to me !! @sanika-n what do you think about this tutorial (especially the negociation part)

* fix-prompt-gestion * fix-prompt-gestion align testing * fix dependencies

* fix-prompt-gestion * fix-prompt-gestion align testing

Bumps [actions/upload-artifact](https://github.com/actions/upload-artifact) from 5 to 6. - [Release notes](https://github.com/actions/upload-artifact/releases) - [Commits](actions/upload-artifact@v5...v6) --- updated-dependencies: - dependency-name: actions/upload-artifact dependency-version: '6' dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

Bumps [actions/cache](https://github.com/actions/cache) from 4 to 5. - [Release notes](https://github.com/actions/cache/releases) - [Changelog](https://github.com/actions/cache/blob/main/RELEASES.md) - [Commits](actions/cache@v4...v5) --- updated-dependencies: - dependency-name: actions/cache dependency-version: '5' dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

…#44)

- Implement _get_dialogue_history() to extract conversation from memory - Inject dialogue context into reasoning prompts - Support both STLTMemory and EpisodicMemory - Handle both agent objects (send_message) and IDs (speak_to tool) - Format senders as 'AgentType ID' for clarity - Limit to last 5 exchanges to manage context window Fixes agent amnesia in multi-turn negotiations where agents forgot previous offers and repeated themselves.

… iteration, remove debug prints

for more information, see https://pre-commit.ci

codecov · 2026-01-27T14:59:31Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.06%. Comparing base (1cd2e17) to head (9b3b969).
⚠️ Report is 52 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #45      +/-   ##
==========================================
+ Coverage   85.81%   86.06%   +0.24%     
==========================================
  Files          17       19       +2     
  Lines        1234     1320      +86     
==========================================
+ Hits         1059     1136      +77     
- Misses        175      184       +9

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

sanika-n · 2026-01-27T15:02:23Z

Great, thanks for making the changes. @colinfrisch , this PR looks good to me now:)

colinfrisch · 2026-01-27T16:16:15Z

Just merged ! Congrats @niteshver !

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

colinfrisch self-requested a review January 13, 2026 20:14

colinfrisch approved these changes Jan 19, 2026

View reviewed changes

sujalgawas and others added 23 commits January 27, 2026 20:03

runs with errors

1e0202a

fixed harvesting logic

40a0d53

final tests with gemini-2.5-flash-lite

736c207

Readme.md file added

9c71eec

readme.md

a28c0f2

Fix harvesting logic in tools.py

16773f8

review changes

a226dab

review 2

0a4f7c2

fix: treat ollama_chat as ollama provider (#43)

9010d70

link to readthedocs and small fixes

ad40aca

Fix and add dependencies (#49)

9ce8b0f

* fix-prompt-gestion * fix-prompt-gestion align testing * fix dependencies

Fix prompt gestion (#48)

4f89739

* fix-prompt-gestion * fix-prompt-gestion align testing

test: update module_llm tests for system prompt handling (None -> "") (…

366dae7

…#44)

test disabling Codecov upload

92dc472

test build

05c4022

testing id-token: write

2a28ae9

reset

15beed5

refactor: address code review feedback - remove duplication, optimize…

23e78c0

… iteration, remove debug prints

docs: minor fixes to first model and negotiation_model

61aad44

[pre-commit.ci] auto fixes from pre-commit.com hooks

9b3b969

for more information, see https://pre-commit.ci

sanika-n approved these changes Jan 27, 2026

View reviewed changes

colinfrisch merged commit bea0fe1 into mesa:main Jan 27, 2026
15 checks passed

wang-boyu added the docs Release notes label label Feb 12, 2026

wang-boyu mentioned this pull request Feb 25, 2026

reorganize readthedocs folder structure #92

Merged

Uh oh!

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!

niteshver commented Jan 12, 2026

Uh oh!

niteshver commented Jan 17, 2026

Uh oh!

colinfrisch left a comment

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

sanika-n commented Jan 27, 2026

Uh oh!

Uh oh!

colinfrisch commented Jan 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

coderabbitai Bot commented Dec 20, 2025 •

edited

Loading

niteshver commented Jan 6, 2026 •

edited

Loading

colinfrisch commented Jan 6, 2026 •

edited

Loading

codecov Bot commented Jan 27, 2026 •

edited

Loading