Move state mutating tools to actions

[wang-boyu]

Partly addresses #148.

This PR is stacked on #311.

Summary

This PR migrates the existing state-changing built-ins from tools to actions. move_one_step, teleport_to_location, and speak_to now execute through the action path, and examples are updated to configure and call committed behavior with actions= / act(...).

Motive

State-changing simulation behavior should not depend on provider tool calls. With the action core in place, movement and messaging can be validated and executed locally as actions, while tool factories remain reserved for read-only deliberation helpers.

Implementation

• Moved move_one_step, teleport_to_location, and speak_to into mesa_llm.actions.
• Added action-set factories: default_actions() returns only wait, spatial_actions() returns movement actions, and social_actions() returns speak_to.
• Removed migrated mutating built-ins from public tool exports and tool factory helpers.
• Removed legacy_tools() as a forward migration path; read-only tool factories currently return empty tuples.
• Added validation coverage for migrated action schemas, argument coercion, validation-before-mutation, movement behavior, messaging behavior, and tool export removal.
• Added async action workflow support used by migrated examples.
• Updated Epstein civil violence, negotiation, and Sugarscape examples to use actions.py, actions=, act(...), and aact(...).
• Hardened action selection for local/reasoning-style models by requesting exactly one JSON object, suppressing hidden reasoning where supported, parsing a single embedded/fenced JSON object, and rejecting ambiguous outputs.

Usage Examples

from mesa_llm.actions import social_actions, spatial_actions
from mesa_llm.llm_agent import LLMAgent
from mesa_llm.reasoning.cot import CoTReasoning

agent = LLMAgent(
    model=model,
    reasoning=CoTReasoning,
    tools=None,
    actions=[*spatial_actions(), *social_actions()],
)

agent.act(
    prompt="Move one step north if that is useful this turn.",
    actions=["move_one_step"],
)

from mesa_llm.actions import teleport_to_location
from mesa_llm.llm_agent import LLMAgent
from mesa_llm.reasoning.cot import CoTReasoning

agent = LLMAgent(
    model=model,
    reasoning=CoTReasoning,
    actions=[teleport_to_location],
)

agent.execute_action(
    {
        "name": "teleport_to_location",
        "arguments": {"target_coordinates": [2, 3]},
    }
)

[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 Plus

Run ID: 7ace6025-ffae-43da-bbd1-d0ef09a0663c

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
• Commit unit tests in branch refactor/mutate-tools-to-actions

---

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

[codecov]

Codecov Report

❌ Patch coverage is 95.40230% with 16 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.15%. Comparing base (500d817) to head (d9a3b0e).

Files with missing lines	Patch %	Lines
mesa_llm/llm_agent.py	91.25%	7 Missing ⚠️
mesa_llm/actions/builtins.py	94.73%	4 Missing ⚠️
mesa_llm/actions/action_decorator.py	96.92%	2 Missing ⚠️
mesa_llm/actions/action_manager.py	97.26%	2 Missing ⚠️
mesa_llm/parallel_stepping.py	87.50%	1 Missing ⚠️

Additional details and impacted files

@@                    Coverage Diff                    @@
##           refactor/actions-core     #312      +/-   ##
=========================================================
+ Coverage                  88.86%   91.15%   +2.28%     
=========================================================
  Files                         26       25       -1     
  Lines                       2344     2600     +256     
=========================================================
+ Hits                        2083     2370     +287     
+ Misses                       261      230      -31     

☔ View full report in Codecov by Harness.
📢 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.