Missing Agent type hints

[EwoutH]

This issue is split of from feedback on the Mesa 3 JOSS paper.

Summary

Mesa uses type hints in its codebase, which is excellent for documentation and static type checking. However, there are gaps in how agent types are handled, which cause typing errors when running code in a strongly typed environment.

Problems:

1. model.agents returns an AgentSet[Agent] but doesn't maintain the specific agent subclass type information
2. When accessing self.model within an agent, the agent doesn't know about the model's specific type
3. Type checkers can't properly validate attribute access on agents retrieved from collections like model.agents

Reproducible examples:

Example 1: Type error when accessing agent attributes through model.agents

From the introductory tutorial in "Agents Exchange"/"Running your first model" section:

def step(self):
    if self.wealth > 0:
        other_agent = self.random.choice(self.model.agents)
        other_agent.wealth += 1  # Type error: 'Agent' has no attribute 'wealth'
        self.wealth -= 1

Example 2: Type error when accessing model attributes from agents

class MyAgent(Agent):
    def __init__(self, unique_id, model):
        super().__init__(model)
        
    def move(self):
        self.model.grid.move_agent(self, new_pos)  # Type error: 'Model' has no attribute 'grid'

Additional context

This would improve the experience for users working in typed environments or using IDEs with type checking capabilities like PyCharm, VSCode with Pylance, or running mypy on their code.

[mukulpythondev]

@EwoutH hi sir , Mukul Rana here having experience in web dev and python and currently working in US startup as full stack intern.
I am eager to contribute on this issue.
Looking forward to your response

[EwoutH]

@mukulpythondev Awesome! I assigned you, feel free to discuss a potential solution here before opening a PR if you want.

[adamamer20]

I remember running into a similar problem in mesa-frames

projectmesa/mesa-frames#12

I think using generics might work. The only limit I found was that generics do not work well with inheritance but this shouldn't be an issue in this case.

However handling multiple agent subtypes in a single model might prove difficult.

[mukulpythondev]

I am working on it soon raise the pr.

[mukulpythondev]

@EwoutH Thank you for assigning me this issue. I spent time understanding the codebase and working on improving type hinting in agent.py and models.py. The main challenges involved ensuring that model.agents retains the specific agent subclass type and that agents correctly recognize their model's concrete type. While I made progress in modifying generic type annotations and improving type safety in Agent, AgentSet, and Model, I encountered complexities in handling type inference within collections and attribute access in strongly typed environments.

Despite my efforts, I was unable to fully resolve the issue. However, this process has greatly helped me understand the project's architecture and type hinting best practices. I am now unassigning myself so that others can take it up. Thanks again for the opportunity!"

[EwoutH]

Thanks for your work, it's a difficult issue and glad you learned something for it.

If you have any further insights that might help a future contributor help understand this issue (or know what not to try), please share them!

[mukulpythondev]

Thank you! I really appreciate the opportunity to work on this. The main challenge was ensuring proper type inference in AgentSet and maintaining subclass types in model.agents. Future contributors might want to explore alternative ways to enforce type safety in collections while keeping backward compatibility. Happy to discuss further if needed!

[SiddharthBansal007]

Hey @EwoutH , is this issue still open. I would like to contribute and trying fixing this with the help of generic or typevar

[EwoutH]

Sure, go ahead. Please first validate if this issue still exists and we understand it correctly.