Feat: Added Command Console

[Sahil-Chhoker]

Summary

Adds a command console in mesa as per #2683.
Closes #2683.

Implementation

This feature consists of four main classes:

1. ConsoleEntry: Defines how the data is entered into the console.
2. CaptureOutput: A context manager for capturing stdout and stderr output.
3. InteractiveConsole: A custom interactive Python console with output capturing capabilities. This class extends code.InteractiveConsole for a console like behaviour.
4. ConsoleManager: A console manager for executing Python code interactively. This class provides functionality to execute Python code in an interactive console environment, maintain command history, and handle multi-line code blocks.

For more information refer to the docstrings in the file.

Usage Examples

from mesa.visualization import CommandConsole
from .agents import myAgent
import numpy as np
import math

console_kwargs = {
    "additional_imports": { # additional imports to be used in command console
        "myAgent": myAgent,
        "np": np,
        "math": math,
    }
}

page = SolaraViz(
    model,
    components=[CommandConsole], # Pass the CommandConsole as a component
    model_params=model_params,
    name="Test Model",
    **console_kwargs
)
page

How it looks:

[github-actions]

Performance benchmarks:

Model	Size	Init time [95% CI]	Run time [95% CI]
BoltzmannWealth	small	🔵 +0.3% [-0.0%, +0.7%]	🔵 +0.6% [+0.5%, +0.8%]
BoltzmannWealth	large	🔵 +16.2% [-2.4%, +51.4%]	🔵 -0.5% [-1.4%, +0.2%]
Schelling	small	🔵 -0.0% [-0.2%, +0.2%]	🔵 -0.7% [-0.9%, -0.6%]
Schelling	large	🔵 -6.0% [-14.4%, -0.0%]	🔵 -1.6% [-2.3%, -0.9%]
WolfSheep	small	🔵 -0.1% [-0.3%, +0.1%]	🔵 -0.1% [-0.3%, +0.0%]
WolfSheep	large	🔵 +0.2% [-0.2%, +0.5%]	🔵 -0.4% [-1.1%, +0.3%]
BoidFlockers	small	🔵 -2.1% [-2.7%, -1.5%]	🔵 -0.3% [-0.5%, -0.2%]
BoidFlockers	large	🔵 -1.2% [-1.7%, -0.7%]	🔵 -0.3% [-0.4%, -0.1%]

[Sahil-Chhoker]

I would love to hear your thoughts on this, @quaquel.

[quaquel]

I think this is really nice.

Unfortunately, I don't have time to play around with it at the moment. However, I know you have been testing this extensively. I'll try to review soon, but I have various other obligations at the moment.

[quaquel]

Code looks clear and well documented. Great stuff!

I still want to try this myself before approving. Hopefully later today if all goes well.

[quaquel]

Started playing with it. I think it's great. Below is a WIP list of things I run into. Not all of this needs to be addressed in this PR.

1. Is it possible to "inherit" all imports from app.py? That is, populate the namespace of the console based on what is defined in the file from which the solara front end is started.
2. Great to have model readily available. This makes dynamically exploring the model easy.
3. It would make sense if the view jumps to the bottom after each command. Currently, I have to scroll down every time.
4. Is it possible to "force" and update of the display without calling model.step()? For example, If I update the wealth of an agent in the boltzmann wealth model, it would be nice if I see the color of an agent changing.
5. Currently, there are two windows: the console history and the line where you type new commands. Most consoles in IDE's integrate this into a single window where the last line is just where you type commands. Is something like this possible with this code base as well at some point in the future?
6. Discussion point: where to put the console? Currently, it is on the left-hand side, but this is getting quite crowded. I like the convention in most IDE's to have a console at the bottom right. How difficult would it be to do this at some point?
7. ...

[Sahil-Chhoker]

1. Is it possible to "inherit" all imports from app.py? That is, populate the namespace of the console based on what is defined in the file from which the solara front end is started.

Don't know yet, it doesn't seem very plausible because those are the imports we can't see. Will try to find a way.

2. Great to have model readily available. This makes dynamically exploring the model easy.

Glad to know.

3. It would make sense if the view jumps to the bottom after each command. Currently, I have to scroll down every time.

This feature makes sense, I will try to incorporate it.

4. Is it possible to "force" and update of the display without calling model.step()? For example, If I update the wealth of an agent in the boltzmann wealth model, it would be nice if I see the color of an agent changing.

I think I've added that already in the recent commits, I also realized that was very annoying, that's why I added force_update() after every execution. Can you please check if that line is there in your code?

5. Currently, there are two windows: the console history and the line where you type new commands. Most consoles in IDE's integrate this into a single window where the last line is just where you type commands. Is something like this possible with this code base as well at some point in the future?

Most likely possible, but I will have to go through the solara documentation thoroughly for that (because just adding the enter took long enough).

6. Discussion point: where to put the console? Currently, it is on the left-hand side, but this is getting quite crowded. I like the convention in most IDE's to have a console at the bottom right. How difficult would it be to do this at some point?

same as the answer in the 5th. Plus I would love to get this PR merged and look back at the code when implementing the variable explorer, because that will also take up some space.

[quaquel]

Thanks for the responses. None of these comments are blocking approval. They are merely a wishlist from my side.

1. Is what can be seen based on where you create the console?
2. Ok.
3. This would be the main thing to add if it is easy before merging
4. It is working, I just missed it. I do notice for boltzman that gini is not updated. I understand why given how all this is implemented, but for a future extension this would be nice to have (probably requires using some of the experimental signal stuff)
5. Ok
6. Ok
7. New wish: in most consoles, arrow key up gives you the last command. Is something like this available in code so that we can add support for the history of commands in the future?

[Sahil-Chhoker]

1. The model instance that is to be used is passed onto the SolaraViz, that can be directly used in the console environment but that is not the case with other imports in the app.py. There may be some kind of way there, if I search hard enough I may find it, but not soon.
2. .
3. I am working on it now. Just found a source after searching a bit. Will see if be able to do it in the next 2 hours, otherwise it will be postponed until tomorrow.
4. Ok
5. .
6. .
7. I also want that, but its not easy to make custom key handlers that's the main reason it is postponed until now. Will try to ask some friends that are more knowledgeable in the javascript web development field. That may act as reference. (but also for me its a must have). About the implementation I think just extracting the last command in the current buffer will work, so code module won't be needed.

[Sahil-Chhoker]

Auto-scrolling is implemented, simple fix I found was to use ChatBox from solara.lab which already contains this functionality.

[Corvince]

Thank you very much @quaquel for starting the review. I, too, wanted to try it out before reviewing this PR. But I still haven't found the time to dedust my local mesa workspace.

Thanks for the responses. None of these comments are blocking approval. They are merely a wishlist from my side.

This should be quite important. I think it would be good to take those (very good) ideas to a follow-up PR and try to merge this soonish. Its an awesome PR, I can already tell without doing a proper review right now.

[quaquel]

I am reviewing the code atm. One request: can you add the console stuff to /docs/apis/visualization.md? I am wondering if some of the docstrings will render correctly.

I don't see any other obvious things that should be changed and have tested the console locally, so I think this is almost ready to merge.

[Sahil-Chhoker]

One request: can you add the console stuff to /docs/apis/visualization.md? I am wondering if some of the docstrings will render correctly.

I don't know how the doc stuff works, should I add this?

\## Command Console

\```{eval-rst}
\.. automodule:: mesa.visualization.command_console
   :members:
   :undoc-members:
   :show-inheritance:
\```

ignore the '\'

[quaquel]

yes that should probably work

[quaquel]

2 minor doc comments, but otherwise good to go.

Amazing work!

[Sahil-Chhoker]

I will inform once I get the docs right, they seem a little off.

[Sahil-Chhoker]

Yeah docs look good now, its good to go!

[quaquel]

It would be good to open an overview issue with a wishlist of possible extensions based on the ideas discussed here.

[EwoutH]

Congratulations on getting this PR merged! Awesome feature already and really excited in what it can involve into!