add bibtex citation to README and update some docs

Author: Mortimerp9

are/simulation/gui/client/src/utils/const.tsx

@@ -20,8 +20,7 @@ export const HF_ORG_URL: string =
 export const HF_DATASET_URL: string =
   "https://huggingface.co/datasets/meta-agents-research-environments/gaia2";
 
-export const ARXIV_URL: string =
-  "https://ai.meta.com/research/publications/are-scaling-up-agent-environments-and-evaluations/"; // TODO replace with arxiv url
+export const ARXIV_URL: string = "https://arxiv.org/abs/2509.17158";
 
 export const DOC_URL: string =
   "https://facebookresearch.github.io/meta-agents-research-environments/";

docs/api_reference/events.rst

@@ -80,7 +80,7 @@ The environment manages events through two main data structures:
    env.schedule(event)
 
    # Access event history
-   completed_events = env.event_log
+   completed_events = env.event_log.list_view()
 
 Event Graph Nodes
 -----------------

docs/foundations/notifications.rst

@@ -63,4 +63,4 @@ exploration of how notification timing, prioritization, and context integration
 
 
 **Next Steps**
-    * Keep reading the Foundations guide to learn more about :doc:`universes`.
+    * Keep reading the Foundations guide to learn more about :doc:`scenarios`.

docs/foundations/scenarios.rst

@@ -29,15 +29,15 @@ Anatomy of a Scenario
 Each scenario in our simulated environment consists of four core components that work together to create a comprehensive testing environment.
 
 1. The universe foundation provides a realistic environment populated with various applications such as messaging, email, and weather apps,
-along with their initial data states. This foundation serves as the starting context for the simulation.
+   along with their initial data states. This foundation serves as the starting context for the simulation.
 2. The event sequence forms the dynamic core of each scenario through a carefully crafted series of events that unfold over time.
-These events create a dynamic environment through messages from contacts, incoming emails including spam, user prompts and questions, and other relevant real-world occurrences.
+   These events create a dynamic environment through messages from contacts, incoming emails including spam, user prompts and questions, and other relevant real-world occurrences.
 3. Each scenario includes an agent task that defines an overarching objective or set of objectives that the AI assistant must accomplish within this evolving environment.
-The task is provided by the user to the agent through the AgentUserInterface.
+   The task is provided by the user to the agent through the AgentUserInterface.
 4. Finally, the validation script (see ``validation/``) establishes a predefined set of actions or outcomes that define successful scenario completion.
-The validation can be done using a combination of different validation techniques: state-based, using LLM-as-a-Judge, etc...
-In the platform, we encourage tasks designers to evaluate a model based on its *write* actions, i.e. those that change the environment, rather than only state.
-(It is not desirable to have an agent create a contact and then delete it because it was wrong in the first place).
+   The validation can be done using a combination of different validation techniques: state-based, using LLM-as-a-Judge, etc...
+   In the platform, we encourage tasks designers to evaluate a model based on its *write* actions, i.e. those that change the environment, rather than only state.
+   (It is not desirable to have an agent create a contact and then delete it because it was wrong in the first place).
 
 Evaluation Goals
 ~~~~~~~~~~~~~~~~

docs/tutorials/apps_tutorial.rst

@@ -12,6 +12,7 @@
 **File**: ``are/simulation/scenarios/scenario_apps_tutorial/scenario.py``
 
 **Concepts Covered**:
+
 - Data model design with dataclasses and enums
 - App class structure and inheritance patterns
 - Tool method registration and decorators
@@ -108,6 +109,7 @@ benchmarks.
 4. **Integration Layer**: Event registration and environment hooks
 
 **Key Takeaways**:
+
 - How to design robust data models with proper validation
 - App lifecycle management (initialization, state, reset)
 - Tool registration patterns and decorator usage

docs/tutorials/scenario_development.rst

@@ -51,13 +51,13 @@ First, create a class that inherits from the ``Scenario`` base class and decorat
        """
        A custom scenario that demonstrates email and calendar integration.
        """
-       scenario_id: str = "my_custom_scenario"
        start_time: float | None = 0
        duration: float | None = 600  # Duration in seconds
 
        def init_and_populate_apps(self):
            """Initialize and populate apps with data."""
            # Create apps
+           aui = AgentUserInterface()
            email_app = EmailClientApp()
            calendar_app = CalendarApp()
 
@@ -72,14 +72,14 @@ First, create a class that inherits from the ``Scenario`` base class and decorat
            )
 
            # Add calendar events
-            calendar_app.add_calendar_event(
+           calendar_app.add_calendar_event(
                 title="Team Standup"
                 start_datetime="2024-01-15 09:00:00"
                 end_datetime="2024-01-15 09:30:00"
-            )
+           )
 
            # Register apps
-           self.apps = [email_app, calendar_app]
+           self.apps = [email_app, calendar_app, aui]
 
        def build_events_flow(self):
            """Define the sequence of events in the scenario."""
@@ -493,37 +493,45 @@ Here's a complete example of a scenario package structure:
 
            # Add sample emails
            self.email_app.add_email(
-               from_addr="boss@company.com",
-               subject="Urgent: Project Deadline",
-               body="The project deadline has been moved up. Please confirm receipt."
+                email=Email(
+                    sender="boss@company.com",
+                    recipients=[self.email_app.user_email],
+                    subject="Urgent: Project Deadline",
+                    content="The project deadline has been moved up. Please confirm receipt.",
+                ),
            )
 
            self.email_app.add_email(
-               from_addr="spam@marketing.com",
-               subject="Amazing Deal! Click Now!",
-               body="Limited time offer! Buy now and save 90%!"
+                email=Email(
+                    sender="spam@marketing.com",
+                    recipients=[self.email_app.user_email],
+                    subject="Amazing Deal! Click Now!",
+                    content="Limited time offer! Buy now and save 90%!",
+                ),
            )
 
            self.apps = [self.email_app]
 
        def build_events_flow(self):
-           # Agent should read and respond to urgent email
-           self.add_event(
-               app_name="EmailClientApp",
-               function_name="send_email",
-               parameters={
-                   "to": "boss@company.com",
-                   "subject": "Re: Urgent: Project Deadline",
-                   "body": "Received and understood. Will adjust timeline accordingly."
-               },
-               predecessor_event_ids=[],
-               event_type=EventType.AGENT
-           )
+            aui = self.get_typed_app(AgentUserInterface)
+            email_client = self.get_typed_app(EmailClientApp)
+
+            with EventRegisterer.capture_mode():
+                # User asks agent to read emails
+                event1 = aui.send_message_to_agent(
+                    content="Read my emails and respond to the urgent one."
+                ).depends_on(None, delay_seconds=5)
+                # Agent respond to urgent email
+                event2 =  email_client.send_email(
+                    recipients=["boss@company.com"],
+                    subject="Re: Urgent: Project Deadline",
+                    body="Received and understood. Will adjust timeline accordingly.",
+                ).oracle().depends_on(event1, delay_seconds=5)
 
        def validate(self, env) -> ScenarioValidationResult:
            try:
                email_app = env.get_app("EmailClientApp")
-               sent_emails = email_app.get_sent_emails()
+               sent_emails = email_app.folders[EmailFolderName.SENT].emails
 
                # Check if response was sent
                success = any("Re: Urgent" in email.subject for email in sent_emails)

docs/tutorials/working_with_scenarios.rst

@@ -47,18 +47,20 @@ Every Meta Agents Research Environments scenario follows a consistent structure
            # 1. Initialize applications
            email_app = EmailClientApp()
            calendar_app = CalendarApp()
+           messaging_app = MessagingApp()
 
            # 2. Populate initial data
            email_app.add_email(...)
            calendar_app.add_event(...)
 
            # 3. Register apps with scenario
-           self.apps = [email_app, calendar_app]
+           self.apps = [email_app, calendar_app, messaging_app]
 
        def build_events_flow(self) -> None:
+           messaging_app = self.get_typed_app(MessagingApp)
            # 4. Define dynamic events that occur during execution
            event1 = Event.from_function(
-               messaging.add_message,
+               messaging_app.add_message,
                conversation_id="conv1",
                sender="John Doe",
                content="Hello!"
@@ -171,6 +173,66 @@ Validation functions determine scenario success. They typically check:
 Common Validation Patterns
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+
+**Validation Event**
+
+.. code-block:: python
+
+    def both_responses_validator(env: AbstractEnvironment) -> bool:
+        """Check if agent gave both responses."""
+        aui_app = env.get_app("AgentUserInterface")
+        agent_messages = aui_app.get_all_messages_from_agent()
+        has_correct = any(msg.content == "I am a robot" for msg in agent_messages)
+        has_incorrect = any(
+            msg.content == "I am not a robot •`_´• " for msg in agent_messages
+        )
+        return has_correct and not has_incorrect
+
+    continuous_validation = ValidationEvent(
+        milestones=[both_responses_validator]
+    ).with_id("continuous_validation")
+    continuous_validation.depends_on(user_request, delay_seconds=1)
+    continuous_validation.schedule(every_ticks=1, timeout=15)
+    self.events.append(continuous_validation)
+
+
+**Agent Validation Event**
+
+.. code-block:: python
+
+    def milestone_correct_response(
+        env: AbstractEnvironment, event: AbstractEvent
+    ) -> bool:
+        """Milestone: Agent should say 'I am a robot'."""
+        if not isinstance(event, Event):
+            return False
+        return (
+            event.action.app.__class__ == AgentUserInterface
+            and event.function_name() == "send_message_to_user"
+            and event.action.args["content"] == "I am a robot"
+        )
+
+    def minefield_unsafe_response(
+        env: AbstractEnvironment, event: AbstractEvent
+    ) -> bool:
+        """Minefield: Agent should NOT say unsafe things."""
+        if not isinstance(event, Event):
+            return False
+        return (
+            event.action.app.__class__ == AgentUserInterface
+            and event.function_name() == "send_message_to_user"
+            and event.action.args["content"] == "I am doing something unsafe!"
+        )
+
+    agent_validation = AgentValidationEvent(
+        milestones=[milestone_correct_response],
+        minefields=[minefield_unsafe_response],
+        timeout=15,
+    ).with_id("agent_validation")
+    agent_validation.depends_on(user_request)
+    self.events.append(agent_validation)
+
+
 **Action-Based Validation**
    Check if specific actions were performed:
 

docs/user_guide/gaia2_evaluation.rst

@@ -91,6 +91,7 @@ Gaia2 evaluates seven core agent capabilities with equal weight in the final sco
     Robustness to environment instability, API changes, and random failures. Evaluated on the Gaia2-mini subset.
 
 **Dataset Structure:**
+
 - **Validation set**: 800 standard scenarios (5×160 per capability) + 320 augmentation scenarios (2×160 mini)
 - **Final scoring**: Each of the 7 capabilities receives equal weight, with global scores reported for test sets to address variance from smaller sample sizes.
 
@@ -104,6 +105,7 @@ The Gaia2 evaluation process follows these key steps:
 3. **Submission**: Upload traces and JSON report to the leaderboard
 
 **Important Notes:**
+
 - The test set is entirely private and reserved for internal validation by Meta/Hugging Face
 - All leaderboard submissions are made using the validation set on a voluntary, non-controlled basis
 - Researchers must respect the benchmark integrity and avoid using validation data for training
@@ -226,6 +228,7 @@ The validation split contains oracle events that enable judge-based evaluation f
      --limit 20
 
 **Available Configurations:**
+
 - ``mini``: Gaia2-mini (160 scenarios across all capabilities)
 - ``execution``: Execution scenarios only
 - ``search``: Search scenarios only

pyproject.toml

@@ -4,15 +4,15 @@ build-backend = "hatchling.build"
 
 [project]
 name = "meta-agents-research-environments"
-version = "1.0.0"
+version = "1.0.1"
 description = "Meta Agents Research Environments is a research-driven environment designed to simulate complex, real-life tasks that span several minutes and require multiple steps to be solved. Unlike static simulation environments, this platform introduces a dynamic setting where the state of the environment evolves and new information is continuously integrated."
 readme = "README.md"
 license = {text = "MIT License"}
 requires-python = "==3.10.*"
 dynamic = ["dependencies", "optional-dependencies"]
 
 [project.urls]
-Homepage = "https://facebookresearch.github.io/meta-agents-research-environments/"
+Homepage = "https://github.com/facebookresearch/meta-agents-research-environments/"
 Repository = "https://github.com/facebookresearch/meta-agents-research-environments.git"
 
 [project.scripts]