Update warehouse example to the new meta-agents API

[falloficaruss]

Note

This PR is a part of GSoC 2026 project "Hypergraph-Based Meta-Agents for Mesa"

Summary

This PR ports the warehouse example, the deliberate meta-agent creation showcase in mesa-examples from the removed experimental API (mesa.experimental.meta_agents.create_meta_agent) to the new backend-authoritative MetaAgents manager introduced in mesa/mesa#3811 (mesa.meta_agents).
mesa/mesa#3811 removes the old implementation outright (no shim), consistent with the Mesa 4.0 breaking-change window. The old API scattered membership state across live objects (meta_agent.constituting_agents, agent.meta_agent, get_constituting_agent_instance(...), assume_constituting_agent_*). The new API makes the model-level MetaAgents manager the single write path, with all memberships stored as (member, group, relation) triplets in a canonical incidence backend. This example is rewritten to exercise that public surface: deliberate creation with overlapping memberships, and member <--> group resolution through the manager instead of object pointers.

Changes

warehouse/model.py

• Imports MetaAgents from the new top-level mesa.meta_agents package (replaces mesa.experimental.meta_agents.meta_agent.create_meta_agent).
• Installs the manager once per model: self.meta_agents = MetaAgents(self) (and exposes self.membership_backend).
• Robots are now assembled via self.meta_agents.create("RobotAgent", [router, sensor, worker], CellAgent, ...) with:
  • meta_attributes: explicit group state: cell, status, path, item, carrying, loading_dock, charging_station (replaces the implicit assume_constituting_agent_attributes=True behavior, which no longer exists).
  • meta_methods: find_path, move, initiate_task, continue_task are thin delegators that resolve the responsible sub-agent through the manager via typed relations (members_of(robot, relation="router" | "sensor" | "worker")).
• memberships=[(router, "router"), (sensor, "sensor"), (worker, "worker")] overlapping relation labels recorded in the backend, demonstrating multi-role membership for the same agent–group pair set.
• The dynamically created robot class is tracked as model.robot_agent_type instead of the fragile type(model.RobotAgent) pattern called out in the old Readme; step() iterates self.agents_by_type[self.robot_agent_type] and no-ops gracefully if no robots exist.
• Adds WarehouseScenario (subclass of Scenario) with rows / cols / height, so warehouse size is a first-class model parameter; layout generation now uses the scenario dimensions and the model's rng for reproducible item codes.
• One robot is created per loading dock / charging station pair (zip(..., strict=True)).

warehouse/agents.py

• All self.meta_agent / get_constituting_agent_instance(...) lookups are replaced with backend-authoritative queries:
  • sub-agent -> its robot: model.meta_agents.groups_of(self)
  • robot -> sibling component: model.meta_agents.members_of(robot, relation=...)
• SensorAgent.move resolves its parent robot and the router member for obstacle re-routing; WorkerAgent.initiate_task / continue_task resolve router/sensor members for pathing and movement, with fallbacks to the robot's own meta_methods.
• Task completion now resets group state (path, item) so robots return to "open" cleanly.

warehouse/make_warehouse.py

• Compact default layout: 8×8×2 (was 22×20×4) with 2 loading docks and 2 charging stations (hence 2 robots), keeping the example quick to run and easy to visualize.
• make_warehouse() accepts an rng parameter; item codes are generated from the model's seeded RNG instead of the global random module.

app.py

• LOADING_DOCKS is now imported from make_warehouse.LOADING_DOCK_COORDS (single source of truth; no duplicated coordinate constants).
• Axis limits updated to the compact layout; robots are drawn via model.robot_agent_type, with a guard for robot_agent_type is None.

warehouse/init.py / Readme.md

• Package exports WarehouseModel and WarehouseScenario.
• Readme updated: robots assembled with MetaAgents.create + typed memberships; notes that the backend supports overlapping memberships (this example still uses one group per robot); robots tracked via model.robot_agent_type; layout/size/seed configuration documented; stale file descriptions fixed.
  Old -> new API mapping used in this example

Old	New
create_meta_agent(model, name, members, cls, ...)	model.meta_agents.create(name, members, cls, ...)
assume_constituting_agent_attributes=True	explicit meta_attributes={...}
assume_constituting_agent_methods=True	explicit meta_methods={...} delegating to typed members
agent.meta_agent	model.meta_agents.groups_of(agent)
meta_agent.get_constituting_agent_instance(Cls)	model.meta_agents.members_of(group, relation=...)
type(model.RobotAgent)	model.robot_agent_type

Behavior

• robots are assigned inventory tasks, A*-route to items (with obstacle re-routing via the sensor/router split), pick up, deliver to the loading dock, and return to open status. The visualization renders inventory and robot agents as before.
• Intentional visible change: the default warehouse is smaller (8×8×2, 2 robots) so the example runs fast and fits the Solara canvas without hardcoded 22×20 axis limits.

Dependencies / Merge Order

• Requires Meta-Agents Rewrite mesa#3811, should be merged after it.