# allenai/scienceworld architecture

> Architecture diagram of the GitHub repository allenai/scienceworld, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/allenai/scienceworld
- Repository: https://github.com/allenai/scienceworld

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Agents"
        H("Human Agent (CLI)"):::clients
        R("Random Agent (CLI)"):::clients
        W("Web Server Demo Agent"):::clients
    end

    subgraph "Middleware Layer"
        PY("Python API/Wrapper (Py4J)"):::middleware
    end

    subgraph "Simulator Engine (Scala/JVM)"
        L("Language Parsers"):::backend
        RE("Runtime Executor"):::backend
        TA("Task & Action Manager"):::backend
        L --> RE --> TA
    end

    B("Build & Packaging Scripts"):::support
    G("Goldpaths"):::support

    H -->|"sendsCommands"| PY
    R -->|"sendsCommands"| PY
    W -->|"sendsCommands"| PY

    PY -->|"invokesSimulation"| L

    B -->|"buildsPackages"| L
    G -->|"validatesTasks"| TA

    TA -->|"returnsResults"| PY
    PY -->|"deliversOutcomes"| H
    PY -->|"deliversOutcomes"| R
    PY -->|"deliversOutcomes"| W

    click L "https://github.com/allenai/scienceworld/tree/main/simulator/src/main/scala"
    click B "https://github.com/allenai/scienceworld/blob/main/simulator/package.sh"
    click PY "https://github.com/allenai/scienceworld/blob/main/scienceworld/scienceworld.py"
    click H "https://github.com/allenai/scienceworld/blob/main/examples/human.py"
    click R "https://github.com/allenai/scienceworld/blob/main/examples/random_agent.py"
    click W "https://github.com/allenai/scienceworld/blob/main/examples/scienceworld-web-server-example.py"
    click G "https://github.com/allenai/scienceworld/tree/main/goldpaths/"

    classDef backend fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef middleware fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef clients fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef support fill:#D7BDE2,stroke:#8E44AD,stroke-width:2px;
```
