Skip to main content

Environment Design

This module is responsible for transforming a researcher's initial natural language idea into a structured, standardized simulation environment. Its core output is a detailed ODD (Overview, Design Concepts, Details) protocol and the corresponding directory structure.

Core Logic​

The environment design functionality is driven by the main script src/researcher/env_design.py. This script acts as a "coordinator," sequentially invoking a series of specialized Large Language Model agents (LLM Agents) to guide their collaboration in the process of converting a concept into a protocol.

Key Agents​

These agents are located in the src/researcher/env_design/ directory, each with a specific role:

  • InspirationAgent

    • Responsibility: Receives a broad research topic from the user (e.g., "the impact of social media on political polarization").
    • Output: Generates multiple specific, executable research questions and scenario concepts, providing a rich set of options for subsequent steps.

  • EvaluatorAgent

    • Responsibility: Evaluates the multiple scenarios generated by the InspirationAgent.
    • Evaluation Criteria: Primarily considers the relevance, feasibility, novelty, and potential impact of the research scenarios.
    • Output: Selects the scenario with the most research potential and provides a justification for the choice.

  • DetailerAgent

    • Responsibility: This is the core agent of this stage. It receives the scenario selected by the EvaluatorAgent.
    • Output: Expands the scenario into a very detailed ODD protocol, strictly adhering to the ODD specification. It generates the protocol in two formats (.md and .json) and extracts key scene information.

  • AssessorAgent (Optional)

    • Responsibility: Conducts a quality assessment of the ODD protocol generated by the DetailerAgent.
    • Evaluation Criteria: Checks the protocol for completeness, clarity, logical consistency, and operational feasibility.
    • Output: An assessment report that helps the researcher determine if the generated protocol meets the standards required for research.

Workflow and Outputs​

When you run the env_design.py script, the system performs the following steps:

  1. Receive Input: Gets the user-provided --topic and optional --scene_name.
  2. Create Directory: Creates a new directory named <scene_name> under the src/envs/ path to serve as the root directory for this simulation environment.
  3. Agent Collaboration: Executes the agent chain described above in sequence, with the output of each step serving as the input for the next.
  4. Save Results: All intermediate and final products are saved in the src/envs/<scene_name>/research/env_design/ directory.

Main Input:

  • --topic: A string describing the research interest.

Main Output Files:

  • src/envs/<scene_name>/scene_info.json: The most important output file. It contains the metadata for the entire environment, especially the complete ODD protocol stored in JSON format, which is used by the subsequent report generation module.
  • src/envs/<scene_name>/research/env_design/detailed_specification.md: The ODD protocol in Markdown format, which is highly readable and convenient for researchers to view and modify directly.
  • src/envs/<scene_name>/research/env_design/odd_protocol.json: A JSON format copy of the ODD protocol.
  • src/envs/<scene_name>/research/env_design/inspiration_output.json: The list of potential research questions generated by the InspirationAgent.
  • src/envs/<scene_name>/research/env_design/evaluator_output.json: The scenario selected by the EvaluatorAgent and its justification.
  • src/envs/<scene_name>/research/env_design/assessment_results.json (Optional): The assessment results for the ODD protocol from the AssessorAgent.

How to Use​

This module is primarily used via the command line. You need to provide a research topic and specify a scene name.

Basic Usage:

python src/researcher/env_design.py \
    --topic "Your research topic" \
    --scene_name "your_scene_name" \
    --model_name "gpt-4o"
  • --topic <string>: (Required) Your research topic.
  • --scene_name <string>: (Optional) The folder name for the environment. If not provided, one will be generated automatically.
  • --assess: (Optional) Perform a quality assessment on the ODD protocol after generation.
  • --save: (Optional) Save the intermediate output files from each agent.

For complete command-line and API examples, please go to Examples.