How allenai/scienceworld works
Main Components
• Simulator Engine (Scala):
• Located inside the “simulator” directory.
• Contains the core logic for parsing, modeling, and executing simulation tasks. This includes language parsers, runtime execution (interpreter, runners, etc.), task definitions, actions, and object models.
• Built using sbt and compiled into a JAR (as mentioned in README and evidenced by build.sbt, package.sh, etc.).
• Python API/Interface:
• Present in the “scienceworld” Python package that helps in managing the simulation environment.
• Uses Py4J to bridge between Python and the Scala simulation engine running on Java.
• Provides convenient functions such as “env.load()” for task setup.
• Example Clients and Agents:
• Found in the “examples” directory (e.g., human.py, random_agent.py, scienceworld-web-server-example.py).
• Demonstrate different modes of interacting with the system (command-line agent, web server).
• Supporting Components:
• “goldpaths” for example execution pathways.
• Build and configuration files (e.g., setup.py, requirements.txt, .github workflows) show development, continuous integration, and packaging processes.
• Testing scripts in “tests” ensure functionality of the system.
Relationships and Interactions
• The simulation engine (Scala/Java) serves as the core computational unit.
• The Python API acts as the mediator: it invokes methods that span across the simulation JAR using Py4J, enabling users (or demo agents) written in Python to start and control simulation episodes.
• Example agents (random agent, human console, web demo) serve as front-end clients that send commands and receive simulation outcomes.
• The web server demo uses the same Python API and underlying engine but is wrapped in a service (accessible via a browser) to handle HTTP requests and update the interface.
• Build and packaging scripts ensure that changes in Scala code get compiled into a JAR and are correctly used by the Python API.
Architectural Patterns and Design Principles
• Language Interoperability Pattern:
• Scala for the heavy computation and simulation engine.
• Python as the user-friendly interface layer.
• Communication is via Py4J, which abstracts away language boundaries.
• Modular Design:
• Clear separation between simulation engine, API layer, and client demos.
• Tasks and actions are defined in distinct packages, facilitating extensibility.
• Build-Oriented Design:
• Use of sbt for the Scala part and setup.py with pip for the Python package interface.
• Client-Server (or agent-based) interaction:
• Agents interact with the simulation environment either via console, scripted agents, or a web interface.